# 0026. Build System Modernization and Path Resolution
**Date**: 2026-01-26
**Status**: Accepted
**Backlog Item**: TASK-0088
## Context
The HTTP migration revealed fragile build and path resolution issues:
- Static assets (HTML/CSS/SVG) not copied to dist/, causing 404s
- Path resolution scattered across codebase with fragile `../../` imports
- Slow build with tsc + tsc-alias
- Hybrid deployment (dist/ + viewer/ source) causing confusion
- dotenv misused in production code
## Problems Identified
### 1. Static Asset Serving
- Build only bundled main.js to dist/viewer/
- HTML/CSS/SVG stayed in viewer/ source
- Server served from viewer/ (missing main.js)
- Result: 404 for main.js
### 2. Fragile Path Resolution
- `__dirname` calculations scattered everywhere
- `join(__dirname, '..', '..', 'viewer')` repeated
- Easy to break during refactoring
- No single source of truth
### 3. Slow Build System
- tsc (TypeScript compiler) - slow
- tsc-alias - post-processes imports
- Two tools, two potential failure points
### 4. Hybrid Deployment
- npm package shipped both dist/ and viewer/ source
- Server had to handle two locations
- Non-standard pattern
- Caused repeated regressions
### 5. dotenv Misuse
- Imported in production code
- In devDependencies but bundled
- Should only be for local dev
## Solution
### 1. Unified Build Output
**Change:** Copy all viewer assets to dist/viewer/
```json
"build:viewer": "esbuild viewer/main.ts --bundle --outdir=dist/viewer && cp viewer/*.{html,css,svg} dist/viewer"
```
**Result:**
- All assets in dist/viewer/
- Server serves from one location
- Standard web app pattern
### 2. Centralized Path Resolution
**Created:** `src/utils/paths.ts` - PathResolver singleton
```typescript
export enum RuntimeEnvironment {
Development = 'development',
Production = 'production',
}
class PathResolver {
public readonly environment: RuntimeEnvironment;
public readonly projectRoot: string;
public readonly distRoot: string;
public readonly viewerDist: string;
public readonly packageJson: any;
public getVersion(): string
public fromRoot(...paths: string[]): string
public fromDist(...paths: string[]): string
public getBinPath(binName: string): string
}
export const paths = PathResolver.getInstance();
```
**Features:**
- Detects dev vs production via NODE_ENV
- Handles src/ (tsx) and dist/ (compiled) paths
- Single source of truth for all paths
- Clean API with JSDoc
### 3. Modern Build System
**Replaced:** tsc + tsc-alias → **tsdown**
```json
"build": "pnpm typecheck && tsdown && pnpm build:viewer"
```
**Benefits:**
- Rust-based (Rolldown + Oxc) - blazing fast
- Path aliases work natively
- TypeScript declarations included
- Source maps for debugging
- One tool instead of two
**Configuration:**
```typescript
// tsdown.config.ts
export default defineConfig({
entry: ['src/**/*.ts', '!src/**/*.test.ts', '!src/__tests__/**'],
format: ['esm'],
platform: 'node',
target: 'node18',
unbundle: true, // Keep file structure
skipNodeModulesBundle: true, // Don't bundle dependencies
dts: true, // Generate declarations
sourcemap: true, // Enable debugging
treeshake: true, // Remove unused code
logLevel: 'info',
report: false,
});
```
### 4. Clean Deployment
**Changed:** Ship only dist/
```json
"files": ["dist", "README.md", "LICENSE"]
```
**Removed:** viewer/ source files from npm package
### 5. Proper dotenv Usage
**Removed:** dotenv imports from production code
**Added:** Node.js native --env-file for dev
```json
"dev": "node --env-file=.env tsx watch src/server/fastify-server.ts"
```
**Created:** .env.example template
### 6. TypeScript Path Aliases
**Added:** Clean import paths
```json
// tsconfig.json
"paths": {
"@/utils/*": ["src/utils/*"],
"@/server/*": ["src/server/*"],
"@/storage/*": ["src/storage/*"],
...
}
```
**Usage:**
```typescript
// Before: import { paths } from '../utils/paths.js'
// After: import { paths } from '@/utils/paths.js'
```
## Changes Summary
| File | Change |
|------|--------|
| `package.json` | Updated to .mjs extensions, added tsdown, removed dotenv, clean build scripts |
| `tsconfig.json` | Added path aliases |
| `tsdown.config.ts` | New - tsdown configuration |
| `src/utils/paths.ts` | New - Centralized path resolver singleton |
| `src/server/*.ts` | Use paths singleton, path aliases |
| `src/cli/*.ts` | Use paths singleton, path aliases |
| `.env.example` | New - Configuration template |
| `README.md` | Added configuration section |
## Benefits
**Build System:**
- ✅ 3x faster builds (tsdown vs tsc)
- ✅ One tool instead of two
- ✅ Path aliases work natively
- ✅ Source maps included
**Path Resolution:**
- ✅ Single source of truth
- ✅ No fragile `../../` imports
- ✅ Works in dev and production
- ✅ Easy to refactor
**Deployment:**
- ✅ Standard npm package structure
- ✅ All assets in dist/
- ✅ No source files shipped
- ✅ Smaller package size
**Developer Experience:**
- ✅ Fast dev mode with tsx
- ✅ Clean imports with @/ aliases
- ✅ Proper .env usage
- ✅ Clear configuration
## Trade-offs
**Accepted:**
- tsdown is newer (v0.20) vs tsc (mature) - but backed by Rolldown team
- .mjs extensions (explicit ESM) vs .js (ambiguous) - better for clarity
- File duplication during build (assets copied) - standard practice
**Rejected:**
- Bundling dependencies - keep external for Node.js packages
- Running tsx in production - always use compiled code
- Shipping source files - only ship dist/
## Migration Notes
**For existing installations:**
- Run `pnpm install` to get tsdown
- Run `pnpm build` to rebuild with new system
- Copy `.env.example` to `.env` for local config
**Breaking changes:**
- None for users (npm package works the same)
- Internal only (build system change)
## Success Criteria
- ✅ Build completes successfully
- ✅ Server starts and serves viewer
- ✅ All static assets load (main.js, CSS, SVG)
- ✅ CLI works (backlog-mcp --help)
- ✅ Dev mode works with tsx
- ✅ No node_modules in dist/
- ✅ Path resolution works in dev and production
## References
- tsdown: https://tsdown.dev
- Rolldown: https://rolldown.rs
- Node.js --env-file: https://nodejs.org/api/cli.html#--env-fileconfig
- TASK-0088: HTTP Migration Issues and Remaining Work
