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.
2.9 KiB
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