Local Development

This section covers everything you need for day-to-day local development — running servers, generating boilerplate, and managing your local environment.

Running the Dev Servers

Run the backend and frontend in separate terminal windows (or terminal tabs):

Backend

ds local run backend

Starts the Hono API server with hot reload on port 3001. The server:

• Watches for TypeScript file changes and restarts automatically
• Connects to your Neon PostgreSQL branch
• Reads configuration from .env
• Sets IS_LOCAL=true for local-specific behavior
• Auto-kills any stale process on port 3001 before starting (prevents EADDRINUSE errors)

Frontend

ds local run frontend

Starts the Vite dev server with hot module replacement on port 8080. The frontend proxies API requests to http://localhost:3001.

Preflight Checks

ds local run backend runs preflight checks before starting:

1. Verifies required tools are available
2. Runs pnpm install if dependencies are stale
3. Validates .env configuration
4. Checks for pending DB migrations and runs them automatically

Code Generation

The CLI provides generators for CQRS boilerplate, saving you from manually creating the 4-5 files needed for each new command or query.

Generating a Command

ds local generate command CreateNotification -m notification

This creates:

All files follow DevStride's DDD patterns and are wired into the module's DI container.

Generating a Query

ds local generate query GetUserNotifications -m notification

Creates the same file structure but for query operations (read-only).

Options

Secrets Management

Pulling Shared Secrets

ds setup secrets pull

Downloads shared development secrets from AWS Secrets Manager to your .env. Run this:

• After initial setup
• When a teammate has added/rotated a secret
• When secrets appear to be missing or stale

Pushing Secret Updates

ds setup secrets push

Uploads your local .env values to Secrets Manager. Use this after manually adding or updating a secret that other developers need.

Auditing Secrets

ds setup secrets audit

Opens an interactive browser showing all secrets with their status:

• Configured — Value is set and looks valid
• Missing — Required but not present
• Placeholder — Default/template value that needs replacement

For each missing secret, the audit provides:

• A description of what it's for
• A link to the dashboard where you can get the value
• A prompt to enter the value directly

Environment Configuration

Key Files

Important Environment Variables

The .env file contains all configuration needed for local development:

Identity & Stage:

DEVSTRIDE_DEVELOPER=phil         # Set in your shell config by ds setup
DEVSTRIDE_STAGE=phil-local       # Auto-computed by the ds wrapper (always {developer}-local)
DEVSTRIDE_REGION=us-east-1
AWS_PROFILE=devstride-dev

Database:

DB_CONNECTION_STRING=postgresql://neondb_owner:[email protected]/neondb?sslmode=require
DB_CONNECTION_STRING_READ_ONLY=postgresql://...

Authentication:

COGNITO_USER_POOL_ID=us-east-1_xxxxxxxx
COGNITO_USER_POOL_CLIENT_ID=xxxxxxxx

Third-party Services:

STRIPE_SECRET_KEY=sk_test_...
PUSHER_APP_ID=...
PUSHER_APP_KEY=...
PUSHER_APP_SECRET=...
SLACK_BOT_TOKEN=xoxb-...
NEON_API_KEY=...

How Local Mode Works

When IS_LOCAL=true (set automatically by ds local run backend):

• Config loading reads individual environment variables from .env instead of decoding a DEVSTRIDE_CONFIG blob from Secrets Manager.
• Database initialization is lazy — the connection pool is only created when first accessed.
• Secrets Manager fetch is skipped — no AWS calls needed at startup.
• Resource names are derived from the {stage}-devstride-{resource} convention.

This means local development works entirely offline from AWS (after initial setup), except for database connections to Neon.

API Client Generation

After modifying backend API routes, regenerate the frontend SDK:

ds api generate-api-client

This:

1. Scans all Hono route definitions in the backend
2. Generates an OpenAPI 3.1.0 specification
3. Produces a class-based TypeScript SDK in frontend/src/api/
4. Auto-formats the output with Prettier

Routes marked with x-skip-client are excluded from generation.

API Documentation Generation

ds api generate-api-docs

Generates an OpenAPI 3.0.0 spec with embedded documentation at backend/src/modules/api/interface-adapters/lambda/http/openapi.json. Includes auth methods, curl examples, and troubleshooting guides.

Routes marked with x-skip are excluded from docs. Routes marked with x-skip-client are excluded from both docs and SDK.

Next Steps

• Database Management — Migrations, branches, resets
• Deployment — Deploying to cloud stages
• Developer Lifecycle — End-to-end workflow examples