Quick Start

This guide gets you from an empty directory to a running Akan application.

Along the way, you will see the Akan way: describe business intent once, then let conventions connect pages, APIs, services, stores, data, and deployment surfaces.

Akan.js is monorepo-native. App execution, production builds, library development, and package management all happen from the workspace root.

After reading this guide, you will know how to create a workspace, start the local runtime, find the first files to edit, and build the app for production.

Requirements

For the first run, Bun is the only required dependency. Docker and native IDEs become useful when you add local services or mobile builds.

Bun 1.3.13 or higher

Docker for local database services

Android Studio or Xcode for native app builds

Create a Workspace

Start with the workspace creator. It asks a few questions, then lays out the monorepo conventions Akan uses for apps, libraries, pages, and domain modules.

Run terminal commands without copying the leading prompt symbol.

Terminal

If you prefer a globally installed CLI, the same lifecycle is available through the akan command.

Terminal

Run the App

Start the local Akan runtime with one command. It scans the workspace, reads the conventions, prepares generated artifacts, and opens the app.

Terminal

By default, the local gateway listens on http://localhost:8282. Pages, API calls, WebSocket traffic, and generated assets all flow through this runtime.

Now the app is running through the Akan gateway. Edit a page and the same workspace can serve web, app-oriented client surfaces, API traffic, realtime traffic, and generated assets.

Edit a page

Akan pages live under apps/<app>/page. Index pages use the _index.tsx convention, so the first screen of myapp is apps/myapp/page/_index.tsx.

Change the component and refresh the local gateway to confirm your first UI change.

apps/myapp/page/_index.tsx

Open http://localhost:8282 to see the page through the Akan gateway.

The runtime uses the same page convention for the surfaces Akan builds, so you work in one page tree instead of maintaining separate client projects.

Hello Akan.js! 🎉

Know the app entry

The generated main.ts starts the Akan runtime. Most application work happens in pages and domain modules, so you rarely need to edit this file.

apps/myapp/main.ts

When akan start is running, the terminal shows the local runtime status. Use the gateway URL for pages and generated runtime surfaces.

Terminal

Build

When the app is ready to ship, build it with the same conventions. Akan generates the server artifact, route manifests, client entries, static assets, and package metadata needed for production.

Terminal

The production build result is generated in the dist/apps/myapp directory.