# 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