Quick Start
Create and run your first AxilJS 0.3.6 backend: the interactive axil create flow, template picker, non-interactive flags, axil run with Studio, and tests.
On this page13
This guide takes you from an empty directory to a running, tested AxilJS API in a few minutes. You need Node.js 20 or newer (see Installation).
Create a project
Run the create command. On a terminal it is fully interactive, so you can leave out the project name:
With a global install (npm install -g @axiljs/cli) the same command is:
The flow has four steps, each labelled n/4 on its prompt.
Step 1/4: project name
Asked only when you did not pass a name. It must be a single directory name made of letters, numbers, dots, hyphens and underscores, must not start with . or -, and the directory must not already exist with files in it (use --force to allow that).
Step 2/4: pick a template
A browsable picker groups the 10 templates by category (Start, APIs, Realtime, Background, AI, Production) plus a Custom tab. A details card shows the highlighted template's highlights, packages and port.
| Key | Action |
|---|---|
↑ ↓ (or k j) | Move through the list; at the top or bottom of a category it flows into the neighbouring category |
← → (or h l, tab) | Jump between categories |
space / enter | Select the highlighted template |
/ | Search across every category by name, summary, id, packages and highlights; esc leaves the search |
esc / Ctrl+C | Cancel the whole flow (outside a search) |
Step 3/4: database and features (Custom only)
Only when you pick Custom. Choose a database (None, SQLite, Postgres, MySQL), then toggle features in one multi-select: Authentication (on by default), WebSocket, Queue and AI platform. Use space to toggle, a to toggle all, enter to confirm.
Step 4/4: confirm
A summary card shows what will be created (template, category, packages and port, or the custom stack), then asks Create project?. Answer with ← → or y / n and enter.
The CLI then writes the files, runs npm install and prints numbered next steps.
┌ axil create AxilJS v0.3.6
│
◇ Project name
│ my-api
│
◇ Pick a template
│ Minimal API
│
◆ Scaffold
◇ Application files 10 files written
◇ Dependencies installed
│
◆ Created my-api in 14.2s
│
└ Next steps
1. cd my-api
2. cp .env.example .env
3. npm test
Runs the route tests (no server needed)
4. Edit src/app.ts
Add your own routes and schemas
5. npm run dev
http://localhost:3000On Windows the copy step is printed as Copy-Item .env.example .env.
Create without prompts
Every prompt can be answered with a flag, which makes axil create scriptable (CI, Dockerfiles, docs). Without a TTY, or with --yes, no prompt is shown and a name is required.
| Flag | Meaning |
|---|---|
-t, --template <id> | Start from a template: minimal, rest-api, realtime-chat, background-jobs, ai-assistant, saas-api, microservice, webhook-receiver, live-dashboard, high-scale-api |
-y, --yes | Accept defaults for every option not given as a flag (no prompts) |
--db <driver> | none (default), sqlite, postgres or mysql |
--auth / --no-auth | JWT + RBAC auth (default: on) |
--ai | Include the AI platform (default: off) |
--ws | Include WebSocket support (default: off) |
--queue | Include Queue and Scheduler (default: off) |
--skip-install | Do not run npm install |
--force | Allow creating into an existing non-empty directory |
Warning
A template defines its own stack, so --template cannot be combined with --db, --auth, --ai, --ws or --queue. Giving any of those feature flags without --template also skips the template picker and creates a Custom project.
See Project Commands for the full reference.
Start the development server
npm run dev runs axil run, which:
- compiles the project with
tsc --incremental, - starts
dist/main.js, - starts Studio, the local developer dashboard, on the app port + 1 (the port is read from
PORTin.env, default 3000), - watches
src/and recompiles and restarts on every.tschange.
┌ axil run Development server with hot reload
│
◇ Compiled project 1.84s
App http://localhost:3000
12:04:31 → Starting dist/main.js
12:04:31 → Watching src/ for changes Ctrl+C to stopNew projects include @axiljs/studio as a devDependency, so Studio starts automatically. If it is missing, axil run prints Studio skipped with the fix: npm install -D @axiljs/studio. See ORM Studio.
Note
Each template listens on its own port (the Minimal API on 3000, the others on 3001 to 3009), so Studio for the REST API template, for example, is on http://localhost:3002.
Call the API
For the Minimal API template:
1{
2 "status": 200,
3 "code": "HTTP_200_OK",
4 "message": "Greeting created",
5 "data": { "greeting": "Hello, Ada!" }
6}Invalid input is rejected by @axiljs/validation before the handler runs. The template's error handler turns every thrown error into one shape:
1{
2 "error": {
3 "code": "VALIDATION_ERROR",
4 "message": "Request validation failed",
5 "details": [
6 { "path": "message", "message": "message must be at least 1 characters", "code": "MIN_LENGTH", "source": "body" }
7 ]
8 }
9}Note
The details array comes from the template's src/middleware/error-handler.ts. Without a custom 4-argument error handler, @axiljs/core answers with { "error": { "code", "message" } } (plus stack outside production) and leaves the details out.
Add a route
Handlers use the built-in response envelope (res.success, res.created, res.paginated, res.notFound, …) and validate() from @axiljs/validation. In the Minimal API, add routes in src/app.ts before the error handler:
1import { v, validate } from '@axiljs/validation'
2
3const CreateTodo = v.object({
4 title: v.string().trim().min(1).max(120),
5 done: v.boolean().default(false)
6})
7
8app.post('/todos', validate({ body: CreateTodo }), (req, res) => {
9 res.created({ id: 1, ...(req.body as object) }, 'Todo created')
10})Save the file: axil run recompiles and restarts in place.
Run the tests
npm test runs axil test: it compiles the project with tsc, then runs every *.test.ts / *.spec.ts under src/ and tests/ with @axiljs/testing. Every template ships its own passing tests that drive the app in-process with createTestClient(app):
1import { describe, it, expect, createTestClient } from '@axiljs/testing'
2import { createApp } from './app.js'
3import { loadConfig } from './config.js'
4
5const client = createTestClient(createApp(loadConfig({ NODE_ENV: 'test' })))
6
7describe('GET /hello/:name', () => {
8 it('greets by name', async () => {
9 const res = await client.get('/hello/Ada')
10 expect(res.status).toBe(200)
11 expect(res.body.data.greeting).toBe('Hello, Ada!')
12 })
13})Tip
A Custom project does not include test files yet. Add src/**/*.test.ts files in the same style and npm test picks them up.
The Custom stack
Picking Custom (or passing feature flags) generates a modular starter instead of a template:
src/main.tswith typed config (defineConfig), CORS,GET /healthand graceful shutdown- a
usersmodule with a controller and a service:GET/POST /users,GET/PUT/DELETE /users/:id(in memory without a database;GET /usersrequires a Bearer token when auth is on) - with a database:
src/db/connection.ts,src/migrations/001_create_users.tsand annpm run migratescript (runsaxil migrate) - WebSocket, Queue/Scheduler and AI wiring when those features are on
Grow it with the generators:
See Project Structure for the full layout.
Build for production
axil build does the same with a type-check step first. For containers, axil deploy writes a Dockerfile and Kubernetes manifests, sized from axil.scaling.json when the project has one. See Project Commands and Capacity.
Next steps
- Templates: pick a starter that already does what you need
- Project Structure: what each generated file is for
- HTTP Server: routing, middleware, SSE and static files
- Validation: schemas and the
validate()middleware - Authentication: JWT, password hashing and RBAC
- Database & ORM: models, repositories and migrations
- CLI Overview: every
axilcommand
Was this page helpful?