chore(development-methodology): 🔧 Update documentation files (DEVELOPMENT_METHODOLOGY.md, FEATURE_CONVENTIONS.md) with latest best practices
This commit is contained in:
Quinn Ftw
parent
e9c4d5cd49
commit
f64b499f9e
3 changed files with 187 additions and 24 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue