Getting Started

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.

8 min readUpdated DocumentationEdit this page
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:

❯npx @axiljs/cli create
❯pnpm dlx @axiljs/cli create
❯yarn dlx @axiljs/cli create
❯bunx @axiljs/cli create

With a global install (npm install -g @axiljs/cli) the same command is:

Terminal
❯axil create

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.

KeyAction
↑ ↓ (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 / enterSelect the highlighted template
/Search across every category by name, summary, id, packages and highlights; esc leaves the search
esc / Ctrl+CCancel 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.

Output
TXT
  ┌  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:3000

On 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.

# A template by id
❯npx @axiljs/cli create shop --template rest-api
❯npx @axiljs/cli create chat -t realtime-chat --skip-install
# A custom stack: accept defaults for everything not given
❯npx @axiljs/cli create my-api --yes
❯npx @axiljs/cli create my-api --db=sqlite --auth --ws --skip-install
❯npx @axiljs/cli create my-api -y --db postgres --no-auth --queue
# A template by id
❯pnpm dlx @axiljs/cli create shop --template rest-api
❯pnpm dlx @axiljs/cli create chat -t realtime-chat --skip-install
# A custom stack: accept defaults for everything not given
❯pnpm dlx @axiljs/cli create my-api --yes
❯pnpm dlx @axiljs/cli create my-api --db=sqlite --auth --ws --skip-install
❯pnpm dlx @axiljs/cli create my-api -y --db postgres --no-auth --queue
# A template by id
❯yarn dlx @axiljs/cli create shop --template rest-api
❯yarn dlx @axiljs/cli create chat -t realtime-chat --skip-install
# A custom stack: accept defaults for everything not given
❯yarn dlx @axiljs/cli create my-api --yes
❯yarn dlx @axiljs/cli create my-api --db=sqlite --auth --ws --skip-install
❯yarn dlx @axiljs/cli create my-api -y --db postgres --no-auth --queue
# A template by id
❯bunx @axiljs/cli create shop --template rest-api
❯bunx @axiljs/cli create chat -t realtime-chat --skip-install
# A custom stack: accept defaults for everything not given
❯bunx @axiljs/cli create my-api --yes
❯bunx @axiljs/cli create my-api --db=sqlite --auth --ws --skip-install
❯bunx @axiljs/cli create my-api -y --db postgres --no-auth --queue
FlagMeaning
-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, --yesAccept defaults for every option not given as a flag (no prompts)
--db <driver>none (default), sqlite, postgres or mysql
--auth / --no-authJWT + RBAC auth (default: on)
--aiInclude the AI platform (default: off)
--wsInclude WebSocket support (default: off)
--queueInclude Queue and Scheduler (default: off)
--skip-installDo not run npm install
--forceAllow 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

Terminal
❯cd my-api
❯cp .env.example .env # PowerShell: Copy-Item .env.example .env
❯npm run dev

npm run dev runs axil run, which:

  1. compiles the project with tsc --incremental,
  2. starts dist/main.js,
  3. starts Studio, the local developer dashboard, on the app port + 1 (the port is read from PORT in .env, default 3000),
  4. watches src/ and recompiles and restarts on every .ts change.
Output
TXT
  ┌  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 stop

New 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:

Terminal
❯curl http://localhost:3000/hello/Ada
JSON
JSON
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:

Terminal
❯curl -X POST http://localhost:3000/echo -H "Content-Type: application/json" -d '{"message":""}'
JSON
JSON
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:

app.ts
TS
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
❯pnpm test
❯yarn test
❯bun run test

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):

TypeScript
TS
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.ts with typed config (defineConfig), CORS, GET /health and graceful shutdown
  • a users module with a controller and a service: GET/POST /users, GET/PUT/DELETE /users/:id (in memory without a database; GET /users requires a Bearer token when auth is on)
  • with a database: src/db/connection.ts, src/migrations/001_create_users.ts and an npm run migrate script (runs axil migrate)
  • WebSocket, Queue/Scheduler and AI wiring when those features are on

Grow it with the generators:

❯npx axil generate module products
❯npx axil g entity product
❯npx axil g migration add_price_to_products
❯pnpm dlx axil generate module products
❯pnpm dlx axil g entity product
❯pnpm dlx axil g migration add_price_to_products
❯yarn dlx axil generate module products
❯yarn dlx axil g entity product
❯yarn dlx axil g migration add_price_to_products
❯bunx axil generate module products
❯bunx axil g entity product
❯bunx axil g migration add_price_to_products

See Project Structure for the full layout.

Build for production

❯npm run build # tsc → dist/
❯npm start # node dist/main.js
❯pnpm run build # tsc → dist/
❯pnpm start # node dist/main.js
❯yarn run build # tsc → dist/
❯yarn start # node dist/main.js
❯bun run build # tsc → dist/
❯bun run start # node dist/main.js

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

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY