⚡ Master

The command center for the Master framework.

The master CLI scaffolds and runs full-stack applications the way create-next-app made Next.js effortless — one command to a working app, one command to run it, and generators for everything in between.

Every app is a clean, decoupled monorepo:

Next.js frontend · MasterController API · MasterRecord ORM

Install

npm install -g master

Requires Node.js ≥ 20.

Quick start

master new my-app        # scaffold a full-stack monorepo
cd my-app
master db migrate        # create the database schema (SQLite by default)
master dev               # run the API (:3001) + Next.js (:3000) together

Open http://localhost:3000 — the homepage talks to the backend's /health endpoint to prove the full stack is wired together.

master new my-app --db postgres     # choose your database
master new my-app --skip-frontend   # backend-only (no Next.js)
master new my-app --skip-install    # skip npm install

What you get

my-app/
├── master.config.js          # ports + frontend toggle
├── backend/                   # MasterController API + MasterRecord ORM (ESM)
│   ├── server.js              # boots the framework (scoped DbContext, config, health, OpenAPI, auth)
│   ├── app/
│   │   ├── routes.js          # URL → controller#action (+ authorize / typed params / versions)
│   │   ├── controllers/       # API controllers (this.db, this.model, this.ok/created/notFound…)
│   │   ├── models/            # MasterRecord entities + AppContext (one per request)
│   │   └── sockets/           # WebSocket controllers
│   ├── middleware/            # auto-loaded request pipeline
│   ├── config/
│   │   ├── appsettings.json   # layered configuration (+ appsettings.production.json)
│   │   └── environments/      # per-env database config (development / test / production)
│   └── test/                  # `master test` — in-process integration tests (createTestClient)
└── frontend/                  # Next.js App Router (TypeScript)
    └── app/                   # page.tsx, layout.tsx, lib/api.ts

The two halves run side by side. The frontend reaches the backend through the typed api() helper (frontend/app/lib/api.ts); CORS is pre-configured on the backend.

Commands

| Command | Description | | --- | --- | | master new <name> | Scaffold a new full-stack app | | master dev (alias s) | Run backend + frontend together (watch mode) | | master build | Build the frontend for production | | master start | Run backend + frontend in production mode | | master generate <type> <name> (alias g) | Generate code (see below) | | master db <action> [name] | Database migrations (MasterRecord) — the dotnet ef equivalent | | master secrets <action> [key] [value] | Development secrets outside the repo — the dotnet user-secrets equivalent | | master test [--frontend] | Run the backend (and optionally frontend) test suites | | master routes | List the registered API routes | | master info | Framework + environment info |

Generators

master g scaffold post title:string body:text   # model + REST API + Next.js page
master g controller users index show             # API controller + routes
master g model Comment body:text                 # MasterRecord entity (+ registered)
master g page about                              # Next.js App Router page
master g socket chat message                     # WebSocket controller
master g middleware auth                          # request-pipeline middleware
master g component billing                        # mountable backend component

Generators are idempotent and wiring-aware: scaffold/controller append their routes to app/routes.js, and model/scaffold register the entity in AppContext.js for you.

Database

master db migrate          # apply pending migrations (update-database)
master db new AddPosts     # create a migration from your current models (enables migrations on first use)
master db rollback         # roll back the latest migration
master db status           # applied / pending migrations (EF: migrations list)
master db script -o up.sql # SQL for the pending migrations, nothing applied (EF: migrations script)
master db remove [--force] # delete the latest migration file (EF: migrations remove)
master db list             # list migration files
master db --env production migrate

master db is a thin, friendly wrapper around the masterrecord migration CLI, always run inside backend/ with the right context and environment.

Configuration, secrets, tests

master secrets set Auth:JwtSecret <32+ random chars>   # ~/.master/usersecrets/<app>/secrets.json
master secrets list                                     # values masked (--reveal to show)
master test                                             # backend tests (node --test, NODE_ENV=test)

Scaffolded apps read configuration ASP.NET-style — config/appsettings.json < appsettings.{env}.json < user secrets < environment variables (Section__Key) — and register the database context per request (master.addScoped('db', AppContext), used as this.db in controllers). Health endpoints (/health/live, /health/ready), OpenAPI (/openapi.json + /docs), response compression, graceful shutdown and opt-in JWT auth are wired in server.js.

Field types

Models use MasterRecord's fluent builder. master g model/scaffold accept name:type:

| Alias | Column | | --- | --- | | string, str | string | | text | text | | int, integer, number | integer | | bigint | bigint | | float | float | | decimal | decimal | | bool, boolean | boolean | | date | date | | datetime, timestamp | datetime / timestamp | | time | time | | json | json | | uuid | uuid | | binary, blob | binary |

// backend/app/models/Post.js
export default class Post {
  id(db) { db.integer().primary().auto(); }
  title(db) { db.string(); }
  body(db) { db.text(); }
}

See the MasterRecord docs for relationships (belongsTo, hasMany), transformers, and the full query API.

Documentation

• Getting started
• Generators
• Deployment

Contributing

git clone https://github.com/Tailor/Master.git
cd Master
npm install
npm test          # vitest (unit + integration)
npm run build     # tsup → dist/
npm run lint

The CLI is written in TypeScript (src/), built with tsup, and tested with Vitest. Generators are pure functions (string in, file descriptors out) so they're easy to test.

License

MIT — By the power of Grayskull, you have the power. ⚡