DOCSEARCHbyAlgolia
Submit Docs

Akan.js Framework

repository·main·Indexed 43 days ago

https://github.com/akan-team/akanjs

A Bun-first, full-stack TypeScript framework that allows developers to write business logic once and compile it into web (SEO-optimized), mobile (iOS/Android), server, and database layers.

Tokens
326.9K
Snippets
983
Records
1.5K
Agent score
50%

What's inside Akan.js

  1. Overview of Akan CLI capabilities

    main

    The Akan CLI is a workspace-wide management tool designed to handle the entire lifecycle of an Akan.js project. It manages workspace creation, application development, code generation, shared libraries, framework packages, domain modules, value types, page routing, mobile builds, local databases, and cloud configurations.

    Commands should generally be executed from the workspace root unless specified otherwise.

  2. Overview of akanjs/ui components

    main

    The akanjs/ui package provides the shared UI facet for Akan applications. It is organized into several functional layers to help build route-aware, data-driven interfaces:

    • Core: Primitives for routing, media, page shells, data loading, and model workflows.
    • Display: Helpers for model lists, relative time labels, loading states, empty states, and tabular UI.
    • Forms: Form controls and action primitives for templates, filters, and admin surfaces.
    • Overlays: Components for overlays, confirmations, menus, and copy helpers.
    • System: Application shell helpers, CSR (Client-Side Rendering) guards, admin signal tools, tab state, and animation wrappers.
    • Customization: Mechanisms to re-skin components per route.

  3. Overview of akanjs/client

    main

    The akanjs/client module provides browser and UI-facing helpers for Akan.js applications. It serves as the primary entry point for client-side logic, including routing, typed fetch access, dictionary hooks, authentication, and device utilities.

    Key responsibilities include:

    • Navigation: A singleton that normalizes Akan language/base-path prefixes before delegating to the active router.
    • UI Utilities: Re-exports clsx for class name composition and provides common prop types for generated UI components (Units, Zones, lists).
    • Routing & Layout: Provides types for PageConfig (transitions, safe areas, gestures, cache, devOnly flags) and LayoutProps.
    • Localization: Provides usePage() for locale-aware text and msg/Err helpers for rendering messages from generated dictionaries.
    • Data Fetching: A typed client fetch proxy built from signal metadata that exposes generated endpoint/slice methods and synchronizes JWT state.
    • Auth & Identity: Helpers for cookies, account decoding (via getAccount), and authentication state synchronization.
    • Hardware/Device Access: A Device singleton for Capacitor/native features like haptics, keyboard listeners, and safe-area values.

  4. What @akanjs/devkit provides

    main

    The @akanjs/devkit package provides the following primitives for Akan-aware development:

    • Executors: Workspace, app, library, package, and module executors.
    • Configuration: Loading and normalization of akan.config.ts.
    • Runners: Application build, typecheck, SSR, CSR, and release runners.
    • Analysis: Dependency scanning and package metadata generation helpers.
    • Frontend Tooling: Frontend build transforms and RSC/SSR artifact builders.
    • CLI Support: Command/script decorators used by @akanjs/cli.
    • AI Utilities: AI prompt, guideline, and code-generation support utilities.
    • Mobile: Capacitor and mobile release helpers.

  5. Use the akanjs/common utility library

    main

    The akanjs/common package provides framework-agnostic utilities shared across the CLI, server, UI, and application code. It is designed to be used in various environments (CLI, server, service adaptors, and long-running build/runtime code) and includes tools for logging, validation, formatting, and object manipulation.

    Key capabilities include:

    • Structured Logging: Supports static calls, named instances, and log-level filtering via the AKAN_PUBLIC_LOG_LEVEL environment variable. It also supports sink hooks for runtime file logging.
    • Validation: Includes email format validators and phone number validation/formatting (specifically optimized for Korean-style lengths).
    • String & Object Helpers: Provides tiny string casing helpers (first-character casing), object path helpers for nested state/form values, and a promise-based delay helper for async flows like polling or retries.
    • Randomization: Utilities like randomPick and randomPicks for selecting values from a list.
    • HTTP Wrapper: A centralized wrapper for managing request options, logging, auth, and response handling for external services.

  6. Use akanjs/base for primitive scalars and foundational utilities

    main

    The akanjs/base package provides foundational primitive scalar classes, runtime environment helpers, and utility types used for defining constants, document IDs, date values, and type-level model helpers.

    Key primitives include:

    • UUID: A 24-character hex string used for document IDs and signal payload IDs. Validates as a string; defaults to an empty string.
    • Integer: A primitive scalar for safe integers (e.g., counters, pagination, metrics).
    • Finite: A primitive scalar for decimal values (e.g., coordinates, rates, balances).
    • Any: A loose object scalar for open-shaped payloads or integration blobs.
    • Enum: A typed enum scalar class created from a literal value list. It provides helpers like .has(), .indexOf(), .find(), .filter(), .map(), and .forEach().
    • Dayjs: Re-exports the configured dayjs function and Dayjs type for date handling and UI formatting.
    • Collection: A small, ID-keyed collection helper for light model arrays, providing immutable-style set, delete, filter, slice, and pick operations.

  7. Use the Cloud CLI for Akan Cloud helpers

    main

    The Cloud CLI provides commands to configure optional Akan Cloud helper services. These helpers manage authentication, LLM settings, project-specific questions, and framework updates.

    Note: Commands should be executed from the workspace root unless specified otherwise. Internal deployment commands marked with devOnly: true are not part of the standard user-facing CLI reference.

  8. Use CapApp-SPM to host SPM dependencies

    main

    The CapApp-SPM package is a specialized container used to host Swift Package Manager (SPM) dependencies for Capacitor projects within the Akan.js ecosystem.

    Warning: Do not modify the contents of this package directly, as doing so may cause unintended consequences in the dependency resolution or the Capacitor build process.

  9. What is a Service Store?

    main

    A Service Store is a coordination layer for client state related to a specific service feature. It is responsible for managing:

    • Local feature state (e.g., search text, selected indices)
    • Loading flags and status
    • Pagination state
    • Fetching data via service endpoints
    • UI-facing actions

    Service stores are typically initialized using a string reference (e.g., store("feature-name" as const, ...)). Unlike model-based stores, they do not automatically receive CRUD helpers or model forms unless explicitly bound to a model signal. They are designed to keep React components thin by handling logic and state updates within the store methods.

  10. What is a Service Module in Akan.js?

    main

    A service module (or service file) owns the server workflow. It is the appropriate layer for implementing encryption, search indexing, file access, external API calls, and service-to-service coordination.

    Unlike model services, service modules are typically identified by a string name using the serve() function (e.g., serve("search" as const, ...)), and they do not necessarily require an underlying database model.

  11. What is a Service Module and when to use it

    main

    A Service Module is a specialized folder used to organize features, workflows, or integrations that are centered around an action or platform capability rather than a specific business object (like a User or Order).

    When to use a Service Module

    • Use a normal module when the feature is centered on a business object (e.g., User, Story, Order).
    • Use a Service Module when the feature is centered on an action or capability (e.g., search, security, local files, or shared utilities).

    Key Characteristics

    • It is useful when code does not start from a document model but still requires server logic, typed APIs, client state, and UI.
    • Service module folders typically start with an underscore (e.g., _search).

  12. What is a Module Abstract and when to update it

    main

    A Module Abstract is a business-intent file used to define the purpose and rules of a domain module. It serves as the source of truth for why a module exists, its business invariants, critical workflows, and data meanings that are not immediately obvious from the code alone.

    When to Update

    You must update the module abstract when there are changes to:

    • Business invariants
    • Workflows
    • Public behavior
    • Permissions
    • State transitions

    Do not update the abstract for:

    • Formatting changes
    • Import changes
    • Style-only changes

    Usage Best Practice

    Always read the module abstract before modifying any of the following files within the same module:

    • constant files
    • document files
    • service files
    • signal files
    • store files
    • UI files