Refactor code structure for improved readability and maintainability; remove redundant code blocks and optimize function calls.
This commit is contained in:
marco.chan committed
1 parent
76a3921782
commit
534fa6dc51
55 files changed
+9274
No files matched your search
@@ -0,0 +1,303 @@
|
||||
# From Express + SQL to Monorepo with Nest Fastify, Vite React, and trest
|
||||
|
||||
This guide is for developers who already know Express APIs and SQL, and are new to Yarn workspaces, NestJS, and private package usage.
|
||||
|
||||
## 1) What You Are Building
|
||||
|
||||
Target architecture:
|
||||
|
||||
- Backend API: NestJS on Fastify
|
||||
- Frontend: Vite + React + Ant Design
|
||||
- Shared/private integration: trest in an isolated adapter package
|
||||
- Monorepo manager: Yarn workspaces
|
||||
|
||||
Why this shape:
|
||||
|
||||
- Keep your main backend on a scalable Fastify stack.
|
||||
- Evaluate trest without coupling everything to Koa ecosystem packages.
|
||||
- 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 Safely
|
||||
|
||||
Recommended approach:
|
||||
|
||||
- Keep trest usage in a dedicated package, for example packages/trest-adapter.
|
||||
- Expose only framework-agnostic functions from that adapter.
|
||||
- Avoid leaking Koa-specific types into app-wide contracts.
|
||||
|
||||
Starter commands:
|
||||
|
||||
```bash
|
||||
mkdir -p packages/trest-adapter
|
||||
cd packages/trest-adapter
|
||||
yarn init -y
|
||||
yarn add @jig-software/trest koa @koa/router koa-body path-to-regexp zod bson
|
||||
```
|
||||
|
||||
Checkpoint:
|
||||
|
||||
- Importing trest from adapter works.
|
||||
|
||||
### Step G: Wire API and Web
|
||||
|
||||
- Add one simple API endpoint in Nest.
|
||||
- Call endpoint from React page.
|
||||
- Render 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/
|
||||
packages/
|
||||
trest-adapter/
|
||||
docs/
|
||||
package.json
|
||||
yarn.lock
|
||||
.yarnrc.yml
|
||||
```
|
||||
|
||||
## 7) Root vs Workspace Dependency Rules
|
||||
|
||||
Use these rules to avoid confusion:
|
||||
|
||||
1. Put backend runtime dependencies in apps/api.
|
||||
2. Put frontend runtime dependencies in apps/web.
|
||||
3. Put trest boundary dependencies in packages/trest-adapter.
|
||||
4. Keep root dependencies minimal and mostly tooling.
|
||||
5. 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.
|
||||
Reference in new issue
Block a user