marco.chan
7923ba1b8d
- Create ingest-api with Koa framework for handling device telemetry. - Implement telemetry ingestion with MongoDB, Redis, and PostgreSQL. - Add API endpoints for telemetry and health checks. - Set up testing with Vitest for unit and end-to-end tests. - Configure Prettier and ESLint for code formatting and linting. - Create Docker Compose setup for PostgreSQL, MongoDB, and Redis services. - Establish contracts package for shared Zod schemas and TypeScript types. - Implement React frontend with device status and greeting functionalities. - Add VS Code setup documentation for onboarding developers.
VS Code Setup Guide
This guide is for developers onboarding to this monorepo with Yarn workspaces, Nest API, and Vite web.
Goals
- Open the workspace with correct TypeScript resolution.
- Run API and web locally from VS Code.
- Use one-click debug profiles.
- Fix common red-squiggle and startup issues quickly.
1) Prerequisites
- Node.js installed
- Corepack enabled
- Yarn available
Quick checks:
node -v
corepack --version
yarn -v
2) Open the Correct Folder
Open the repository root folder in VS Code, not a subfolder.
Expected top-level folders:
- apps
- packages
- docs
- .vscode
3) Install Dependencies from Root
Run in the root folder:
yarn install
Why: workspace metadata and PnP dependency graph are generated at root.
4) Configure Yarn SDK for VS Code
Run:
yarn dlx @yarnpkg/sdks vscode
Then in VS Code:
- Open Command Palette
- Run TypeScript: Select TypeScript Version
- Choose Use Workspace Version
- Run TypeScript: Restart TS Server
This fixes most false errors like cannot find module react or asset files.
5) Verify Workspace Settings
The workspace should contain these settings:
- typescript.tsdk points to .yarn/sdks/typescript/lib
- typescript.enablePromptUseWorkspaceTsdk is true
If missing, rerun the SDK command in section 4.
6) Start and Debug from VS Code
Use Run and Debug with these profiles:
- API: Attach Nest (9229)
- Web: Chrome (Vite 5173)
- Full Stack Debug
They rely on background tasks:
- api:debug
- web:dev
7) Manual Run Commands (Fallback)
From repo root:
yarn workspace api start:dev
yarn workspace web dev --host 0.0.0.0 --port 5173
8) Common Issues and Fixes
A) Package for api not found
Cause: workspace name changed but graph not refreshed.
Fix:
yarn install
yarn workspaces list --json
B) Cannot find module react, css, svg in editor
Cause: VS Code TypeScript server not using workspace SDK.
Fix:
- Run yarn dlx @yarnpkg/sdks vscode
- Select Use Workspace Version
- Restart TS Server
- Reload window if needed
C) Peer dependency warnings after installing trest stack
Cause: trest and Koa peers installed in wrong workspace, usually web.
Fix:
- Keep trest and Koa in apps/api
- Keep web dependencies frontend-only
D) Nest scaffold fails with schematics resolution
Use non-interactive fallback:
CI=1 npx -y @nestjs/cli new apps/api --skip-git --package-manager yarn --strict
9) Workspace Dependency Rules
- apps/api contains Koa, trest, and other backend runtime dependencies.
- apps/web contains frontend runtime dependencies.
- root should mostly contain workspace-level tooling.
10) Day-1 Validation Checklist
- yarn install completes from root
- yarn workspaces list shows root, api, web
- API starts locally
- Web starts locally
- Full Stack Debug launches successfully
- No persistent false TypeScript module errors in editor