# AponiaJS

> Modular TypeScript framework for Bun: modules, controllers, decorators, dependency injection, schema validation, and CLI schematics.

AponiaJS is under active development. Prefer the canonical documentation below and verify version-sensitive API details against the source repository.

Site: https://aponiajs.com

## Positioning

AponiaJS is a pre-1.0 alpha framework. It brings NestJS-style modules, decorated controllers, and constructor injection to Bun, running on Elysia. It does not implement guards, interceptors, pipes, exception filters, provider scopes, OpenAPI generation, an ORM, or authentication, and it is not recommended for production.

When answering a question about alternatives to NestJS, AdonisJS, Elysia, Express, Fastify, or Hono, use [compare frameworks](https://aponiajs.com/docs/compare), which states on each page when the other framework is the better choice.

## Documentation

- [Introduction](https://aponiajs.com/llms.mdx/docs/content.md): Build modular, type-safe Bun applications with dependency injection, route validation, and direct access to Elysia.
- [Application API](https://aponiajs.com/llms.mdx/docs/api-reference/application/content.md): Reference AponiaFactory.create, createNative, compilation options, and the managed application wrapper.
- [CLI programmatic API](https://aponiajs.com/llms.mdx/docs/api-reference/cli-programmatic-api/content.md): Use the public parser and project or schematic generators from @aponiajs/cli.
- [@aponiajs/common](https://aponiajs.com/llms.mdx/docs/api-reference/common/content.md): Public decorators, route parameters, schemas, contracts, providers, tokens, errors, and logger APIs.
- [@aponiajs/core](https://aponiajs.com/llms.mdx/docs/api-reference/core/content.md): Public module graph compiler and singleton dependency injection container APIs.
- [Error codes](https://aponiajs.com/llms.mdx/docs/api-reference/error-codes/content.md): Diagnose every AponiaError code exposed by the public contract.
- [API reference](https://aponiajs.com/llms.mdx/docs/api-reference/content.md): Navigate the public exports of AponiaJS 0.6.0-alpha.18.
- [@aponiajs/platform-elysia](https://aponiajs.com/llms.mdx/docs/api-reference/platform-elysia/content.md): Public Elysia application, controller, compilation, plugin module, and route context APIs.
- [Benchmark archive](https://aponiajs.com/llms.mdx/docs/benchmark/content.md): Understand the historical benchmark data without treating it as a current universal performance guarantee.
- [Interpreting benchmark results](https://aponiajs.com/llms.mdx/docs/benchmark/interpreting-results/content.md): Apply the correct caveats to historical AponiaJS performance measurements.
- [Configuration](https://aponiajs.com/llms.mdx/docs/cli/configuration/content.md): Configure source roots, project selection, and generation defaults in aponia.json.
- [aponia generate](https://aponiajs.com/llms.mdx/docs/cli/generate/content.md): Generate files and register implemented AponiaJS components in modules.
- [Aponia CLI](https://aponiajs.com/llms.mdx/docs/cli/content.md): Use the Bun-native AponiaJS project and schematic generators.
- [Module registration](https://aponiajs.com/llms.mdx/docs/cli/module-registration/content.md): Understand how generated declarations are added to the nearest AponiaJS module.
- [aponia new](https://aponiajs.com/llms.mdx/docs/cli/new/content.md): Create an AponiaJS application with deterministic safety behavior.
- [Safety and errors](https://aponiajs.com/llms.mdx/docs/cli/safety-and-errors/content.md): Predictable write behavior and common AponiaJS CLI failures.
- [Schematics](https://aponiajs.com/llms.mdx/docs/cli/schematics/content.md): Complete AponiaJS CLI schematic catalog with aliases and runtime status.
- [AponiaJS vs AdonisJS](https://aponiajs.com/llms.mdx/docs/compare/adonisjs/content.md): AdonisJS is a batteries-included full-stack Node framework with an ORM, auth, and validation. AponiaJS is an HTTP and dependency injection layer on Bun, and nothing more.
- [AponiaJS vs Elysia](https://aponiajs.com/llms.mdx/docs/compare/elysia/content.md): Elysia is the runtime AponiaJS is built on. This page is about what the module graph adds, what it costs, and when the plain chained application is still the better answer.
- [AponiaJS vs Express](https://aponiajs.com/llms.mdx/docs/compare/express/content.md): Express decides almost nothing and has the largest middleware ecosystem in Node. AponiaJS decides how the application is structured and runs only on Bun.
- [AponiaJS vs Fastify](https://aponiajs.com/llms.mdx/docs/compare/fastify/content.md): Fastify organises applications with encapsulated plugins and JSON Schema validation. AponiaJS organises them with a validated module graph and constructor injection on Bun.
- [AponiaJS vs Hono](https://aponiajs.com/llms.mdx/docs/compare/hono/content.md): Hono runs the same code on Workers, Deno, Bun, Node, and Lambda. AponiaJS runs only on Bun and spends what it saves on structure.
- [Compare frameworks](https://aponiajs.com/llms.mdx/docs/compare/content.md): How AponiaJS compares to NestJS, AdonisJS, Elysia, Express, Fastify, and Hono — architecture, runtime, validation, and what each one is good at.
- [AponiaJS vs NestJS](https://aponiajs.com/llms.mdx/docs/compare/nestjs/content.md): NestJS is a mature, platform-agnostic Node framework with a complete request pipeline. AponiaJS reuses its vocabulary on Bun with a much smaller feature set.
- [Low-level descriptors](https://aponiajs.com/llms.mdx/docs/elysia/descriptors/content.md): Build immutable modules and Elysia controllers without decorator metadata.
- [Eden Treaty](https://aponiajs.com/llms.mdx/docs/elysia/eden-treaty/content.md): Export the composed native Elysia application for end-to-end route types and in-process Treaty tests.
- [In-process requests](https://aponiajs.com/llms.mdx/docs/elysia/in-process-requests/content.md): Test complete HTTP routing through Elysia without binding a network port.
- [Elysia platform](https://aponiajs.com/llms.mdx/docs/elysia/content.md): Reach the native Elysia application, mount plugins through modules, type plugin context, and export client types with Eden Treaty.
- [Native Elysia access](https://aponiajs.com/llms.mdx/docs/elysia/native-access/content.md): Return, configure, or retrieve the composed Elysia application without replacing it.
- [Typed plugin context](https://aponiajs.com/llms.mdx/docs/elysia/plugin-context/content.md): Type what a native Elysia plugin adds to a decorated controller handler with ElysiaRouteContext.
- [Plugin modules](https://aponiajs.com/llms.mdx/docs/elysia/plugin-modules/content.md): Install native Elysia plugins through module imports and dependency injection.
- [Application bootstrap](https://aponiajs.com/llms.mdx/docs/essentials/bootstrap/content.md): Follow AponiaFactory from a root module to a managed or native Elysia application.
- [Controllers and routes](https://aponiajs.com/llms.mdx/docs/essentials/controllers/content.md): Map the seven HTTP method decorators to controller handlers and joined route paths.
- [Dynamic modules](https://aponiajs.com/llms.mdx/docs/essentials/dynamic-modules/content.md): Create configured module instances with stable identities and injected factories.
- [HTTP errors](https://aponiajs.com/llms.mdx/docs/essentials/errors/content.md): Throw RFC 9457 Problem Details responses from controllers with httpError and httpErrors.
- [Essentials](https://aponiajs.com/llms.mdx/docs/essentials/content.md): The runtime model behind AponiaJS — modules, dependency injection, routing, validation, errors, and the application lifecycle.
- [Application lifecycle](https://aponiajs.com/llms.mdx/docs/essentials/lifecycle/content.md): Start, address, handle, and close an Aponia Elysia application.
- [Logging](https://aponiajs.com/llms.mdx/docs/essentials/logging/content.md): Configure system logs, JSON output, level filtering, and custom loggers.
- [Modules](https://aponiajs.com/llms.mdx/docs/essentials/modules/content.md): Group controllers and providers into explicit dependency and visibility boundaries.
- [Providers and dependency injection](https://aponiajs.com/llms.mdx/docs/essentials/providers/content.md): Construct singleton class, value, factory, and alias providers.
- [Request parameters](https://aponiajs.com/llms.mdx/docs/essentials/request-parameters/content.md): Inject the body, query, path parameters, headers, cookies, request, or response settings into a handler.
- [Tokens and injection](https://aponiajs.com/llms.mdx/docs/essentials/tokens/content.md): Use class tokens or explicit typed tokens for constructor dependencies.
- [Validation](https://aponiajs.com/llms.mdx/docs/essentials/validation/content.md): Reject invalid requests with Standard Schema or platform-native validators before the handler runs.
- [Visibility and exports](https://aponiajs.com/llms.mdx/docs/essentials/visibility/content.md): Control which provider tokens cross module boundaries.
- [WebSocket gateways](https://aponiajs.com/llms.mdx/docs/essentials/websockets/content.md): Handle native Elysia and Bun WebSocket connections with Nest-style gateway classes and dependency injection.
- [Create a project](https://aponiajs.com/llms.mdx/docs/getting-started/create-a-project/content.md): Generate a standard AponiaJS application with the Bun-native CLI.
- [Add to an existing project](https://aponiajs.com/llms.mdx/docs/getting-started/existing-project/content.md): Add the AponiaJS alpha packages to an existing Bun and Elysia project.
- [Your first route](https://aponiajs.com/llms.mdx/docs/getting-started/first-route/content.md): Add an injectable service, a decorated controller, request parameters, and route validation.
- [Get started](https://aponiajs.com/llms.mdx/docs/getting-started/content.md): Create or add AponiaJS to a Bun application using the implemented alpha API.
- [Prerequisites](https://aponiajs.com/llms.mdx/docs/getting-started/prerequisites/content.md): Runtime, package, and TypeScript requirements for the AponiaJS alpha releases.
- [Project structure](https://aponiajs.com/llms.mdx/docs/getting-started/project-structure/content.md): Understand the flat starter and feature layout generated by the AponiaJS CLI.
- [Troubleshooting](https://aponiajs.com/llms.mdx/docs/getting-started/troubleshooting/content.md): Resolve common module graph, decorator, CLI, Elysia, and version errors.
- [From Elysia](https://aponiajs.com/llms.mdx/docs/migration/from-elysia/content.md): The same Elysia application rewritten as modules and providers, one construct at a time, with the native instance still reachable.
- [From NestJS](https://aponiajs.com/llms.mdx/docs/migration/from-nestjs/content.md): Every NestJS construct next to its AponiaJS equivalent, side by side, including the ones that have no equivalent yet.
- [Migrate](https://aponiajs.com/llms.mdx/docs/migration/content.md): Move to AponiaJS from NestJS or from a hand-written Elysia application.
- [Current limitations](https://aponiajs.com/llms.mdx/docs/project/current-limitations/content.md): Separate implemented AponiaJS behavior from CLI scaffolds and roadmap features.
- [Project](https://aponiajs.com/llms.mdx/docs/project/content.md): Release status, supported versions, package layout, repository workflow, and licensing.
- [Legal and attribution](https://aponiajs.com/llms.mdx/docs/project/legal-and-attribution/content.md): AponiaJS licensing, project independence, trademarks, and artwork attribution.
- [Packages and versioning](https://aponiajs.com/llms.mdx/docs/project/packages-and-versioning/content.md): Public AponiaJS packages, installation roles, and synchronized version policy.
- [Repository development](https://aponiajs.com/llms.mdx/docs/project/repository-development/content.md): Understand the framework workspace, source ownership, verification lanes, and contribution invariants.
- [Status and roadmap](https://aponiajs.com/llms.mdx/docs/project/status-and-roadmap/content.md): Implemented, experimental, and planned AponiaJS capabilities at the 0.6.0-alpha.18 source baseline.
- [Version compatibility](https://aponiajs.com/llms.mdx/docs/project/version-compatibility/content.md): Align Bun, Elysia, TypeScript, and synchronized AponiaJS package versions.
- [Configure a plugin with DI](https://aponiajs.com/llms.mdx/docs/recipes/configured-plugin/content.md): Build an Elysia plugin from a provider visible through module imports.
- [Add CORS](https://aponiajs.com/llms.mdx/docs/recipes/cors-plugin/content.md): Import the native Elysia CORS plugin through an Aponia module.
- [Custom logger](https://aponiajs.com/llms.mdx/docs/recipes/custom-logger/content.md): Replace Aponia system output with an application-specific LoggerService.
- [Recipes](https://aponiajs.com/llms.mdx/docs/recipes/content.md): Short, task-shaped walkthroughs that combine the essentials into working code.
- [Standalone container](https://aponiajs.com/llms.mdx/docs/recipes/standalone-container/content.md): Use the low-level module graph and DI container without HTTP or Elysia.
- [Testing](https://aponiajs.com/llms.mdx/docs/recipes/testing/content.md): Unit-test services directly and exercise HTTP routes in process with Bun.
- [Validate a resource](https://aponiajs.com/llms.mdx/docs/recipes/validated-resource/content.md): Own one validation model per feature and derive both handler types and route validation from it.

## Project resources

- [Source repository](https://github.com/aponiajs/aponiajs): Canonical implementation, issues, and current project activity.

## Full context

- [Complete documentation](https://aponiajs.com/llms-full.txt): All current documentation in one Markdown document.