Kaneo Build Tools and Scripts: Complete Guide to the TurboRepo Monorepo Workflow

The usekaneo/kaneo repository uses a pnpm monorepo managed by TurboRepo with npm-style scripts in package.json and task orchestration in turbo.json.

This guide explores every build tool, script, and configuration file that powers development and deployment in the Kaneo project. Whether you're contributing code or deploying your own instance, understanding these tools ensures efficient workflows across the API and web applications.

Core Build System: pnpm + TurboRepo

Kaneo is structured as a pnpm workspace monorepo with TurboRepo handling task orchestration. This combination provides fast, parallelized builds with intelligent caching. The root package.json defines entry-point commands, while turbo.json specifies how tasks depend on each other across packages.

The package.json scripts are defined at lines 5-16, covering everything from development servers to internationalization utilities.

Available npm Scripts in package.json

Root-level commands provide the primary interface for daily development. Each script delegates to Turbo where appropriate, ensuring consistent behavior across workspace packages.

Development and Build Commands

Script	Purpose	Underlying Tool
pnpm dev	Starts API and web apps in watch mode	turbo dev
pnpm build	Production builds for all packages	turbo build
pnpm lint	Code quality enforcement	turbo lint (Biome)
pnpm test	Unit test execution	turbo test
pnpm test:integration	End-to-end database tests	turbo test:integration

The pnpm dev command is the primary entry point for full-stack development. It concurrently starts both the API server and web interface with hot reloading enabled.

The pnpm build command triggers turbo build, which processes packages in dependency order and caches results to dist/** outputs.

Quality Assurance and Testing

Linting runs Biome across the entire workspace through turbo lint. Tests split into two categories: fast unit tests via pnpm test and slower integration tests requiring a live PostgreSQL connection via pnpm test:integration.

Internationalization Utilities

The pnpm i18n:* namespace contains multiple helper scripts implemented as Node.js modules in scripts/i18n/*.mjs. These handle translation key extraction, validation, and automated fixes for the project's localization workflow.

TurboRepo Configuration in turbo.json

The turbo.json at the repository root defines task relationships and caching behavior. Lines 5-9 configure the core build task:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

This configuration ensures that workspace packages build in topological order—dependencies complete before dependents—and caches the resulting dist/** artifacts.

Key Turbo characteristics in Kaneo:

• Dependency-aware execution — Tasks run in parallel where possible, respecting package interdependencies
• Remote caching support — Build outputs can be shared across CI runs and developer machines
• Input hashing — Only rebuilds when source files or configurations change

Husky Git Hooks

The pnpm prepare script initializes Husky for Git hook management. This runs automatically after pnpm install to ensure:

• Pre-commit linting and formatting
• Pre-push test validation
• Consistent code quality standards across all contributors

Quick Reference: Common Workflows

Initial Setup

# Clone and install

git clone https://github.com/usekaneo/kaneo.git
cd kaneo
pnpm install

Daily Development

# Start full development environment (API + Web)

pnpm dev

# Verify code changes before committing

pnpm lint
pnpm test

Production Preparation

# Create optimized builds for deployment

pnpm build

# Validate against real database

pnpm test:integration

Internationalization Maintenance

# Available i18n utilities

pnpm i18n:check    # Validate translation keys

pnpm i18n:fix      # Auto-correct common issues

pnpm i18n:extract  # Pull new strings from source

Essential Files Reference

File	Location	Purpose
package.json	Repository root	Top-level scripts and pnpm workspace configuration
turbo.json	Repository root	TurboRepo task definitions and caching rules
CLAUDE.md	Repository root	Quick-reference command cheat sheet
scripts/i18n/*.mjs	./scripts/i18n/	Localization helper implementations

All paths follow the repository structure at github.com/usekaneo/kaneo on the main branch.

Summary

• pnpm workspaces manage the monorepo with fast, disk-space-efficient dependency handling
• TurboRepo orchestrates builds, tests, and linting with intelligent parallelization
• Root package.json exposes eight primary script categories: dev, build, lint, test, test:integration, i18n utilities, and prepare
• turbo.json defines task dependencies, with the build task producing cached dist/** outputs
• Husky hooks enforce quality gates on every commit through the prepare script

Frequently Asked Questions

What package manager does Kaneo require?

Kaneo requires pnpm. The repository includes pnpm-workspace.yaml and uses pnpm-specific features that prevent compatibility with npm or yarn. Install pnpm globally before running pnpm install.

How does TurboRepo improve build performance?

TurboRepo caches build outputs to dist/** and shares results across machines when remote caching is configured. It also parallelizes independent tasks—linting and testing can run simultaneously while builds respect package dependencies through the dependsOn: ["^build"] declaration.

Where are the i18n scripts implemented?

Internationalization utilities live in scripts/i18n/*.mjs as standalone Node.js modules. The package.json scripts invoke these directly, for example: "i18n:check": "node ./scripts/i18n/check.mjs".

What triggers Husky installation?

The prepare script runs automatically after pnpm install completes, executing husky to set up Git hooks. This one-time setup ensures linting and testing run before commits without manual configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}