Documentation

Instant Express is a JSON-configured Express server. Define routes, auth, CRUD, and custom handlers in one config file — ship a REST API without boilerplate.

Install

npm install express-instant

Requires Node.js 18+.

Quick start

CLI

cp slices.example.json my-api.json
cp .env.example .env
npx express-instant --config-file my-api.json

Library

import { createApp, loadConfigFromFile } from "express-instant";

const config = loadConfigFromFile("./my-api.json");
const app = await createApp(config);
app.listen(3000);

Add to package.json: "start": "express-instant --config-file my-api.json"

Config file

Top-level options:

Key	Type	Description
`port`	number	Listen port (default `3000`)
`dotenv`	boolean	Load `.env` on startup
`cors`	boolean \| object	Enable CORS (pass options to `cors`)
`mongoDB`	boolean	Connect MongoDB via `MONGODB_STRING`
`bodyParser`	object	`{ "json": true, "urlencoded": { "extended": true } }`
`routes`	object	Path → HTTP method → handler config
`websockets`	object	Path → WebSocket template config

Example — Todo API with auth

{
  "port": 3000,
  "dotenv": true,
  "cors": true,
  "mongoDB": true,
  "bodyParser": { "json": true },
  "routes": {
    "/health": {
      "GET": { "type": "template", "template": "health" }
    },
    "/auth/sign-up": {
      "POST": { "type": "template", "template": "signUp" }
    },
    "/auth/sign-in": {
      "POST": { "type": "template", "template": "signIn" }
    },
    "/items/:collection": {
      "GET": { "type": "template", "template": "listItems" },
      "POST": {
        "type": "template",
        "template": "listItems",
        "middleware": ["requireAuth"]
      }
    }
  }
}

See slices.example.json for a full copy-paste example.

Route types

Type	Description
`template`	Built-in handler (`health`, `signUp`, …)
`function`	Inline handler body as a string
`module`	Load a local `.js` module from disk
`import`	Import an ES module handler
`static`	Serve static files from a directory
`routes`	Nested router (sub-routes)

Middleware on routes

{
  "POST": {
    "type": "template",
    "template": "listItems",
    "middleware": ["requireAuth"]
  }
}

Built-in templates

Template	Description
`health`	`{ success, status, uptime }`
`signUp`	Register user → MongoDB + bcrypt + JWT
`signIn`	Login → JWT
`listItems`	In-memory CRUD on `/items/:collection`
`mongoItems`	MongoDB CRUD on `/db/:collection` (requires `mongoDB: true`)

Built-in middleware

Name	Description
`requireAuth`	Validates `Authorization: Bearer <jwt>`

WebSockets

{
  "websockets": {
    "/ws": { "template": "echo" }
  }
}

Built-in echo template sends { "type": "connected" } on connect and echoes messages back.

Extend the library

import { registerTemplate, registerMiddleware } from "express-instant";

registerTemplate("myHandler", (req, res) => res.json({ ok: true }));
registerMiddleware("adminOnly", (req, res, next) => { /* ... */ next(); });

Environment variables

MONGODB_STRING=mongodb://localhost:27017
MONGODB_NAME=express-instant
JWT_SECRET=change-me-in-production
EXPRESS_INSTANT_CONFIG=./my-api.json
PORT=3000

Live API demo

This site runs Instant Express on Vercel. Try the health endpoint:

curl https://express-instant.vercel.app/api/health

Open /api/health in your browser.