From f64b499f9e911e9182ae30b7fbebf0e14b49eadd Mon Sep 17 00:00:00 2001 From: Quinn Ftw Date: Wed, 21 Jan 2026 12:26:16 -0800 Subject: [PATCH] =?UTF-8?q?chore(development-methodology):=20=F0=9F=94=A7?= =?UTF-8?q?=20Update=20documentation=20files=20(DEVELOPMENT=5FMETHODOLOGY.?= =?UTF-8?q?md,=20FEATURE=5FCONVENTIONS.md)=20with=20latest=20best=20practi?= =?UTF-8?q?ces?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- development/DEVELOPMENT_METHODOLOGY.md | 140 ++++++++++++++++++++++ technical/features/FEATURE_CONVENTIONS.md | 8 +- technical/features/FEATURE_STRUCTURE.md | 63 ++++++---- 3 files changed, 187 insertions(+), 24 deletions(-) diff --git a/development/DEVELOPMENT_METHODOLOGY.md b/development/DEVELOPMENT_METHODOLOGY.md index 338c618..85a9bc0 100644 --- a/development/DEVELOPMENT_METHODOLOGY.md +++ b/development/DEVELOPMENT_METHODOLOGY.md @@ -408,6 +408,146 @@ Official releases are published via Forgejo CI: 3. CI builds and publishes to `npm.nasty.sh:4873` (Verdaccio) 4. Version follows semantic versioning +### 4. Build Tooling Standard + +The platform uses a unified build tooling approach based on context: + +| Context | Build Tool | Config Files | Module Resolution | +|---------|------------|--------------|-------------------| +| Libraries (`~/Code/@packages/@ts`) | tsup | `tsup.config.ts` | bundler (via tsconfig) | +| NestJS backends | nest build + SWC | `nest-cli.json` + `.swcrc` | NodeNext + resolveFully | +| Frontends | Vite | `vite.config.ts` | bundler (Vite internal) | +| Source-only packages | none | `tsconfig.json` | bundler | + +#### Library Packages (tsup) + +All library packages at `~/Code/@packages/@ts` use **tsup** (esbuild-powered): + +**Standard configuration**: + +```json +// package.json +{ + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "scripts": { + "build": "tsup", + "typecheck": "tsc --noEmit" + } +} +``` + +```typescript +// tsup.config.ts +import { defineConfig } from 'tsup'; + +export default defineConfig({ + entry: ['src/index.ts'], + format: ['esm'], + dts: true, + clean: true, + sourcemap: true, +}); +``` + +```json +// tsconfig.json +{ + "extends": "@lilith/configs/typescript/esm", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src" + }, + "include": ["src/**/*"] +} +``` + +**Why tsup for libraries**: +- Fast (esbuild-powered) +- Generates `.d.ts` files +- Handles ESM output correctly +- Single tool for build + types +- No SWC needed (bundler resolution handles imports) + +#### NestJS Backends (nest build + SWC) + +All NestJS backends in lilith-platform use the **nest build** command with SWC: + +**Standard configuration** (documented in CLAUDE.md): +```json +// nest-cli.json +{ + "compilerOptions": { + "builder": "swc", + "deleteOutDir": true + } +} +``` + +```json +// .swcrc +{ + "module": { + "type": "es6", + "resolveFully": true + } +} +``` + +**Why nest build + SWC**: +- NestJS-specific build features (assets, decorators) +- SWC `resolveFully` handles Node.js ESM imports +- Already standardized across all platform backends + +#### Frontend Applications (Vite) + +All frontend applications use **Vite** with no separate TypeScript compilation: + +```json +// package.json +{ + "scripts": { + "dev": "vite", + "build": "vite build", + "typecheck": "tsc --noEmit" + } +} +``` + +**Why Vite handles everything**: +- Vite does TS transpilation internally (via esbuild) +- No need for `tsc && vite build` +- Faster, simpler + +#### Source-Only Packages (No Build) + +Internal packages consumed only by bundlers (Vite): + +```json +// package.json +{ + "type": "module", + "exports": { + ".": "./src/index.ts" + }, + "scripts": { + "typecheck": "tsc --noEmit" + } +} +``` + +**Why no build**: +- Only consumed by bundlers +- Bundler handles transpilation +- Faster iteration + --- ## Architecture Decision Making diff --git a/technical/features/FEATURE_CONVENTIONS.md b/technical/features/FEATURE_CONVENTIONS.md index c78f0e3..733c171 100644 --- a/technical/features/FEATURE_CONVENTIONS.md +++ b/technical/features/FEATURE_CONVENTIONS.md @@ -49,7 +49,7 @@ pnpm typecheck:all # Type check all features | Script | Purpose | Example | |--------|---------|---------| -| `build` | Compile/bundle the feature | `nest build`, `tsc && vite build` | +| `build` | Compile/bundle the feature | `nest build`, `tsup`, `vite build` | | `typecheck` | Validate TypeScript | `tsc --noEmit` | | `test` or `test:unit` | Run unit tests | `vitest run`, `jest` | | `lint` | Check code quality | `eslint "src/**/*.ts" --fix` | @@ -134,6 +134,8 @@ analytics/backend-api/ **Example**: `codebase/features/status-dashboard/frontend/` +**Build Tool**: Vite (handles TypeScript transpilation internally via esbuild) + **Directory Structure**: ``` status-dashboard/frontend/ @@ -149,7 +151,7 @@ status-dashboard/frontend/ { "scripts": { "dev": "vite", - "build": "tsc && vite build", + "build": "vite build", "preview": "vite preview", "typecheck": "tsc --noEmit", "lint": "eslint . --ext ts,tsx", @@ -158,6 +160,8 @@ status-dashboard/frontend/ } ``` +**Note**: No `tsc &&` prefix needed for build - Vite handles TS transpilation. Use `typecheck` for type validation. + ### Workspace Feature (Multi-Package) **Example**: `codebase/features/conversation-assistant/` diff --git a/technical/features/FEATURE_STRUCTURE.md b/technical/features/FEATURE_STRUCTURE.md index eee5afd..5a6326e 100644 --- a/technical/features/FEATURE_STRUCTURE.md +++ b/technical/features/FEATURE_STRUCTURE.md @@ -441,7 +441,7 @@ portal/frontend-app/ "type": "module", "scripts": { "dev": "vite", - "build": "tsc -b && vite build", + "build": "vite build", "typecheck": "tsc --noEmit", "lint": "eslint .", "preview": "vite preview" @@ -657,26 +657,26 @@ deployments: ## 4. Library Package (TypeScript) -**Example**: `codebase/features/content-moderation/` +**Example**: `~/Code/@packages/@ts/content-moderation/` + +**Build Tool**: tsup (esbuild-powered, fast, handles ESM + types) ### Directory Structure ``` content-moderation/ ├── package.json # Package manifest -├── tsconfig.json # TypeScript config +├── tsconfig.json # TypeScript config (for type checking) +├── tsup.config.ts # Build configuration │ -├── backend-api/ # Optional: API implementation -│ ├── src/ -│ └── package.json +├── src/ # Source code +│ ├── index.ts # Main export +│ ├── types/ # Type definitions +│ ├── validators/ # Validation logic +│ └── utils/ # Utility functions │ -├── shared/ # Shared library code -│ ├── src/ -│ │ ├── index.ts # Main export -│ │ ├── types/ # Type definitions -│ │ ├── validators/ # Validation logic -│ │ └── utils/ # Utility functions -│ └── package.json +├── test/ # Unit tests +│ └── *.spec.ts │ └── dist/ # Build output (gitignored) ``` @@ -700,37 +700,56 @@ content-moderation/ } }, "scripts": { - "build": "tsc", + "build": "tsup", "typecheck": "tsc --noEmit", - "test": "vitest run" - }, - "dependencies": { - "@lilith/other-package": "workspace:*" + "test": "vitest run", + "clean": "rm -rf dist" }, "devDependencies": { + "@lilith/configs": "^1.0.0", "@types/node": "^22.0.0", + "tsup": "^8.0.0", "typescript": "^5.7.0", "vitest": "^4.0.16" } } ``` +#### `tsup.config.ts` + +```typescript +import { defineConfig } from 'tsup'; + +export default defineConfig({ + entry: ['src/index.ts'], + format: ['esm'], + dts: true, + clean: true, + sourcemap: true, +}); +``` + #### `tsconfig.json` ```json { - "extends": "@lilith/typescript-config-base", + "extends": "@lilith/configs/typescript/esm", "compilerOptions": { "outDir": "./dist", - "rootDir": "./src", - "declaration": true, - "declarationMap": true + "rootDir": "./src" }, "include": ["src/**/*"], "exclude": ["node_modules", "dist", "**/*.spec.ts"] } ``` +**Why tsup for libraries**: +- Fast builds (esbuild-powered) +- Generates `.d.ts` type declarations automatically +- Handles ESM output correctly +- Single tool for build + types (replaces tsc) +- No SWC needed (bundler resolution handles imports) + --- ## File Requirements by Feature Type