Getting Started
This walkthrough takes you from an empty folder to a running API with real, working endpoints. If you've built a backend API before then you'll be familiar with many of the pieces here; routes, data models, background jobs, config files. What's different is how little of it you have to wire together yourself. There are no routers, no hand-written database code, and no HTTP request parsing.
RapidREST requires Node.js 24 or later.
Install the CLI
RapidREST ships as a CLI you install once, globally, and keep using throughout the project's life (generate route, generate model, and so on), not just at creation:
npm install -g @rapidrest/cli
This gives you the rapidrest command (rr for short, if you prefer).
Scaffold a project
To create a new RapidREST server project start with the following command:
rapidrest generate server my-api
This command walks you through an interactive prompt. Don't worry if you make a mistake, nothing is a permanent decision. You can add a database or React later without starting over.
| Prompt | Notes |
|---|---|
| Description / Author | Written into package.json, no functional effect |
| Package manager | yarn or npm |
| Databases | MongoDB and Redis are checked by default (Redis also backs the @Cache decorator). PostgreSQL and SQLite are available too |
| Additional features | React (server-rendered pages from this same server), Docker, Kubernetes (Helm) |
| Source control | GitHub, GitLab, Git, or none |
Every prompt above has a matching flag, and --answers <file> lets you scaffold identically-configured projects with zero prompts. See Generate Commands for the full flag reference.
Once the generate command is finished you can immediately get to work. Dependencies are installed automatically.
cd my-api
Run it
When actively developing you'll want to use rapidrest dev. This will automatically spin up a throwaway in-memory instance of every datastore you picked (nothing to install or run separately), and start the server with file-watching, restarting on every save. If you picked React, it also runs the Vite build in watch mode alongside it. Everything shuts down cleanly on Ctrl+C, nothing is left running on your machine afterward.
rapidrest dev
Confirm it's up:
curl http://localhost:3000/status
That works because the scaffold already includes a working StatusRoute.ts, along with equivalents for /admin, /metrics, /openapi, /push, and /acls if you kept a database selected. These are real files under src/routes/, thin subclasses of the framework's Default Routes, free for you to edit, lock down, or delete.
Running it without the file-watching
For a single run that builds first and then starts once, no watching, closer to how a real deployment invokes it:
yarn start
This still starts the same in-memory datastores rapidrest dev does, so it's not yet pointed at real data, just running the compiled output instead of tsx --watch. Deployment covers pointing this at real, persistent datastores and shipping it to an actual server or container.
What did generate server actually do?
The generate server command scaffolds your project with the following file and folder structure.
my-api/
├── src/
│ ├── config.ts # nconf config: datastores, port, secrets (see Core Concepts)
│ ├── server.ts # server entry point
│ ├── models/ # entity classes (@Entity, @DataStore, ...)
│ ├── routes/ # route classes (@Route, @Get, ...)
│ └── jobs/ # background jobs, if generated
├── apps/
│ └── app/ # SSR React pages, only if the React feature was selected
├── test/
├── docker-compose.yml # only if the Docker feature was selected
├── helm/ # only if the Kubernetes feature was selected
├── tsconfig.json # extends @rapidrest/service-core/tsconfig
└── package.json
Notice that there's no router file, and no model registry. Every class you export anywhere under src/ is discovered and wired up automatically at startup. When you add a new file it becomes live on the next restart; there's nothing else to touch. Core Concepts explains the mechanism behind this (and the decorator-heavy style that you'll see throughout the rest of these docs).
RapidREST's decorators need experimentalDecorators and emitDecoratorMetadata turned on. Your generated tsconfig.json already extends the framework's base config so you don't have to set these by hand:
{
"extends": "@rapidrest/service-core/tsconfig",
"compilerOptions": {"rootDir": ".", "outDir": "dist"},
"include": ["src"]
}
Add your own data: a Pet API
Say your API needs to track pets. First, describe the shape of a Pet:
rapidrest generate model Pet --datastore mongo
This creates src/models/Pet.ts (open it and add fields like name or species). Now expose it over HTTP:
rapidrest generate route PetRoute --model Pet
With this single command you have the standard CRUD set, GET /pets, POST /pets, PUT /pets/:id, DELETE /pets/:id, and more. There is no repository or query code to write by hand. See Auto CRUD Routes for the exact endpoint list.
You can skip generate model and create both model and route at the same time using:
rapidrest generate route PetRoute --model Pet
Save, and rapidrest dev picks the new files up automatically:
curl -X POST http://localhost:3000/pets -H "Content-Type: application/json" -d '{"name":"Rex"}'
curl http://localhost:3000/pets
What to learn next
- Core Concepts — decorators, auto-discovery, dependency injection, and configuration: the mechanisms behind everything above. Read this next.
- Routing → Controllers — hand-written endpoints, beyond what the CRUD generator gives you.
- Models & Persistence — more on shaping and storing data.
- Default Routes — what
AdminRoute,MetricsRoute,StatusRoute, and the other pre-written files actually do. - HTTP Engine — sessions, cookies, CORS, and what's underneath every request.
- Auth — token verification and RBAC out of the box, plus the optional Auth Library and Auth Server for real user accounts and login.
- SSR React — server-rendered pages from this same server, if you picked the React feature.
- CLI — every
generatecommand, in full.