# Alepha > Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe full-stack applications. **Working in a project that already installs Alepha? Run `npx alepha docs` instead of reading this site.** alepha.dev documents the latest release and latest.alepha.dev documents `main`, for a project that vendors Alepha; `npx alepha docs` prints the same pages for the version the project installed, word for word and offline, from `node_modules/alepha/docs/`. `npx alepha docs ` prints a page (the slug is what follows `/docs/` in each URL below, without `.md`), and `npx alepha docs --grep ` searches every page. ## Overview **Core Principles:** - **Primitive Architecture**: Define features using `$`-prefixed primitives (`$action`, `$entity`, `$page`) that auto-register with the framework - **Class-Based Services**: All services are classes, not functional components. Primitives are class properties. - **Zero-Mapping**: No route files, no config files - code structure IS the configuration - **End-to-End Type Safety**: Types flow from database schema -> API -> React components - **Convention over Configuration**: Sensible defaults, minimal boilerplate - **Dependency Injection**: Built-in DI container manages all service instances **Built on**: Drizzle (ORM), React (SSR), Vite (bundler), Zod 4 (validation) **Runs on**: Node.js 24+, Bun, Cloudflare Workers, Vercel, Docker ## Creating a Project **ALWAYS run `npx alepha init my-app` to create a new Alepha project. Never hand-write the project skeleton, config files, or entry points - the CLI generates them correctly and keeps them consistent with the installed version.** ```bash npx alepha init my-app # scaffold: API + React (SSR) + Tailwind, deps installed npx alepha init my-app --preset=saas # the same, plus auth, account and admin cd my-app npx alepha dev # start the dev server ``` Every Alepha project has the **same** structure. `--preset` is the only choice, and a preset decides what is _mounted_ on the layout below, never where anything lives: | Preset | What you get | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `default` | The layout below: API module, web module (React SSR), Tailwind. | | `saas` | The above plus `@alepha/ui` and the identity surface - sign-in at `/auth/*`, an account area at `/account/*`, an admin console at `/admin/*` - backed by a `$realm` in `src/api/Realm.ts`. It also mounts the ORM, generates the initial migration, and writes `ADMIN_EMAIL` into a gitignored `.env`. Refused for Expo projects, which have no web module. | The remaining options are `--pm ` and `--force` (`-f`). Building an API-only service? Generate the project, then delete `src/web/`, `src/main.browser.ts` and `src/main.css`, and drop `WebModule` from `src/main.server.ts`. Run `alepha init` (no path) inside an existing project to fill in whatever is missing - it never overwrites without `--force`. ### Rules - ALWAYS scaffold new projects with `alepha init`, never by hand - use TypeScript (strict mode) - use oxlint for linting and oxfmt for formatting - use Vitest for testing - use Vite for bundling (full-stack) - use React for frontend (full-stack) - use Postgres or SQlite for database - use Zod for schema definitions, always via `z` from Alepha (`import { z } from "alepha"`), never `import { z } from "zod"` directly - Alepha's `z` adds opinionated defaults and extra formats - use documentation: https://latest.alepha.dev/llms.txt - one file = one class - primitives are always a class property, except for `$entity` to be drizzle-kit compatible - no decorators, no functional services, no Express/Fastify patterns - no manual instantiation, always use DI - use import with file extensions (e.g. `import { User } from "./User.ts"`) ## Project Structure ``` my-app/ ├── src/ │ ├── api/ # Backend │ │ ├── controllers/ # API controllers with $action │ │ ├── services/ # Business logic │ │ ├── entities/ # Entities with $entity │ │ ├── schemas/ # Request/response schemas │ │ ├── providers/ # External service providers │ │ ├── Realm.ts # $realm identity config (saas preset only) │ │ └── index.ts # API module definition with $module │ ├── web/ # Frontend (React, SSR) │ │ ├── components/ # React components │ │ ├── AppRouter.ts # Router definition with $page │ │ └── index.ts # Web module definition with $module │ ├── shared/ # Shared types/schemas │ ├── main.server.ts # Server entry │ ├── main.browser.ts # Browser entry │ └── main.css # Tailwind entry (@import "tailwindcss") ├── test/ # Vitest specs (*.spec.ts) ├── alepha.config.ts ├── vite.config.ts # Tailwind plugin ├── package.json └── tsconfig.json ``` Note: this layout is generated by `alepha init` and is identical in every Alepha project. `controllers/` and `schemas/` come scaffolded; `services/`, `entities/`, `providers/` and `shared/` are the conventional homes for what you add next. Each module directory has an `index.ts` exporting a `$module` grouping its services. Tailwind is already wired up - use utility classes, do not add another CSS framework. ## Examples ### API + Database ```typescript import { z } from "alepha"; import { $entity, $repository, db } from "alepha/orm"; import { $action } from "alepha/server"; const userEntity = $entity({ name: "users", schema: z.object({ id: db.primaryKey(), email: z.email(), createdAt: db.createdAt(), updatedAt: db.updatedAt(), deletedAt: db.deletedAt(), // Soft delete }), indexes: [{ column: "email", unique: true }], }); class UserController { userRepo = $repository(userEntity); getUser = $action({ method: "GET", path: "/users/:id", // -> GET /api/users/:id schema: { params: z.object({ id: z.uuid() }), response: userEntity.schema, }, handler: async ({ params }) => this.userRepo.getById(params.id), }); createUser = $action({ method: "POST", path: "/users", schema: { body: z.object({ email: z.email(), }), response: userEntity.schema, }, handler: async ({ body }) => this.userRepo.create(body), }); listUsers = $action({ method: "GET", path: "/users", // -> GET /api/users schema: { response: z.array(userEntity.schema), }, handler: async () => this.userRepo.findMany(), }); } ``` ### React Page with SSR ```tsx import { $page } from "alepha/react/router"; import { $client } from "alepha/server/links"; import type { UserController } from "./UserController.ts"; class AppRouter { api = $client(); // infer API client from controller users = $page({ path: "/users", loader: async () => ({ users: await this.api.listUsers() }), component: ({ users }) => (
    {users.map((u) => (
  • {u.email}
    • ))}
), }); } ``` ### Entry Point ```typescript // src/main.server.ts import { run } from "alepha"; import { ApiModule } from "./api/index.ts"; import { WebModule } from "./web/index.ts"; // React only run([ApiModule, WebModule]); // src/api/index.ts import { $module } from "alepha"; import { UserController } from "./controllers/UserController.ts"; export const ApiModule = $module({ name: "app.api", services: [UserController], }); ``` ### Service Communication ```typescript // Within same module - use $inject class OrderService { userService = $inject(UserService); async createOrder(userId: string) { const user = await this.userService.findById(userId); // ... } } // Between frontend and backend - use $client class AppRouter { api = $client(); orders = $page({ path: "/orders", loader: async () => ({ orders: await this.api.listOrders() }), }); } ``` ### Testing ```typescript import { Alepha } from "alepha"; import { describe, it, expect } from "vitest"; describe("UserService", () => { it("should create user", async () => { const alepha = Alepha.create().with(UserService); const service = alepha.inject(UserService); const user = await service.createUser({ email: "test@example.com" }); expect(user.email).toBe("test@example.com"); }); }); ``` ## Conventions - `$action` paths auto-prefix with `/api` - `$action` requires `method` and `path`: a read says `GET`, the URL never derives from the property name - Response schema strips undeclared fields (security) - `z.` = Zod schemas via `import { z } from "alepha"` - Primitives are class properties, not standalone (except `$atom`, `$entity`) - One file = one class - Use import with file extensions (e.g. `import { User } from "./User.ts"`) - Use `protected` instead of `private` for class members ## Common Mistakes to Avoid 1. **DON'T use decorators** - Alepha uses primitives, not decorators 2. **DON'T use Express/Fastify patterns** - No `app.get()`, `router.use()`, etc. 3. **DON'T import from `zod` directly** - Use `z` from `alepha`; it carries the framework's defaults and formats 4. **DON'T use functional components for services** - Always use classes 5. **DON'T forget the `$` prefix** - All primitives start with `$` 6. **DON'T inject across modules** - Use `$client` for cross-module communication 7. **DON'T use async constructors** - Use `$hook({ on: "start" })` instead 8. **DON'T create instances manually** - Let the DI container manage them ## Quick Reference Core utilities: - `z` (Zod schemas) - `import { z } from "alepha"` - `db` (database column helpers) - `import { db } from "alepha/orm"` Core primitives: - `$inject` - `import { $inject } from "alepha"` - `$env` - `import { $env } from "alepha"` - `$module` - `import { $module } from "alepha"` - `$atom` - `import { $atom } from "alepha"` - `$hook` - `import { $hook } from "alepha"` - `$logger` - `import { $logger } from "alepha/logger"` - `$action` - `import { $action } from "alepha/server"` - `$route` - `import { $route } from "alepha/server"` - `$entity` - `import { $entity } from "alepha/orm"` - `$repository` - `import { $repository } from "alepha/orm"` - `$page` - `import { $page } from "alepha/react/router"` - `$job` - `import { $job } from "alepha/api/jobs"` - `$cache` - `import { $cache } from "alepha/cache"` - `$storage` - `import { $storage } from "alepha/api/files"` - `$issuer` - `import { $issuer } from "alepha/security"` - `$realm` - `import { $realm } from "alepha/api/users"` - `$command` - `import { $command } from "alepha/command"` Picking the right one: - **Background work and cron**: always `$job`. It is the only primitive for either, and it has a durable outbox: at-least-once delivery, retries, idempotency keys, crash recovery, and failure rows in the database. Declare `schema` for queue-mode (then `push()`) or `cron` for cron-mode, never both. Requires a database. There is no `$scheduler` and no `$queue`. - **Files**: always `$storage`. Every upload writes a `files` row next to the blob, so you get paginated listing, TTL expiry, tags, checksums and creator tracking. `upload()` returns the row (use `.id`), not a blob id. A storage is a key prefix inside one bucket, never a bucket of its own, so declaring many costs nothing. Requires a database. There is no `$bucket`. For blobs without a database, inject `FileStorageProvider` from `alepha/bucket` and give up all of the above. React hooks: - `useStore` - `import { useStore } from "alepha/react"` - `useClient` - `import { useClient } from "alepha/react"` - `useInject` - `import { useInject } from "alepha/react"` - `useRouter` - `import { useRouter } from "alepha/react/router"` - `useForm` - `import { useForm } from "alepha/react/form"` - `useAuth` - `import { useAuth } from "alepha/react/auth"` - `useI18n` - `import { useI18n } from "alepha/react/i18n"` ## Docs Every page listed below is plain markdown: the HTML page at `https://latest.alepha.dev/docs/` is served as markdown at `https://latest.alepha.dev/docs/.md`. Fetch only the pages you need. Each section of the guides and of the CLI opens with an `llms-full.txt`: all of its pages in one file, for when you need the whole topic. A page listed directly under Guides or CLI, outside any section, has none. The reference and package pages are too many to list here; each kind has its own index, linked under "API reference" at the end. - [Examples](https://github.com/alepha-dev/alepha/tree/main/framework/apps): Example applications ## Guides - [Introduction](https://latest.alepha.dev/docs/guides-introduction.md): Alepha is a full-stack TypeScript application engine. - [Getting Started](https://latest.alepha.dev/docs/guides-getting-started.md): Create a full-stack app with an explicit Cloudflare production environment, then deploy it. - [Docs for Agents](https://latest.alepha.dev/docs/guides-docs-for-agents.md): Every Alepha package ships its own documentation, as plain markdown, inside its npm package. npx alepha docs prints it. ## Guides: Core - [Guides: Core, every page in one file](https://latest.alepha.dev/docs/guides/core/llms-full.txt): 10 pages, ~26k tokens. - [The Alepha Instance](https://latest.alepha.dev/docs/guides-core-alepha-instance.md): The Alepha class is the central container of your application. It holds configuration, manages state, controls lifecycle, and wires dependencies together. - [Configurations](https://latest.alepha.dev/docs/guides-core-configurations.md): Alepha provides two primitives for configuration: $env for environment variables and $atom for runtime state. - [Logging](https://latest.alepha.dev/docs/guides-core-logging.md): Alepha provides structured logging via the $logger primitive from alepha/logger. - [Modules](https://latest.alepha.dev/docs/guides-core-modules.md): $module groups related services into named, self-contained units. It helps organize large applications into domain-driven bounded contexts. - [Internal Events](https://latest.alepha.dev/docs/guides-core-internal-events.md): Alepha uses a hook-based event system for lifecycle management and cross-service communication. - [Types](https://latest.alepha.dev/docs/guides-core-types.md): Alepha provides schema validation through the z singleton from "alepha". - [Pipelines](https://latest.alepha.dev/docs/guides-core-pipelines.md): Every primitive with a handler in Alepha is a pipeline: a handler with a list of middleware wrapped around it. - [Cancellation](https://latest.alepha.dev/docs/guides-core-cancellation.md): Work that nobody is waiting for anymore should stop. - [Run Modes and Commands](https://latest.alepha.dev/docs/guides-core-run-modes.md): Most of the time an Alepha app is a server. Sometimes the same codebase has to be something else for thirty seconds: apply migrations, seed a database, print a report, drain a queue. - [Inspector](https://latest.alepha.dev/docs/guides-core-inspector.md): Every app alepha dev runs can be inspected from outside: its actions, jobs, entities, atoms, environment and logs, read and edited by a separate tool. ## Guides: Server - [Guides: Server, every page in one file](https://latest.alepha.dev/docs/guides/server/llms-full.txt): 11 pages, ~31k tokens. - [Building an API](https://latest.alepha.dev/docs/guides-server-building-an-api.md): Alepha provides type-safe HTTP endpoints through the $action primitive. Actions are class properties that define request schemas, response schemas, and handler logic in a single declaration. - [Middlewares](https://latest.alepha.dev/docs/guides-server-middlewares.md): Alepha provides built-in middleware modules for common server needs. - [Error Handling](https://latest.alepha.dev/docs/guides-server-error-handling.md): Every error in Alepha is declared with $error: a name, and a schema for the data it carries. - [Typed errors](https://latest.alepha.dev/docs/guides-server-typed-errors.md): Every error in Alepha is declared with $error: a name, and a schema for the data it carries. - [OpenAPI Documentation](https://latest.alepha.dev/docs/guides-server-openapi.md): Alepha auto-generates OpenAPI 3.0 specifications from your $action definitions using the $swagger primitive. - [HTTP Links](https://latest.alepha.dev/docs/guides-server-http-links.md): Alepha's link system provides type-safe cross-service communication through $client and $remote. - [File Upload](https://latest.alepha.dev/docs/guides-server-file-upload.md): Alepha handles multipart/form-data uploads through two body schema types. Multipart parsing is built into AlephaServer and active by default. - [Multipart](https://latest.alepha.dev/docs/guides-server-multipart.md): alepha/server/multipart is the layer underneath File Upload: the parser that reads multipart/form-data, and the registry that decides how many bytes a given request is allowed to carry. - [Rate limiting](https://latest.alepha.dev/docs/guides-server-rate-limiting.md): alepha/rate-limit counts hits per key in fixed windows and refuses past a limit. - [Static Files and Proxying](https://latest.alepha.dev/docs/guides-server-static-and-proxy.md): Two primitives for the requests an $action should not be handling: files that exist on disk, and requests that belong to somebody else's server. - [Cookies](https://latest.alepha.dev/docs/guides-server-cookies.md): $cookie declares an HTTP cookie with a schema. You read, write and delete it from a handler, and it can be signed, encrypted or compressed on the way. ## Guides: Security - [Guides: Security, every page in one file](https://latest.alepha.dev/docs/guides/security/llms-full.txt): 7 pages, ~31k tokens. - [Authentication](https://latest.alepha.dev/docs/guides-security-authentication.md): Alepha provides JWT-based authentication through $issuer for token management and $realm for full user management. - [Two-factor authentication](https://latest.alepha.dev/docs/guides-security-two-factor-authentication.md): A realm can ask for a second factor after the password. Two are built in, and they share one mechanism, so switching between them is a settings change rather than a rewrite. - [API keys](https://latest.alepha.dev/docs/guides-security-api-keys.md): alepha/api/keys gives a user long-lived tokens for scripts, CI and other machines. - [Resource Authorization](https://latest.alepha.dev/docs/guides-security-resource-authorization.md): $secure answers what kind of user is this? - issuer, roles, permissions (see Roles and Permissions). - [Organizations](https://latest.alepha.dev/docs/guides-security-organizations.md): alepha/api/organizations provides organizations, members, ownership, ranks, and invitations as one coherent boundary. - [Crypto and Secrets](https://latest.alepha.dev/docs/guides-security-crypto.md): alepha/crypto holds the cryptographic helpers every other module uses: password hashing, hashes and HMAC, AES-256-GCM encryption, and secure random values. - [Audit Log](https://latest.alepha.dev/docs/guides-security-audit-log.md): $audit records who did what, in a database table you can filter and search. A service declares a type of event with the actions it allows, and logs them as they happen. ## Guides: Realtime - [Guides: Realtime, every page in one file](https://latest.alepha.dev/docs/guides/realtime/llms-full.txt): 4 pages, ~14k tokens. - [WebSocket](https://latest.alepha.dev/docs/guides-realtime-websocket.md): Alepha provides real-time, bidirectional messaging through the $channel and $websocket primitives. - [Stateful Rooms](https://latest.alepha.dev/docs/guides-realtime-rooms.md): $websocket is a stateless, per-message handler. - [Topics](https://latest.alepha.dev/docs/guides-realtime-topics.md): $topic is publish/subscribe: a named channel with a typed message, where publishers do not know who is listening. - [MQTT](https://latest.alepha.dev/docs/guides-realtime-mqtt.md): @alepha/mqtt is an MQTT 5 client: byte payloads, a Last Will you can set by code, reconnection, and shared subscriptions. ## Guides: Persistence - [Guides: Persistence, every page in one file](https://latest.alepha.dev/docs/guides/persistence/llms-full.txt): 9 pages, ~34k tokens. - [Repository](https://latest.alepha.dev/docs/guides-persistence-repository.md): Alepha ORM is built on top of Drizzle ORM and Drizzle Kit. - [Special Columns](https://latest.alepha.dev/docs/guides-persistence-special-columns.md): The db object from alepha/orm provides helper methods for database-specific column types. - [Relations](https://latest.alepha.dev/docs/guides-persistence-relations.md): Declare how entities relate to one another once, then read the graph with include. - [Joins](https://latest.alepha.dev/docs/guides-persistence-joins.md): The with option performs a SQL join at query time, written per query. - [Migrations](https://latest.alepha.dev/docs/guides-persistence-migrations.md): Alepha manages database schema migrations through the embedded Drizzle Kit. The behavior differs between development, testing, and production environments. - [Portable SQL](https://latest.alepha.dev/docs/guides-persistence-portable-sql.md): Analytics work - grouping by day, measuring elapsed time, bounding a rolling window - needs date expressions, and written by hand those are not portable. - [Actor state](https://latest.alepha.dev/docs/guides-persistence-actors.md): An actor is a small piece of server state with an identity, changed only by pure reducers. - [Caching](https://latest.alepha.dev/docs/guides-persistence-caching.md): $cache provides a caching system with two modes: automatic function result caching, and a key-value store that also works as a middleware. - [File Storage](https://latest.alepha.dev/docs/guides-persistence-storage.md): $storage declares a named, constrained place to keep files. It works across local disk, S3-compatible services, Cloudflare R2 and an in-memory backend for tests. ## Guides: Frontend - [Guides: Frontend, every page in one file](https://latest.alepha.dev/docs/guides/frontend/llms-full.txt): 7 pages, ~30k tokens. - [React Integration](https://latest.alepha.dev/docs/guides-frontend-react.md): Alepha provides first-class React support with server-side rendering, dependency injection in components, type-safe API calls, and a global state system. - [Routing](https://latest.alepha.dev/docs/guides-frontend-routing.md): Alepha uses the $page primitive to define React routes, with support for data loading, code splitting, SSR, SSG, nested routing, and type-safe parameters. - [State Management](https://latest.alepha.dev/docs/guides-frontend-state-management.md): Alepha provides $atom for defining typed, validated state and useStore for consuming it in React components. - [Forms](https://latest.alepha.dev/docs/guides-frontend-forms.md): Alepha provides useForm for schema-driven forms with Zod validation, automatic input generation, and lifecycle events. - [Localization](https://latest.alepha.dev/docs/guides-frontend-localization.md): Alepha provides $dictionary for registering translations and useI18n for accessing them in React components. - [Page Cache](https://latest.alepha.dev/docs/guides-frontend-page-cache.md): Alepha caches server-rendered pages automatically, signed-in visitors included, and never caches a person. - [Sitemap](https://latest.alepha.dev/docs/guides-frontend-sitemap.md): $sitemap serves a sitemap.xml built from your $page primitives, and the build prerenders it to a static file. ## Guides: Features - [Guides: Features, every page in one file](https://latest.alepha.dev/docs/guides/features/llms-full.txt): 9 pages, ~42k tokens. - [Background Jobs](https://latest.alepha.dev/docs/guides-features-background-jobs.md): $job is the primitive for work that happens outside a request. - [Notifications and Email](https://latest.alepha.dev/docs/guides-features-notifications.md): Two layers, and picking the wrong one is the most common mistake. - [Runtime Parameters](https://latest.alepha.dev/docs/guides-features-runtime-parameters.md): $parameter is configuration that lives in the database instead of the environment: a named, schema-validated value you can change while the app is running, from the admin UI or from code, with... - [Analytics](https://latest.alepha.dev/docs/guides-features-analytics.md): $analytics gives your app a portable, aggregate-on-read analytics dataset. - [Payments](https://latest.alepha.dev/docs/guides-features-payments.md): Alepha provides a provider-agnostic payments layer through alepha/api/payments. - [Payment Providers](https://latest.alepha.dev/docs/guides-features-payment-providers.md): A PaymentProvider is the bridge between Alepha's lifecycle and a real payment service provider. - [Commerce](https://latest.alepha.dev/docs/guides-features-commerce.md): @alepha/commerce is a headless shop: catalog, cart, checkout, orders, invoices. - [Locks](https://latest.alepha.dev/docs/guides-features-locks.md): $lock is a middleware that lets one caller at a time run a handler. It takes a lock before the handler and releases it after, whether the handler returned or threw. - [Background Tasks](https://latest.alepha.dev/docs/guides-features-background-tasks.md): alepha/background runs a task without making the caller wait for it: a welcome email, a webhook, a write that does not have to finish first. ## Guides: AI - [Guides: AI, every page in one file](https://latest.alepha.dev/docs/guides/ai/llms-full.txt): 2 pages, ~13k tokens. - [AI assistant](https://latest.alepha.dev/docs/guides-ai-assistant.md): alepha/ai puts a model behind one provider contract and gives your app an assistant that knows the page the user is on and can run your features for them. - [MCP Server](https://latest.alepha.dev/docs/guides-ai-mcp.md): The Model Context Protocol (MCP) lets AI assistants call your application's tools, read its resources, and use its prompt templates over a standard JSON-RPC protocol. ## Guides: Testing - [Guides: Testing, every page in one file](https://latest.alepha.dev/docs/guides/testing/llms-full.txt): 4 pages, ~8k tokens. - [Unit Tests](https://latest.alepha.dev/docs/guides-testing-unit-tests.md): Alepha uses Vitest as the test runner. Every alepha init scaffolds a Vitest config and a sample test file - Vitest ships embedded in alepha, so there is nothing to install. - [React Tests](https://latest.alepha.dev/docs/guides-testing-react-tests.md): Alepha provides testing utilities for React components through alepha/testing/react. - [End-to-End Tests](https://latest.alepha.dev/docs/guides-testing-e2e-tests.md): End-to-end tests run against the built production version of your Alepha application. - [Before Commit](https://latest.alepha.dev/docs/guides-testing-before-commit.md): Every code change must pass linting, type checking, and tests before being committed. ## Guides: Deployment - [Guides: Deployment, every page in one file](https://latest.alepha.dev/docs/guides/deployment/llms-full.txt): 9 pages, ~30k tokens. - [Bare Deployment](https://latest.alepha.dev/docs/guides-deployment-bare.md): The default deployment. alepha build produces a self-contained dist/ folder that runs on any machine with Node.js or Bun installed. - [Static Deployment](https://latest.alepha.dev/docs/guides-deployment-static.md): The static runtime declaration generates a client-only bundle with no server code. - [Cloudflare Workers Deployment](https://latest.alepha.dev/docs/guides-deployment-cloudflare.md): A workerd runtime slice generates a Cloudflare Workers bundle with a wrangler.jsonc configuration. - [Bay Deployment](https://latest.alepha.dev/docs/guides-deployment-bay.md): Bay is a self-hosted application server for Alepha apps. - [Docker Deployment](https://latest.alepha.dev/docs/guides-deployment-docker.md): Build a runtime artifact, then turn it into a container image. - [Postgres and Redis on a Bay Stack](https://latest.alepha.dev/docs/guides-deployment-bay-stack.md): A Bay deploys an app on its own with SQLite in the instance's directory. - [Static File Headers](https://latest.alepha.dev/docs/guides-deployment-headers.md): A host that answers a file itself never runs your app, so the headers your app sends never reach that file. - [Native Apps (iOS and Android)](https://latest.alepha.dev/docs/guides-deployment-capacitor.md): @alepha/capacitor turns an Alepha app into an iOS and an Android app. - [Desktop App (macOS)](https://latest.alepha.dev/docs/guides-deployment-desktop.md): @alepha/desktop turns a built Alepha app into a macOS application: dist/.app, one executable whose main thread owns a native window while the app's own server, unchanged, runs in a Bun... ## CLI - [Installation](https://latest.alepha.dev/docs/cli-installation.md): The Alepha CLI is bundled inside the alepha package. No separate installation required. ## CLI: Commands - [CLI: Commands, every page in one file](https://latest.alepha.dev/docs/cli/commands/llms-full.txt): 11 pages, ~19k tokens. - [Init Command](https://latest.alepha.dev/docs/cli-commands-init.md): Create an Alepha project. The init command sets up everything you need - configuration files, dependencies, and project structure - so you can focus on building, not configuring. - [Dev Command](https://latest.alepha.dev/docs/cli-commands-dev.md): Start your development server with a single command. Hot reloading, fast refresh, environment variables - it all just works. - [Build Command](https://latest.alepha.dev/docs/cli-commands-build.md): Build your project for production. alepha build produces one dist/, carrying one server slice per runtime you asked for. - [Verify Command](https://latest.alepha.dev/docs/cli-commands-verify.md): alepha verify runs the configured verification command and exits nonzero when a step fails. - [Db Command](https://latest.alepha.dev/docs/cli-commands-db.md): Manage your database schema from the CLI. - [Toolchain Commands](https://latest.alepha.dev/docs/cli-commands-toolchain.md): Test, lint, typecheck, clean. - [Gen Command](https://latest.alepha.dev/docs/cli-commands-gen.md): Generate artifacts from your running application: OpenAPI specs, .env templates, and changelogs. gen boots your server entry (without starting it) and introspects the real app - the output always... - [Pack Command](https://latest.alepha.dev/docs/cli-commands-pack.md): Pack a built workspace into a deployable tar.zst. - [Compile Command](https://latest.alepha.dev/docs/cli-commands-compile.md): Compile a built dist/ into one executable, with the client's public/ files inside it. - [Image Command](https://latest.alepha.dev/docs/cli-commands-image.md): Build a container image from ./dist. - [Docs Command](https://latest.alepha.dev/docs/cli-commands-docs.md): Print the Alepha documentation of the version this project installed, from node_modules, word for word. ## CLI: Plugins - [CLI: Plugins, every page in one file](https://latest.alepha.dev/docs/cli/plugins/llms-full.txt): 4 pages, ~15k tokens. - [Infra Plugin](https://latest.alepha.dev/docs/cli-plugins-infra.md): Deploy your full-stack app to the cloud in one command. The infra plugin provisions databases, storage buckets, queues, pushes secrets, runs migrations, and deploys your code. - [Vendor Plugin](https://latest.alepha.dev/docs/cli-plugins-vendor.md): Keep local copies of Alepha packages inside your project. Audit source code, apply quick patches, or work offline with a stable snapshot. - [I18n Plugin](https://latest.alepha.dev/docs/cli-plugins-i18n.md): Find dead translation keys before they pile up. - [Capacitor Plugin](https://latest.alepha.dev/docs/cli-plugins-capacitor.md): alepha capacitor makes an iOS and an Android app from an Alepha app: it creates the native projects, builds the shell, compiles binaries and publishes live updates. ## API reference - [Primitives](https://latest.alepha.dev/docs/reference/primitives/llms.txt): Index of the 77 primitives (`$action`, `$entity`, `$page`, `$job`...), one page each with its import path and API. - [React hooks](https://latest.alepha.dev/docs/reference/react-hooks/llms.txt): Index of the 32 React hooks, one page each with its import path and API. - [Providers](https://latest.alepha.dev/docs/reference/providers/llms.txt): Index of the 227 providers: the services behind the primitives, the ones an app injects, and the ones it swaps. - [Packages](https://latest.alepha.dev/docs/packages/llms.txt): Index of the 127 package pages: every module of `alepha` (`alepha/server`, `alepha/orm`...) and every `@alepha/*` package, with its install line and overview. ## Optional - [Bay](https://latest.alepha.dev/bay/llms.txt): A self-hosted application server for Alepha apps, with TLS, rollback and process isolation handled for you. - [Lore](https://latest.alepha.dev/lore/llms.txt): An open-source project management app built on Alepha. Quests, folios, feedback and crash telemetry, readable and writable over MCP.