Skip to main content

Development & Troubleshooting

1. Local Development Setup​

Prerequisites​

  • Node.js 20+
  • Docker & Docker Compose
  • AWS CLI (configured for infrastructure tasks)

Getting Started​

  1. Install Dependencies: npm install
  2. Start Infrastructure: npm run infra:up (Starts Postgres, Redis, LocalStack)
  3. Merge Envs: npm run merge-envs
  4. Start Services: npm run dev (Starts all services and the web app)

Useful Commands​

  • npm run build: Build all packages and services.
  • npm run typecheck: Run TypeScript validation across the monorepo.
  • npm run validate: Run the full pre-push validation suite.

2. Troubleshooting​

Common Issues​

"Cannot find module 'reflect-metadata'" (Docker)​

  • Cause: Incomplete npm install or dependency conflict in the Docker build stage.
  • Fix: Ensure npm ci is used without --legacy-peer-deps and rebuild the container.

Database Connection Errors (SSL)​

  • Cause: Production databases (RDS) require SSL, but the service is connecting without it.
  • Fix: Ensure the service uses getDatabaseConfig from @skinclubpro/shared, which handles SSL automatically for non-local hosts.

"No stacks match the name" (CDK)​

  • Cause: The dist folder in packages/infrastructure is out of date.
  • Fix: Run npm run build inside packages/infrastructure before deploying.

Subdomain Routing Not Working​

  • Cause: Local host file doesn't have the subdomain, or CloudFront Function is not deployed.
  • Fix: For local testing, add {subdomain}.localhost to your /etc/hosts file.

3. Testing Strategy​

  • Unit Tests: Run with npm test in each service.
  • Validation: The scripts/validate-build.sh script runs a full build and type-check of the entire system.