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.
150 lines
2.9 KiB
Markdown
150 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
yarn install
|
|
```
|
|
|
|
Why: workspace metadata and PnP dependency graph are generated at root.
|
|
|
|
## 4) Configure Yarn SDK for VS Code
|
|
|
|
Run:
|
|
|
|
```bash
|
|
yarn dlx @yarnpkg/sdks vscode
|
|
```
|
|
|
|
Then in VS Code:
|
|
|
|
1. Open Command Palette
|
|
2. Run TypeScript: Select TypeScript Version
|
|
3. Choose Use Workspace Version
|
|
4. 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. Run yarn dlx @yarnpkg/sdks vscode
|
|
2. Select Use Workspace Version
|
|
3. Restart TS Server
|
|
4. 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:
|
|
|
|
```bash
|
|
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
|