Local development

Use the local workflow to review generated code, test schema changes, and implement extensions before deployment. The CLI reads the target language from .apsorc and starts the corresponding native framework process.

Create a local project


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

Use python or go for the other framework templates.

Configure the database

The TypeScript template supports PGlite for a low-setup local database:

.env


DATABASE_TYPE=pglite
DATABASE_SYNC=true
APP_PORT=3100

To use PostgreSQL, set the connection values created by the template and start a local database. Keep secrets in .env, and exclude that file from version control.


docker run --name apso-postgres \
  -e POSTGRES_USER=apso \
  -e POSTGRES_PASSWORD=apso \
  -e POSTGRES_DB=project_api \
  -p 5432:5432 \
  -d postgres:16

Run the development loop

Edit `.apsorc`

Use the version 2 array format. This excerpt adds a Project resource:

.apsorc


{
  "version": 2,
  "language": "typescript",
  "rootFolder": "src",
  "entities": [
    {
      "name": "Project",
      "created_at": true,
      "updated_at": true,
      "fields": [
        { "name": "name", "type": "text" },
        { "name": "budget", "type": "decimal", "precision": 12, "scale": 2 }
      ]
    }
  ],
  "relationships": []
}

Validate and generate


apso schema validate
apso generate

Review the generated diff before committing it. Keep product-specific code in extensions/.

Start the service


apso dev

apso dev detects the language and runs the native command. Use Docker when you need a repeatable container environment:


apso dev --docker
apso dev --docker --build
apso dev --docker --detach

Exercise the API

For the preceding TypeScript example:


curl -s -X POST http://localhost:3100/Projects \
  -H "Content-Type: application/json" \
  -d '{"name":"Launch","budget":5000}'
 
curl -s http://localhost:3100/Projects

Open http://localhost:3100/_docs to inspect the generated OpenAPI surface.

Validate schema changes


apso migrate

The migration command detects schema changes, generates SQL, and exercises it against a local PGlite sandbox before deployment.

Framework commands

TypeScript


npm test
npm run build

Python


pytest
python -m compileall app

Go


go test ./...
go build ./...

Template ports and scripts can differ by language. Treat the generated .env, package scripts, and README as the source for that project, then use /_docs to confirm its HTTP routes.

Diagnose a project

Run the CLI diagnostics when generation, dependencies, Git, or platform linking do not look right:


apso doctor
apso status

For an offline project, apso doctor is the relevant check. apso status requires a linked service.