xtablo-source/docs/API_TURBOREPO_INTEGRATION.md

API Turborepo Integration

Overview

The api folder has been successfully integrated into the Turborepo monorepo structure. This document outlines the changes made and how to work with the API in the new setup.

Changes Made

1. Folder Structure

• Before: api/ (root level)
• After: apps/api/ (inside apps directory)

The API has been moved to the apps directory to follow the monorepo convention where all applications live under apps/ and shared packages live under packages/.

2. Package Configuration

Updated apps/api/package.json

{
  "name": "@xtablo/api",           // Changed from "xtablo-api"
  "private": true,                 // Added
  "version": "1.0.0",              // Added version
  "scripts": {
    "typecheck": "tsc --noEmit",   // Added typecheck script
    "clean": "rm -rf dist node_modules/.cache"  // Added clean script
  }
}

Created apps/api/turbo.json

Turbo configuration for the API app with specific task definitions for build, dev, and test.

Created apps/api/biome.json

Biome configuration for linting and formatting, consistent with other apps.

3. Root Configuration Updates

Updated package.json

Added API-specific scripts:

{
  "scripts": {
    "dev:api": "turbo dev --filter=@xtablo/api",
    "test:api": "turbo test --filter=@xtablo/api"
  }
}

Updated biome.json

Changed all references from api/ to apps/api/ in:

• File includes
• Override paths

Updated apps/api/cloudbuild.yaml

Changed Docker build context from api to apps/api.

4. Workspace Integration

The API is now automatically included in the pnpm workspace via the existing apps/* pattern in pnpm-workspace.yaml.

5. Documentation Updates

Updated all Stripe-related documentation files to reference cd apps/api instead of cd api:

• docs/STRIPE_IMPLEMENTATION_SUMMARY.md
• docs/TESTING_WITH_FAKE_ACCOUNTS.md
• docs/STRIPE_README.md
• docs/STRIPE_WITH_SYNC_ENGINE.md
• docs/STRIPE_INTEGRATION_COMPLETE.md
• docs/STRIPE_QUICK_REFERENCE.md
• docs/STRIPE_SETUP.md
• docs/STRIPE_FINAL_SETUP.md

6. Package Lock Files

• Removed apps/api/package-lock.json (npm lock file)
• Updated pnpm-lock.yaml to include the API package

Usage

Running Commands from Root

All turbo commands can now be run from the root directory with the --filter flag:

# Development
pnpm run dev:api

# Building
turbo build --filter=@xtablo/api

# Testing
pnpm run test:api
turbo test --filter=@xtablo/api

# Type checking
turbo typecheck --filter=@xtablo/api

# Linting and formatting
turbo lint --filter=@xtablo/api
turbo lint:fix --filter=@xtablo/api
turbo format --filter=@xtablo/api

# Clean build artifacts
turbo clean --filter=@xtablo/api

Running Commands from API Directory

All existing npm scripts still work when you're inside the apps/api directory:

cd apps/api

# Development
pnpm dev

# Build
pnpm build

# Test
pnpm test
pnpm test:watch

# Lint
pnpm lint
pnpm lint:fix

Running All Apps Together

You can now run all apps in parallel using turbo:

# Run dev for all apps
pnpm run dev

# Build all apps
pnpm run build

# Lint all apps
pnpm run lint

# Test all apps
pnpm run test

Benefits

1. Consistent Tooling: The API now uses the same build tools (Turbo, pnpm) as other apps
2. Parallel Execution: Turbo can run API tasks in parallel with other apps
3. Caching: Turbo's caching mechanism speeds up builds and tests
4. Dependency Management: Shared dependencies are deduplicated by pnpm
5. Workspace Support: Easy to share code between the API and other packages
6. Better DX: Unified commands across all apps

Verification

All tests pass:

• ✅ Type checking: turbo typecheck --filter=@xtablo/api
• ✅ Linting: turbo lint --filter=@xtablo/api (with auto-fix applied)
• ✅ Tests: turbo test --filter=@xtablo/api (67 tests passing)
• ✅ Build: turbo build --filter=@xtablo/api

Notes

• The API's Docker configuration (Dockerfile and cloudbuild.yaml) has been updated to reference the new path
• All import sorting issues were automatically fixed with biome
• The API maintains its existing functionality and dependencies
• No changes to the API's runtime behavior or endpoints