elysia-atlas

Advanced file-system router for ElysiaJS featuring automatic type generation and strict type inference.

Installation

``bash
bun add elysia-atlas
`

Quick Start

$3

`typescript
import { Elysia } from "elysia";
import { autoload } from "elysia-atlas";

const app = new Elysia()
.use(await autoload())
.listen(3000);

// Export type for Eden or strict type safety
export type App = typeof app;
`

> [!IMPORTANT]
> It's important to use await when registering the plugin.

$3

Create a routes directory and add your endpoints. Each file must export a default function that accepts an Elysia instance.

`typescript
// routes/index.ts
import { Elysia } from "elysia";

export default (app: Elysia) => app.get("/", () => "Hello World");
`

Strict Type Generation

elysia-atlas can automatically generate a type definition file that aggregates all your route types. This ensures your main App type includes every route defined in your file system, enabling full type safety for Eden clients.

$3

Enable typegen in the plugin options:

`typescript
const app = new Elysia()
.use(await autoload({
typegen: true // Generates routes.d.ts in the parent of the routes dir
}))
`

$3

The generated routes.d.ts allows you to cast your app to include all autoloaded routes.

`typescript
import { Elysia } from "elysia";
import { autoload } from "elysia-atlas";
import type { AutoloadedRoutes } from "./routes"; // Generated file

const app = new Elysia()
.use(await autoload({ typegen: true }));

export type App = typeof app;
`

Now App contains the type definitions for every route in your routes directory.

Routing Patterns

Files are mapped to routes based on their path relative to the dir option.

| File Path | Route Path |
| --- | --- |
| routes/index.ts | / |
| routes/users.ts | /users |
| routes/posts/index.ts | /posts |
| routes/settings/profile.ts | /settings/profile |

Options

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| dir | string | "./routes" | Path to the directory containing your routes |
| prefix | string | "/" | Prefix to prepend to all autoloaded routes |
| typegen | boolean \| string | false | If true, generates routes.d.ts`. If string, specifies the output path. |