image
Akan.js
English
DocsConventionsReferencesCheatsheet
image
Akan.js
Akan.js v2 docs are now available.View the v1 docs
DocsConventionsReferencesCheatsheet
Released under the MIT License
Official Akan.js Consulting onAkansoft
Copyright © 2026 Akan.js All rights reserved.
System managed bybassman
Introduction
• Quick Start
• Fundamentals
• Practice
Tutorials
• Show Details
• Modifying Status
• Interact in Service
• Displaying with Slice
• UX with Pages
• Using Scalar
• Using Insight
• Relate Data
Core Concepts
• Akan Runtime
• File Based Routing
• Multi Client
• App Config
• Folder Rule
• File Rule
• Data Layer
System Architecture
• Architecture Overview
• Runtime And Infra
• UI Architecture
• Business Service
• Mobile App Architecture
• CSS And Styling
Introduction
• Quick Start
• Fundamentals
• Practice
Tutorials
• Show Details
• Modifying Status
• Interact in Service
• Displaying with Slice
• UX with Pages
• Using Scalar
• Using Insight
• Relate Data
Core Concepts
• Akan Runtime
• File Based Routing
• Multi Client
• App Config
• Folder Rule
• File Rule
• Data Layer
System Architecture
• Architecture Overview
• Runtime And Infra
• UI Architecture
• Business Service
• Mobile App Architecture
• CSS And Styling
Previous
Akan Runtime
Next
Multi Client

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
to
/:lang/project/:projectId
The index file becomes the route endpoint.
Layout file
page/(user)/project/[projectId]/_layout.tsx
to
wraps child pages
The layout wraps pages below the same folder.
Route group
(user)
to
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 head example
default
The page component. This is required.
pageConfig
Client page options such as transition or mobile safe-area behavior.
head
Static metadata for the page.
generateHead
Dynamic metadata that can use route params.
Loading
Fallback UI shown while the page is loading.
Use either head or generateHead, not both. Use head for fixed metadata and generateHead when the title or tags depend on params.

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, head, generateHead, and Loading. Layout's head is used for child pages without head declaration.

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/seon/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, 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.
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, head, generateHead, and Loading.
File Based Routing
File Convention
Page File Shape
Layout File Shape
Base Paths
Root Layout Exports