File Based Routing

Akan uses file-based routing. You create files under page/, and the folder structure becomes the page URL. Most pages also get a language parameter automatically, so the same file can serve localized URLs.

How files become routes

Page file

page/(user)/project/[projectId]/_index.tsx

/:lang/project/:projectId

The index file becomes the route endpoint.

Layout file

page/(user)/project/[projectId]/_layout.tsx

wraps child pages

The layout wraps pages below the same folder.

Route group

(user)

not in URL

Parentheses organize files without adding a URL segment.

File-based: Folders and files decide the URL shape.

Locale-aware: Akan injects [lang] automatically.

Explicit files: Use page and layout files instead of hidden magic.

File Convention

A route file can be a page or a layout. _index.tsx renders the current segment, _layout.tsx wraps child segments, and route groups organize files without changing the URL.

page/

_index.tsx

Page for the folder it lives in.

_layout.tsx

Layout that wraps child pages below it.

(group)

Organizes files without adding a URL segment.

<path>.tsx

Single-file page for a path segment. project.tsx becomes /:lang/project.

[<param>].tsx

Single-file dynamic page. [projectId].tsx becomes /:lang/:projectId.

Page File Shape

A page file must export a default component. It can also export optional helpers for page options, metadata, and loading UI.

page/(user)/project/[projectId]/_index.tsx

Static metadata example

default

The page component. This is required.

pageConfig

Client page options such as transition or mobile safe-area behavior.

metadata

Declarative static metadata for title, description, robots, Open Graph, Twitter, canonical, and language alternates.

generateMetadata

Dynamic declarative metadata that can use route params and search params.

head / generateHead

Escape hatch for custom JSX head elements when declarative metadata is not enough.

Fallback UI shown while the page is loading.

Use one metadata API per route module: metadata or generateMetadata. Do not mix metadata/generateMetadata with head/generateHead. Metadata is not merged across layouts and pages; the nearest route module wins.

Layout File Shape

A layout file wraps child pages. Use it for shared headers, tabs, sidebars, guards, or page-level shells.

page/(user)/project/[projectId]/_layout.tsx

Layouts support default, metadata, generateMetadata, head, generateHead, Loading, NotFound, and Error. Layout metadata is used for child pages without their own metadata/head declaration, and the nearest layout fallback renders when a child route is missing or fails.

NotFound

Layout-scoped 404 UI. It renders under the layout when a child route is missing or router.notFound() is called below it.

Error

Layout-scoped server render error UI. It renders under the nearest layout when a child route throws during SSR.

Custom NotFound and Error exports are available on _layout.tsx files, not page files. If a layout does not export one, Akan walks up to the nearest parent layout fallback, then falls back to the framework system page.

Base Paths

When an app defines base paths in akan.config.ts, page files must live under one of those base path folders. This keeps multi-service or multi-domain apps explicit.

apps/myapp/akan.config.ts

page/

If base paths are configured, putting a page directly under page/ is invalid. Move it under page/<basePath>/ so Akan can tell which route group owns it.

Root Layout Exports

The root _layout.tsx can configure app-wide behavior. It is still a layout, but it may also export extra values for fonts, manifest, theme, realtime connection, analytics, and mobile-style rendering.

page/_layout.tsx

fonts

Registers app-wide fonts so pages can use them consistently.

manifest

Defines the web app manifest used for installable/PWA-like behavior.

theme

Chooses the default theme policy, such as dark, light, system, or css.

reconnect

Controls whether the client tries to reconnect to realtime runtime channels.

wsConnect

Controls whether the browser connects the client WebSocket runtime after load. The default is true. If false, message/pubsub calls warn in the browser console until fetch.instance.connect() is called.

layoutStyle

Switches the outer page container style. Use mobile for app-like mobile shells.

gaTrackingId

Adds Google Analytics tracking for the app.

These extra exports are for root layouts only. Normal nested layouts should stay focused on default, metadata, generateMetadata, and Loading.