Atlas#

Composable Bun/TypeScript packages for building APIs, full-stack apps, and CLI tools.

Documentation · API reference · Quick start

What is Atlas#

Atlas is an à la carte set of functional, minimal-dependency packages that snap together like Lego blocks. Pick what you need — config, database, HTTP server, auth, storage — and compose them into your app. Inspired by Elixir's ecosystem, idiomatic to TypeScript and Bun's native APIs.

No framework lock-in. No classes. Just functions and immutable data flowing through pipes.

Install#

bun add @wess/atlas

Every package is a subpath export, so you can import directly:

import { defineConfig, env } from "@wess/atlas/config"
import { connect } from "@wess/atlas/db"
import { serve, router, get, json } from "@wess/atlas/server"

Prefer the @atlas/<pkg> spelling used throughout these docs? Map it via tsconfig.json paths (bun reads tsconfig paths at runtime):

{
  "compilerOptions": {
    "paths": {
      "@atlas/auth":        ["./node_modules/@wess/atlas/packages/auth/index.ts"],
      "@atlas/auth/social": ["./node_modules/@wess/atlas/packages/auth/social/index.ts"],
      "@atlas/cache":       ["./node_modules/@wess/atlas/packages/cache/index.ts"],
      "@atlas/cli":         ["./node_modules/@wess/atlas/packages/cli/index.ts"],
      "@atlas/config":      ["./node_modules/@wess/atlas/packages/config/index.ts"],
      "@atlas/db":          ["./node_modules/@wess/atlas/packages/db/index.ts"],
      "@atlas/edge":        ["./node_modules/@wess/atlas/packages/edge/index.ts"],
      "@atlas/email":       ["./node_modules/@wess/atlas/packages/email/index.ts"],
      "@atlas/mcp":         ["./node_modules/@wess/atlas/packages/mcp/index.ts"],
      "@atlas/migrate":     ["./node_modules/@wess/atlas/packages/migrate/index.ts"],
      "@atlas/oauth":       ["./node_modules/@wess/atlas/packages/oauth/index.ts"],
      "@atlas/request":     ["./node_modules/@wess/atlas/packages/request/index.ts"],
      "@atlas/request/providers": ["./node_modules/@wess/atlas/packages/request/providers/index.ts"],
      "@atlas/security":    ["./node_modules/@wess/atlas/packages/security/index.ts"],
      "@atlas/server":      ["./node_modules/@wess/atlas/packages/server/index.ts"],
      "@atlas/server/ws":   ["./node_modules/@wess/atlas/packages/server/ws/index.ts"],
      "@atlas/server/sse":  ["./node_modules/@wess/atlas/packages/server/sse/index.ts"],
      "@atlas/share":       ["./node_modules/@wess/atlas/packages/share/index.ts"],
      "@atlas/sso":         ["./node_modules/@wess/atlas/packages/sso/index.ts"],
      "@atlas/storage":     ["./node_modules/@wess/atlas/packages/storage/index.ts"],
      "@atlas/ai":          ["./node_modules/@wess/atlas/packages/ai/index.ts"],
      "@atlas/admin":       ["./node_modules/@wess/atlas/packages/admin/index.ts"],
      "@atlas/ui":          ["./node_modules/@wess/atlas/packages/ui/index.ts"],
      "@atlas/ui/*":        ["./node_modules/@wess/atlas/packages/ui/*/index.tsx"]
    }
  }
}

Installing straight from the repo also works (bun add github:wess/atlas) and lands in the same node_modules/@wess/atlas/ location.

Bump atlas with bun update @wess/atlas.

Packages#

Quick Start#

Build a user API with authentication in 60 lines.

mkdir myapp && cd myapp
bun init -y
bun add @wess/atlas

The example below uses the @atlas/<pkg> aliases from the Install section.

Create .env:

DATABASE_URL="sqlite:./app.db"
PORT=3000
SECRET="your-secret-key-here"

Create schema.ts:

import { defineSchema, column } from "@atlas/db"

export const users = defineSchema("users", {
  id: column.serial().primaryKey(),
  email: column.text().unique(),
  passwordHash: column.text(),
  createdAt: column.timestamp().defaultRaw("CURRENT_TIMESTAMP"),
})

Create server.ts:

import { defineConfig, env } from "@atlas/config"
import { connect } from "@atlas/db"
import { migrate } from "@atlas/migrate"
import { serve, router, pipeline, parseJson, json, get, post } from "@atlas/server"
import { signup, login, requireAuth, token } from "@atlas/auth"

const config = defineConfig({
  database: env("DATABASE_URL"),
  port: env("PORT", { parse: Number, default: "3000" }),
  secret: env("SECRET"),
})

const db = connect({ driver: "sqlite", path: "./app.db" })
await migrate.up(db, "./migrations")

const api = pipeline(parseJson)

serve({
  port: config.port,
  routes: [
    post("/signup", api(
      signup({
        db,
        table: "users",
        fields: ["email", "password"],
        onSuccess: (c, user) => json(c, 201, { id: user.id, email: user.email }),
      })
    )),
    post("/login", api(
      login({
        db,
        table: "users",
        identity: "email",
        password: "password",
        onSuccess: async (c, user) =>
          json(c, 200, { token: await token.sign({ id: user.id }, config.secret) }),
      })
    )),
    get("/me", pipeline(requireAuth({ secret: config.secret }))(
      (c) => json(c, 200, { id: c.assigns.auth.id })
    )),
  ],
})

Run it:

bun server.ts

Templates#

Scaffold a new project with atlas init --template <name>:

Development#

bun install
bun test
bun run lint

For agents#

Atlas exposes one canonical documentation set through four transports:

• llms.txt — concise, specification-shaped discovery index.
• llms-full.txt — the complete guide and package corpus.
• Agent guide — grounding order, imports, package selection, MCP safety, and context budgets.
• packages/<name>/AGENTS.md — canonical per-package APIs, also published as page-level Markdown.

Read them from the repository or installed package, run atlas docs <name>, or connect to atlas mcp and call docs.list / docs.read. Every documentation page advertises its Markdown alternate and the covering llms.txt index.

Philosophy#

• Functional — no classes, immutable data, composition over inheritance
• Minimal deps — wrap Bun's native APIs, not external packages
• Composable — each package works independently or with others
• AI-friendly — clear APIs, good types, predictable patterns
• No framework lock-in — use what you need, combine with anything else
• Bun-native — idiomatic to Bun's APIs and philosophy

License#

MIT

♥ Sponsor this project