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

> Explore the Kaneo build tools and scripts for managing your TurboRepo monorepo. This guide covers pnpm, npm-style scripts, and task orchestration in turbo.json.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-04

---

**The usekaneo/kaneo repository uses a pnpm monorepo managed by TurboRepo with npm-style scripts in [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) and task orchestration in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/package.json) defines entry-point commands, while [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) specifies how tasks depend on each other across packages.

The [`package.json`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) at the repository root defines task relationships and caching behavior. Lines 5-9 configure the core **build task**:

```json
{
  "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

```bash

# Clone and install

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

```

### Daily Development

```bash

# Start full development environment (API + Web)

pnpm dev

# Verify code changes before committing

pnpm lint
pnpm test

```

### Production Preparation

```bash

# Create optimized builds for deployment

pnpm build

# Validate against real database

pnpm test:integration

```

### Internationalization Maintenance

```bash

# 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`](https://github.com/usekaneo/kaneo/blob/main/package.json) | Repository root | Top-level scripts and pnpm workspace configuration |
| [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) | Repository root | TurboRepo task definitions and caching rules |
| [`CLAUDE.md`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.