diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ddf099d..6af6d1f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,10 +29,15 @@ git clone https://github.com/yourusername/YieldVault-RWA.git cd YieldVault-RWA # Install dependencies -npm ci # Backend -cd frontend && npm ci # Frontend +pnpm install + +# Build shared packages (required before backend type-checking or building) +npm run build:schemas # Or: cd packages/api-schemas && npm run build ``` +> **Important (Build Order):** The `@yieldvault/api-schemas` package must be built prior to running TypeScript (`tsc`), local type-checking, or building the backend. Running `npm run build` or `npm run dev` in the backend will automatically execute `build:schemas` via `prebuild`/`predev` hooks, but manual `tsc --noEmit` invocations require `dist` in `packages/api-schemas` to be generated first. + + ### Environment Configuration Copy environment templates and configure for local development: diff --git a/backend/docs/REQUEST_VALIDATION.md b/backend/docs/REQUEST_VALIDATION.md index 1f5af5c1..a12a6efa 100644 --- a/backend/docs/REQUEST_VALIDATION.md +++ b/backend/docs/REQUEST_VALIDATION.md @@ -36,6 +36,9 @@ webhook register/update reject unknown keys). | `backend/src/middleware/validate.ts` | Auth, alias, webhook register schemas + middleware | | `packages/api-schemas` | Shared vault deposit/withdrawal contracts | +> **Build Order:** The `@yieldvault/api-schemas` package must be built (`npm run build:schemas` or `npm run build` in backend) before TypeScript typechecking (`tsc --noEmit`) can resolve types imported by `backend/src/middleware/validate.ts`. + + ## Common rules - **Stellar addresses** on login/nonce: checksummed `G…` public keys. diff --git a/backend/package.json b/backend/package.json index c35e25d3..470e7e18 100644 --- a/backend/package.json +++ b/backend/package.json @@ -4,11 +4,14 @@ "description": "YieldVault Stellar RWA Backend API", "main": "dist/index.js", "scripts": { + "predev": "npm run build:schemas", "dev": "tsx watch src/index.ts", + "build:schemas": "npm --prefix ../packages/api-schemas run build", + "prebuild": "npm run build:schemas && npm run prisma:generate", "prebuild": "npm run prisma:generate", "build": "npm run prisma:generate && tsc", "build": "tsc", - "pretypecheck": "npm run prisma:generate", + "pretypecheck": "npm run build:schemas && npm run prisma:generate", "typecheck": "tsc --noEmit", "start": "node dist/index.js", "test": "jest --runInBand --coverage", diff --git a/docs/CONTRIBUTOR_ONBOARDING_CHECKLIST.md b/docs/CONTRIBUTOR_ONBOARDING_CHECKLIST.md index bc148369..133288a8 100644 --- a/docs/CONTRIBUTOR_ONBOARDING_CHECKLIST.md +++ b/docs/CONTRIBUTOR_ONBOARDING_CHECKLIST.md @@ -153,8 +153,13 @@ cd YieldVault-RWA # Install root-level dependencies (Husky git hooks, etc.) npm install + +# Build shared packages (build order requirement before backend typecheck or dev) +npm run build:schemas ``` +> **Build Order Requirement:** `@yieldvault/api-schemas` must be built before local typechecking or starting the backend. Without this step, `tsc --noEmit` fails because `backend/src/middleware/validate.ts` imports `@yieldvault/api-schemas`. + ### Verify Git Hooks ```bash @@ -171,7 +176,7 @@ ls .husky/pre-commit ```bash cd backend -# Install dependencies +# Install dependencies (prebuild/predev will build api-schemas automatically) npm install # Create environment file from template diff --git a/docs/LOCAL_DEV_BOOTSTRAP.md b/docs/LOCAL_DEV_BOOTSTRAP.md index ffb8781e..e70b9807 100644 --- a/docs/LOCAL_DEV_BOOTSTRAP.md +++ b/docs/LOCAL_DEV_BOOTSTRAP.md @@ -56,6 +56,12 @@ git config core.hooksPath .husky Install dependencies for each application separately: ```bash +# Build shared API schemas first (required before backend typecheck or build) +cd packages/api-schemas +npm install +npm run build +cd .. + cd backend npm install cd ../frontend @@ -63,6 +69,8 @@ npm install cd .. ``` +> **Note on Build Order:** `@yieldvault/api-schemas` is a workspace package imported by backend middleware (`backend/src/middleware/validate.ts`). Without building `packages/api-schemas` first, TypeScript compilation (`tsc --noEmit`) fails with `Cannot find module '@yieldvault/api-schemas'`. Always ensure `packages/api-schemas` is built first (or use root `npm run build:schemas`). + If a workspace uses a lockfile, prefer the package manager and frozen-lockfile command specified by that lockfile and by CI. ## 2. Configure the backend diff --git a/package.json b/package.json index be9b0cf8..6d94b23b 100644 --- a/package.json +++ b/package.json @@ -23,9 +23,12 @@ "test": "vitest run", "lint:staged": "lint-staged", "commitlint": "commitlint", + "build:schemas": "npm --prefix packages/api-schemas run build", + "build": "pnpm build:schemas && pnpm --filter backend build && pnpm --filter frontend build", + "typecheck": "pnpm build:schemas && pnpm --filter backend typecheck && pnpm --filter frontend build", "dev": "concurrently \"pnpm:dev:backend\" \"pnpm:dev:frontend\"", - "dev:backend": "bash scripts/wait-for-db.sh && pnpm --filter backend dev", - "dev:frontend": "pnpm --filter frontend dev", + "dev:backend": "pnpm build:schemas && bash scripts/wait-for-db.sh && pnpm --filter backend dev", + "dev:frontend": "pnpm build:schemas && pnpm --filter frontend dev", "wait-for-db": "bash scripts/wait-for-db.sh", "test": "pnpm --filter backend test -- --runInBand --coverage && pnpm --filter frontend test --run", "test:backend": "pnpm --filter backend test -- --runInBand --coverage",