Minima.js

Appearance

Minima.jsThoughtfully Designed for Modern Runtimes

Most frameworks optimize features. Minima.js optimizes how it feels to work every day.

Get Started
View on GitHub
Minima.js

Built from Scratch for Modern Runtimes

Not a legacy port. Designed ground-up for Bun and Node.js with native APIs, zero compatibility layers, zero historical baggage.

File-Based Modules with True Isolation

Create users/module.ts, it auto-loads as /users/*. Each module is encapsulated—plugins only affect that module and its children. No sibling interference.

Write Code That Reads Naturally

Call body() from anywhere. No req.body drilling. No context passing. Access request data like it's global—because it is (safely).

TypeScript works with you

APIs are designed for inference, so types flow naturally from usage. You write logic.

100% Bun-Native Compatible

First-class Bun support with dedicated imports. Full Node.js compatibility. Same code, different runtime.

Web Standards, Zero Abstractions

Native Request/Response objects. Web standard APIs. Pure ESM. No framework-specific wrappers. Write portable, future-proof code.

How It Feels to Build ​

Watch how little code you need to write. Notice what you DON'T see—no imports, no registration, no wiring.

typescript
import { createApp } from "@minimajs/server/bun";
// import { createApp } from "@minimajs/server/node"; // for node

const app = createApp();
await app.listen({ port: 3000 });
// That's your entire entry point
typescript
import { type Meta } from "@minimajs/server";
import { cors } from "@minimajs/server/plugins";

// Global config - applies to every route
export const meta: Meta = {
  prefix: "/api",
  plugins: [cors()],
};

// sync / async supported
export default async function (app) {
  app.get("/health", () => ({ status: "ok" }));
}
typescript
// Auto-loaded as /api/users/*

import { body } from "@minimajs/server";

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

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

export default function (app) {
  app.get("/list", getUsers);
  app.post("/create", createUser);
}
typescript
// Auto-loaded as /api/posts/*

function getLatestPosts() {
  return { posts: [] };
}
export default function (app) {
  app.get("/latest", getLatestPosts);
}

Your API is ready:

  • GET /api/health → {"status":"ok"}
  • GET /api/users/list → [{"id":1,"name":"Alice"}...]
  • POST /api/users/create → Creates user
  • GET /api/posts/latest → {"posts":[]}

Add Authentication in Seconds ​

Protected routes? Just add a plugin to meta.plugins:

typescript
import { type Meta } from "@minimajs/server";
import { authPlugin, guardPlugin, getUser } from "../auth/index.js";

export const meta: Meta = {
  plugins: [
    authPlugin, // Makes getUser() available
    guardPlugin, // Requires authentication
  ],
};

export default async function (app) {
  app.get("/profile", () => {
    const user = getUser(); // Guaranteed to exist (guard ensures it)
    return { user };
  });
}

No decorators. No middleware chains. Just declare what you need.

See full JWT authentication tutorial →

True Module Encapsulation ​

Each module creates an isolated scope. Plugins, hooks, and configuration stay contained—no accidental global state, no sibling interference.

typescript
import { type Meta } from "@minimajs/server";
import { cors } from "@minimajs/server/plugins";

// Root module - these plugins apply to ALL children
export const meta: Meta = {
  prefix: "/api",
  plugins: [cors()],
};
typescript
import { type Meta } from "@minimajs/server";
import { hook } from "@minimajs/server";

// Users module - this hook ONLY affects /api/users/* routes
export const meta: Meta = {
  plugins: [hook("request", () => console.log("Users accessed"))],
};

export default async function (app) {
  app.get("/list", () => [
    /* users */
  ]);
}
typescript
import { searchParams } from "@minimajs/server";
// Posts module - no logging hook here
// Completely isolated from users module

function getPosts() {
  // contexts will be available everywhere
  const page = searchParams.get("page", Number); // cast page to number
  return {
    page,
    data: [], // posts
  };
}

export default async function (app) {
  app.get("/latest", getPosts);
}

How it works:

  • ✅ Root module plugins → Inherited by all children
  • ✅ Parent module plugins → Inherited by their children only
  • ✅ Sibling modules → Completely isolated from each other
  • ✅ Child can override or extend parent behavior
  • ✅ No global state pollution

Request to /api/users/list:

→ Root plugins run (cors)
→ Users plugins run (logging hook)
→ Route handler executes

Request to /api/posts/latest:

→ Root plugins run (cors)
→ Route handler executes
✅ Users logging hook DOES NOT run (isolated)

REST API with Auth ​

src/
├── module.ts           # Global auth, body parsing, CORS
├── auth/
│   └── module.ts       # POST /auth/login (public)
└── users/
    └── module.ts       # GET/POST /users/* (protected)

Why Minima.js?

Minima.js removes the friction you’ve learned to tolerate—slow feedback, noisy types, hidden lifecycles, and tangled modules—so building backends feels fast, clear, and predictable again.

Get Started →

Join the Community

Open source and community-driven. Report bugs, request features, or contribute code. We'd love your feedback.

GitHub →