Quickstart

Build a local NestJS API for projects and tasks. You will create a project, define .apsorc, generate the backend, run it with an embedded PostgreSQL-compatible database, and call the REST endpoints.

Prerequisites

Node.js 18 or newer
Git

Install the CLI

npm


npm install -g @apso/cli

yarn


yarn global add @apso/cli

pnpm


pnpm add -g @apso/cli


apso --version

Create the API

Initialize a TypeScript project


apso init --name task-api --language typescript --skip-platform
cd task-api

--skip-platform creates the project locally without requiring an Apso Cloud login.

Use PGlite for local development

Open .env and set the database type to pglite. Keep synchronization enabled for this local quickstart.

.env


DATABASE_TYPE=pglite
DATABASE_SYNC=true
APP_PORT=3100

PGlite runs in the Node.js process, so this path does not require Docker or a separate PostgreSQL server.

Define the schema

Replace .apsorc with:

.apsorc


{
  "version": 2,
  "language": "typescript",
  "rootFolder": "src",
  "entities": [
    {
      "name": "Project",
      "created_at": true,
      "updated_at": true,
      "fields": [
        { "name": "name", "type": "text" },
        { "name": "description", "type": "text", "nullable": true },
        {
          "name": "status",
          "type": "enum",
          "values": ["Active", "Archived"],
          "default": "Active"
        }
      ]
    },
    {
      "name": "Task",
      "created_at": true,
      "updated_at": true,
      "fields": [
        { "name": "title", "type": "text" },
        {
          "name": "status",
          "type": "enum",
          "values": ["Todo", "InProgress", "Done"],
          "default": "Todo"
        },
        { "name": "priority", "type": "integer", "default": 3 }
      ]
    }
  ],
  "relationships": [
    { "from": "Project", "to": "Task", "type": "OneToMany" }
  ]
}

Generate the service


apso generate

The TypeScript generator writes entities, DTOs, services, controllers, and module registration under src/autogen/.

Start the development server


apso dev

The API runs at http://localhost:3100. Open http://localhost:3100/_docs to inspect the generated OpenAPI interface.

Call the API

Open another terminal while apso dev is running.

Create a project


curl -s -X POST http://localhost:3100/Projects \
  -H "Content-Type: application/json" \
  -d '{"name":"Launch","description":"Prepare the first release"}'

Create a task


curl -s -X POST http://localhost:3100/Tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Verify the API","priority":1,"projectId":1}'

List tasks


curl -s http://localhost:3100/Tasks

The generated CRUD controller uses plural entity routes such as /Projects and /Tasks. Confirm the exact routes in /_docs after each schema change.

Inspect the generation boundary


task-api/
|-- .apsorc
|-- .env
`-- src/
    |-- autogen/
    |   |-- Project/
    |   `-- Task/
    `-- extensions/

Path	Use
`.apsorc`	Edit the data model and generation settings
`src/autogen/`	Inspect generated code; expect regeneration to rewrite it
`src/extensions/`	Add custom endpoints, hooks, and business rules

Next steps

Explore SaaS, CRM, commerce, operations, and industry starter backends

Start from a product model

Extend the service without editing generated files

Add custom logic

Use the generated API behind a Next.js BFF

Connect Next.js