Monorepo Architecture and Tooling

The THLSPress project is structured as a monorepo to facilitate efficient development, code sharing, and consistent tooling across its various parts. This document details the structure and the key technologies that power our workflow.

Directory Structure Overview

The root directory contains several key folders, each with a specific purpose:

• thlspress-cms/ (Workspace Root)
  • cms/: The core Next.js application. This package is the deployable CMS that end-users will host. It contains all the essential UI, API routes, and business logic for the base system.
  • packages/: A directory for internal tools and shared libraries that support the ecosystem but are not part of the core CMS application itself.
    • cli/: Source code for the thlspress-cli command-line tool. This package is compiled and published to NPM.
    • e2e-tests/: Contains all end-to-end and integration tests for the system. It runs against a live instance of the cms application to ensure all parts work together correctly.
  • templates/: A collection of official, versioned module templates (e.g., reservation, store). These are not "active" code but rather blueprints that the CLI uses to install new features.
  • docs/: The source files for this documentation.

Core Tooling

PNPM Workspaces

PNPM is the package manager of choice for this monorepo, configured via pnpm-workspace.yaml.

Key Advantages:

• Disk Space Efficiency: PNPM utilizes a content-addressable store and symlinks to avoid duplicating dependencies. A single version of a package is stored only once on the disk, regardless of how many projects use it.
• Installation Speed: The symlink-based approach makes installation and updates significantly faster than traditional package managers.
• Strict Isolation (No Phantom Dependencies): A package can only access dependencies that are explicitly listed in its package.json. This prevents bugs caused by accidentally relying on transitive dependencies and improves code reliability.

Turborepo

Turborepo acts as the high-performance build system and task runner for the monorepo, configured via turbo.json.

Key Advantages:

• Intelligent Task Orchestration: With a single command like pnpm build, Turborepo can run the build script in all packages, respecting dependencies between them and executing tasks in parallel for maximum speed.
• Remote Caching: Turborepo caches the output of tasks (e.g., build artifacts, test results). If the source files for a task haven't changed since the last run, Turborepo skips the execution and restores the result from the cache. This is a game-changer for CI/CD times and local development.
• Scoped Tasks: Easily run tasks on a subset of the monorepo, for example, only on packages that have changed since the last commit.