Local Development

Set up a complete local development environment for building with APSO.

Prerequisites

Before you begin, ensure you have:

Node.js 18+ — Required for the CLI and generated code
PostgreSQL 14+ — Local database for development
Git — Version control

Database Setup

Option 1: Docker (Recommended)


# Start PostgreSQL with Docker
docker run --name apso-postgres \
  -e POSTGRES_USER=apso \
  -e POSTGRES_PASSWORD=apso \
  -e POSTGRES_DB=apso_dev \
  -p 5432:5432 \
  -d postgres:16
 
# Verify it's running
docker ps

Option 2: Local PostgreSQL

If you have PostgreSQL installed locally:


# Create the database
createdb apso_dev
 
# Or with psql
psql -U postgres -c "CREATE DATABASE apso_dev;"

Connection String

Your connection string for local development:


postgresql://apso:apso@localhost:5432/apso_dev

Environment Setup

Create a .env file in your project root:

.env


# Database
DATABASE_URL=postgresql://apso:apso@localhost:5432/apso_dev
 
# Auth (Better Auth)
BETTER_AUTH_SECRET=your-secret-key-change-in-production
 
# Optional: Enable debug logging
DEBUG=apso:*
 
# Optional: Server port
PORT=3001

Project Initialization

New Project


# Create a new APSO project
npx apso server new my-api
 
# Navigate to the project
cd my-api
 
# Install dependencies
npm install
 
# Set up the database
npm run db:setup

Existing Project


# Clone your project
git clone https://github.com/your-org/your-api.git
 
# Install dependencies
npm install
 
# Run migrations
npm run db:migrate
 
# Generate APSO code
npm run apso:generate

Running the Server

Start the development server with hot reload:


npm run dev

The server starts on http://localhost:3001 with:

API endpoints at /api/v1/...
Swagger UI at /api/docs
Health check at /health

Development Workflow

1. Edit Schema

Modify your .apsorc file:


{
  "entities": {
    "Project": {
      "fields": {
        "name": { "type": "string", "required": true },
        "budget": { "type": "number" }  // New field
      }
    }
  }
}

2. Regenerate Code


npm run apso:generate

This updates:

Entity files
Controllers
Services
TypeORM entities

3. Create Migration


npm run db:migrate:create

4. Run Migration


npm run db:migrate

5. Test Changes


# Run tests
npm run test
 
# Or test manually with Swagger UI
open http://localhost:3001/api/docs

Debugging

Enable Debug Logging


# In .env
DEBUG=apso:*
 
# Or run with DEBUG
DEBUG=apso:* npm run dev

Database Logging

Enable SQL query logging in .apsorc:


{
  "database": {
    "logging": true
  }
}

Node.js Debugging


# Start with debugger
node --inspect-brk node_modules/.bin/nest start
 
# Or use VS Code launch configuration

VS Code Setup

Create .vscode/launch.json:


{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug APSO",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start:debug"],
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

Common Tasks

Task	Command
Start dev server	`npm run dev`
Run tests	`npm run test`
Regenerate code	`npm run apso:generate`
Create migration	`npm run db:migrate:create`
Run migrations	`npm run db:migrate`
Reset database	`npm run db:reset`
Build for production	`npm run build`

Troubleshooting

Port Already in Use


# Find process on port 3001
lsof -i :3001
 
# Kill the process
kill -9 <PID>

Database Connection Failed


# Check PostgreSQL is running
docker ps  # If using Docker
pg_isready  # If local installation
 
# Test connection
psql $DATABASE_URL -c "SELECT 1"

Migration Failed


# Check migration status
npm run db:migrate:status
 
# Rollback last migration
npm run db:migrate:rollback
 
# Reset and re-run all migrations
npm run db:reset