Building Guide

March 10, 2026 · View on GitHub

Guide to building Shep AI CLI for development and distribution.

Build System

Shep uses the TypeScript compiler (tsc) with tsc-alias for building:

  • Standard TypeScript compilation via tsconfig.build.json
  • Path alias resolution via tsc-alias
  • Web UI built separately with Next.js and copied to web/ for distribution

Build Commands

Development Build

# Start the web dev server
pnpm dev

# Or run CLI and web separately
pnpm dev:cli    # Run CLI via ts-node
pnpm dev:web    # Start Next.js dev server

Production Build

pnpm build

Output goes to dist/ (mirroring src/ structure with compiled .js files).

Type Checking

# Check types without emitting
pnpm typecheck

# Watch mode
pnpm typecheck:watch

Build Pipeline

The CLI build command (pnpm build) runs:

tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && pnpm build:web:prod
  1. tsc -p tsconfig.build.json - Compiles TypeScript to JavaScript in dist/
  2. tsc-alias -p tsconfig.build.json - Resolves @/ path aliases to relative paths
  3. pnpm build:web:prod - Builds the Next.js web UI and copies output to web/

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

Build Outputs

Compiled JavaScript

Output goes to dist/ mirroring the src/ directory structure:

dist/
├── src/
│   ├── presentation/
│   │   ├── cli/         # CLI entry point
│   │   ├── tui/         # TUI components
│   │   └── web/         # Web server integration
│   └── ...
└── packages/
    └── core/
        └── src/         # Core business logic

Web UI Output

The Next.js web UI is built separately and copied to web/ for distribution:

web/                     # Pre-built Next.js output (in .gitignore)

CLI Executable

Package.json bin configuration:

{
  "bin": {
    "shep": "./dist/src/presentation/cli/index.js"
  }
}

Dependencies

Runtime Dependencies

Only essential dependencies for production:

{
  "dependencies": {
    "commander": "^12.0.0",
    "better-sqlite3": "^9.0.0"
  }
}

Build Dependencies

Development-only:

{
  "devDependencies": {
    "typescript": "^5.3.0",
    "tsc-alias": "^1.8.0",
    "@types/node": "^20.0.0",
    "@types/better-sqlite3": "^7.0.0"
  }
}

Native Modules

better-sqlite3 requires native compilation:

# Rebuild for current platform
npm rebuild better-sqlite3

# Or during install
npm install --build-from-source

For distribution, we use prebuild:

{
  "scripts": {
    "install": "prebuild-install || node-gyp rebuild"
  }
}

Build Scripts

Clean Build

pnpm clean && pnpm build

Clean script:

{
  "scripts": {
    "clean": "rimraf dist coverage"
  }
}

Package for npm

pnpm build
npm pack

Creates shep-ai-cli-x.x.x.tgz.

Publish

pnpm build
npm publish --access public

Build Optimization

Source Maps

Source maps are generated by tsc when sourceMap: true is set in tsconfig.build.json.

Debugging Builds

Check Output Size

pnpm build
du -sh dist/*

Continuous Integration

Build Matrix

# .github/workflows/build.yml
jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: pnpm build

Release Build

# .github/workflows/release.yml
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: pnpm build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Maintaining This Document

Update when:

  • Build tooling changes
  • TypeScript configuration changes
  • New build targets added
  • Dependency requirements change

Related docs: