Getting Started with Minima.js

This guide takes you from zero to a running modular API using the Minima.js CLI.

Prerequisites

• Bun >=1.3 or Node.js >=22
• Basic TypeScript familiarity

1) Scaffold a Project

The fastest way to start is with @minimajs/cli:

Bun

bunx @minimajs/cli new my-app
cd my-app

Node.js

npx @minimajs/cli new my-app
cd my-app

This creates a fully configured project with TypeScript, a root module, and an ./app runner script.

Use the ./app runner

Every scaffolded project includes an executable ./app script that wraps the CLI. You don't need a global install — the project always uses its own pinned version.

2) Start the Dev Server

./app dev

Watch mode starts, TypeScript is compiled on save, and the server restarts automatically.

3) Understand File-Based Routing

Minima.js uses file-based module discovery — routes are defined in module.ts files, not registered imperatively with app.get(). The framework scans your src/ directory and mounts each module automatically.

Prefer module.ts over imperative registration

Don't do this:

// ❌ not the Minima.js way
app.get("/users", listUsers);

Do this instead — create src/users/module.ts:

// ✅ file-based routing
export const routes: Routes = {
  "GET /list": listUsers,
};

The file's directory path becomes the URL prefix automatically.

4) Add a Feature Module

Generate a module with the CLI:

./app add module users

This creates src/users/module.ts. Edit it to define your routes:

import type { Routes } from "@minimajs/server";
import { params, body } from "@minimajs/server";

function listUsers() {
  return [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
  ];
}

function getUser() {
  const id = params.get("id");
  return { id, name: "Alice" };
}

function createUser() {
  const payload = body();
  return { created: payload };
}

export const routes: Routes = {
  "GET /list": listUsers,
  "GET /:id": getUser,
  "POST /create": createUser,
};

With the root module's /api prefix you now have:

• GET /api/users/list
• GET /api/users/:id
• POST /api/users/create

No registration needed — adding the file is enough.

5) Build for Production

./app build    # compile TypeScript → dist/
./app start    # run the compiled output

6) What You Just Used

• File-based module discovery — module.ts files are found and mounted automatically
• Scoped module config via meta (prefix, plugins, hooks)
• Context helpers (params, body) — no request object passed around
• CLI scaffolding — add module, add service, add middleware and more

7) Next Steps

• Learn module architecture: Modules
• Learn request helpers: HTTP Guide
• Learn hooks and lifecycle: Hooks Guide
• Explore all CLI commands: CLI Reference
• Build a complete example: Task Board Tutorial