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

Full Stack (Recommended)

ds local run

This launches both servers in a tmux session with side-by-side panes:

• Left pane: Backend (Hono API server on port 3001)
• Right pane: Frontend (Vite dev server on port 8080)

tmux controls:

Re-running ds local run replaces any existing tmux session.

Backend Only

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

Frontend Only

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

Both ds local run backend and ds local run frontend run preflight checks before starting:

1. Verifies required tools are available
2. Runs pnpm install if dependencies are stale
3. Validates .env configuration

If you're restarting frequently and want to skip these checks:

ds local run backend --skip-preflight

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 ds doctor reports missing secrets

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

CI Readiness Check

ds setup secrets audit --ci

Non-interactive mode that outputs a readiness report. Useful in CI pipelines or for quick verification.

Backup and Restore

# Create a timestamped backup
ds setup env backup
# → .env.backup.2026-02-22T10-30-00

# Restore from a backup
ds setup env restore
# → Shows available backups with age and key count, lets you pick one

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:...@ep-xxx.us-east-1.aws.neon.tech/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):

• 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