Kemma Docs

Appearance

Development Scripts ​

This monorepo uses Turborepo and npm workspaces for managing dependencies and tasks across projects.

Quick Start ​

  1. Install Dependencies:

    bash
    npm install
cd apps/server && uv sync

  2. Start Development:

    bash
    npm run dev

    This will start both the Frontend (Port 5173) and Backend (Port 8000) in parallel using Turbo.

Available Commands ​

Development ​

  • npm run dev: Start both web-client and server in parallel.
  • turbo dev --filter=web-client: Start only the web-client.
  • turbo dev --filter=server: Start only the server.

Quality Checks ​

  • npm run check: Runs typecheck, lint, and test for all projects.
  • npm run lint: Lint code (ESLint, Ruff).
  • npm run format: Format code (Prettier, Ruff).
  • npm run typecheck: Check types (TypeScript, Pyright).
  • npm run test: Run tests (Vitest, Pytest).

Build ​

  • npm run build: Build the web-client for production.

Cleanup ​

  • npm run clean: Remove build artifacts and cache directories.

Workspace Structure ​

  • apps/web-client: React Frontend.
  • apps/server: Python FastAPI Backend.
  • turbo.json: Configuration for the build pipeline.

Turbo Tips ​

  • Caching: Turbo caches the output of tasks. If you run npm run check twice without changing code, the second run will be instant.
  • Filtering: You can run a command for a specific workspace using --filter.
    • Example: turbo test --filter=server
  • Graph: Visualize the dependency graph with npx turbo graph.

Build Architecture ​

Monorepo Setup ​

This project uses a modern monorepo architecture powered by TurboRepo and npm workspaces.

  • npm workspaces: Links dependencies between packages and allows them to share a root node_modules folder, reducing disk space and install times.
  • TurboRepo: Orchestrates build tasks (dev, build, lint, etc.) across the workspace with intelligent caching and parallel execution.

Package Configuration ​

Each application (e.g., web-client, server, docs) acts as an independent workspace.

Why does apps/docs have its own package.json? ​

Yes, apps/docs requires its own package.json. In a monorepo, every workspace must define:

  1. Identity: Its name and version.
  2. Scripts: Specific commands (e.g., vitepress dev) that TurboRepo invokes.
  3. Dependencies: Libraries unique to that workspace (e.g., vitepress is only needed for the docs, not the server).

Why does apps/docs have its own node_modules? ​

While npm workspaces hoist most dependencies to the root node_modules, apps/docs may still have a small local node_modules folder. This is normal and happens when:

  • Binaries (like the vitepress CLI) need to be executable within the specific workspace scope.
  • Version conflicts prevent hoisting specific packages to the root.