marco-trest-test/docs/express-sql-to-monorepo-guide.md

# From Express + SQL to Monorepo with Koa, Vite React, and trest

This guide is for developers who already know Express APIs and SQL, and are new to Yarn workspaces, Koa, and private package usage.

## 1) What You Are Building

Target architecture:

- Backend API: Koa + trest
- Frontend: Vite + React + Ant Design
- Monorepo manager: Yarn workspaces

Why this shape:

- Keep the HTTP API on Koa so it matches trest's router.
- Keep one repo and one lockfile for easier onboarding.

## 2) Mental Map (Old to New)

If you came from Express + SQL, map concepts like this:

- Express app -> Nest application
- Express route handler -> Nest controller method
- Express middleware -> Nest middleware/guards/interceptors
- Service classes (manual) -> Nest providers with dependency injection
- SQL repository/service layer -> same idea in Nest modules
- One project folder -> monorepo with apps and packages

## 3) Your Current Repo State

Current important files and meaning:

- Root package.json: defines Yarn workspaces and root dependencies
- .yarnrc.yml: private registry and auth settings for company packages
- apps/api: backend app workspace
- docs/*: onboarding and test notes

Current private registry behavior:

- Scope @jig-software points to Gitea npm endpoint
- Auth token comes from JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN
- nodeLinker is PnP (not node_modules)

## 4) Core Concepts You Must Know First

### Yarn Workspaces

One repo with many packages/apps. Each workspace has its own package.json.

- Root should hold shared tooling only.
- App-specific dependencies should stay in the app workspace.

### PnP (Plug'n'Play)

Yarn resolves dependencies without creating a large node_modules tree.

- Pros: faster installs, stricter dependency boundaries.
- Cons: missing peer dependencies fail earlier and louder.

### Peer Dependencies

A package can require your app to provide certain dependencies.

Example here:

- trest expects koa, @koa/router, koa-body, path-to-regexp, zod, bson as peers.

If peers are missing under PnP, imports can fail at runtime.

### Why You Saw Peer Warnings

You previously installed some Nest dependencies in root workspace.
Then Yarn expected root-level peer providers there.

Fix pattern:

- Keep Nest dependencies inside apps/api only.
- Keep root focused on workspace orchestration.

## 5) Step-by-Step Learning Path

Do this sequence in order and verify at each checkpoint.

### Step A: Verify Toolchain

```bash
node -v
yarn -v
yarn workspaces list
```

Checkpoint:

- You can see root workspace and apps/api workspace.

### Step B: Verify Private Package Access

```bash
export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-token>"
yarn npm info @jig-software/trest
```

Checkpoint:

- You see trest package metadata and versions.

### Step C: Backend Workspace Hygiene

From repo root, ensure Nest runtime dependencies live in apps/api.

Important:

- Your current workspace name may be api-npx even if the folder is apps/api.
- Check the name field in apps/api/package.json and use that in yarn workspace commands.

```bash
yarn workspace api-npx add @nestjs/platform-fastify fastify reflect-metadata rxjs
yarn workspace api-npx remove @nestjs/platform-express
```

Checkpoint:

- apps/api package contains fastify platform and no express platform.

### Step D: Start Backend

```bash
yarn workspace api-npx start:dev
```

If you rename the workspace package name to api, the command becomes:

```bash
yarn workspace api start:dev
```

Checkpoint:

- API starts successfully.

### Step E: Create Frontend Workspace

```bash
yarn create vite apps/web --template react-ts
cd apps/web
yarn
yarn add antd @ant-design/icons
```

Add style reset import in app entry:

```ts
import "antd/dist/reset.css";
```

Checkpoint:

- Vite app runs and Ant Design components render.

### Step F: Introduce trest on the API

Install trest and its Koa peers in `apps/api`:

```bash
yarn workspace api add @jig-software/trest koa @koa/router koa-body path-to-regexp zod bson
```

Checkpoint:

- `GET /greeting?name=Marco` returns a JSON greeting from the Koa app.

### Step G: Wire API and Web

- Call `/greeting` from a React page.
- Render the response using an Ant Design component.

Checkpoint:

- Browser request reaches backend and returns expected payload.

## 6) Suggested Repo Layout

```text
marco-trest-test/
  apps/
    api/
    web/
  docs/
  package.json
  yarn.lock
  .yarnrc.yml
```

## 7) Root vs Workspace Dependency Rules

Use these rules to avoid confusion:

1. Put Koa, trest, and other backend runtime dependencies in apps/api.
2. Put frontend runtime dependencies in apps/web.
3. Keep root dependencies minimal and mostly tooling.
4. Run installs from root unless targeting one workspace intentionally.

## 8) Troubleshooting You Are Likely to Hit

### Debugger feels broken in monorepo

Common causes:

- VS Code TypeScript server is not using Yarn SDK under PnP.
- No workspace launch/tasks config exists for API + web.

Fix checklist:

```bash
yarn dlx @yarnpkg/sdks vscode
```

Then in VS Code:

1. Run command: TypeScript: Select TypeScript Version
2. Choose: Use Workspace Version
3. Restart TypeScript server if diagnostics look stale

Use debug profiles from `.vscode/launch.json`:

- API: Attach Nest (9229)
- Web: Chrome (Vite 5173)
- Full Stack Debug

They depend on tasks in `.vscode/tasks.json` that start each app in watch mode.

### Nest scaffold error: collection cannot be resolved

Symptom:

- Error resolving @nestjs/schematics with yarn dlx under this setup.

Workaround:

```bash
CI=1 npx -y @nestjs/cli new apps/api --skip-git --package-manager yarn --strict
```

### Peer dependency warnings for reflect-metadata and rxjs

Cause:

- Nest packages in root workspace.

Fix:

- Move/add those dependencies in apps/api workspace.

### 404 on yarn npm whoami

Cause:

- Endpoint may not support whoami.

Fix:

- Use yarn npm info @jig-software/trest to verify access.

## 9) How to Decide if trest Is Right for Future Projects

Use this checklist:

- Type safety benefit vs integration complexity
- Runtime coupling to Koa ecosystem
- Team familiarity and onboarding cost
- Performance and operational fit
- Exit strategy if you stop using trest

Practical policy many teams use:

- Allow trest in adapter layer first.
- Keep core services on standard Nest Fastify patterns.
- Reassess after one pilot project.

## 10) 30-Minute Practice Plan

1. Run Step A and Step B.
2. Start backend in Step D.
3. Create web in Step E.
4. Add one API call from web to backend.
5. Write what was easy/hard in your notes.

If you can complete this once, you have a strong foundation for real project work.