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.

Agents#

skills/ holds small, task-focused instructions for coding agents, so they can build with Atlas without loading the full docs. Run atlas skills install to copy them into .claude/skills, or pass --dir for another tool. See skills/README.md.

Install#

Install the coordinated 0.5.1 libraries from this repository's GitHub release assets. The release workflow verifies all artifacts before making them available.

bunx --package https://github.com/wess/atlas/releases/download/v0.5.1/wess-atlas-cli-0.5.1.tgz atlas add server config db/query db/postgres

The installer records exact GitHub release URLs, tested external versions, and the dependency closure for only the selected entry points. Public imports stay under @wess/atlas:

import { defineConfig, env } from "@wess/atlas/config"
import { connect } from "@wess/atlas/db/postgres"
import { column, defineSchema, from } from "@wess/atlas/db/query"
import { serve, get, json } from "@wess/atlas/server"

@wess/atlas is a small facade with optional implementation peers such as @wess/atlas-server. Installing the facade alone does not install implementations. Use atlas add to select modules and their required peers; atlas add without arguments lists the public entry points. No consumer path aliases or local Atlas checkout are required. Keep application lockfiles and update the selected Atlas libraries together.

To prepare and validate a release from this source workspace:

bun install --frozen-lockfile
bun run check
bun run typecheck
bun test
bun run distribution:build
bun run distribution:verify
bun run distribution:dryrun

Artifacts and the entry-point dependency catalog are written to out/distribution/. The GitHub release contains those exact tarballs and their integrity catalog. No npm publication or registry token is needed.

Packages#

For a clean production dependency tree, use bun install --production --omit=peer --frozen-lockfile. The installer records the selected module closure and required peers as explicit application dependencies. Build browser assets first with development dependencies available. The release fixture verifies that the minimal runtime excludes the CLI and frontend tooling.

Quick Start#

Build a user API with authentication in 60 lines.

mkdir myapp && cd myapp
bun init -y
bunx --package https://github.com/wess/atlas/releases/download/v0.5.1/wess-atlas-cli-0.5.1.tgz atlas add server config db/sqlite db/query migrate auth/flows auth/token

The example below uses public @wess/atlas/<pkg> exports from the selected libraries.

Create .env:

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

Create schema.ts:

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

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 "@wess/atlas/config"
import { connect } from "@wess/atlas/db/sqlite"
import { migrate } from "@wess/atlas/migrate"
import { serve, router, pipeline, parseJson, json, get, post } from "@wess/atlas/server"
import { signup, login, requireAuth } from "@wess/atlas/auth/flows"
import * as token from "@wess/atlas/auth/token"

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