How to Set Up a Development Environment for Cordis: Complete Monorepo Guide

Setting up a Cordis development environment requires cloning the repository, installing Yarn 4 with the node-modules linker, running yarn to install workspace dependencies, and executing yarn build to compile the TypeScript source across the monorepo.

Cordis is a meta-framework organized as a Yarn 4 monorepo that uses workspaces to manage its core runtime, hot-module-replacement utilities, and scaffolding tools. Setting up a local development environment involves configuring the Yarn 4 toolchain, resolving cross-package dependencies, and building the TypeScript source with the yakumo build system. This guide walks through the exact steps required to clone, install, build, and test the Cordis source code according to the cordiverse/cordis repository structure.

Prerequisites

Before cloning the repository, ensure you have Node.js installed (version compatible with Yarn 4) and the Yarn 4 package manager. Cordis specifically configures the node-modules linker in .yarnrc.yml rather than Plug'n'Play, so standard node_modules resolution will apply once dependencies are installed.

Clone the Repository

Start by cloning the Cordis repository from GitHub and navigating into the directory:

git clone https://github.com/cordiverse/cordis.git
cd cordis

Configure Yarn 4 and Install Dependencies

Cordis pins the Yarn 4 node-modules linker via the nodeLinker: node-modules setting in .yarnrc.yml【/cache/repos/github.com/cordiverse/cordis/main/.yarnrc.yml】. This ensures dependencies are hoisted into a single node_modules folder rather than using Plug'n'Play.

The root package.json defines the workspace structure as ["external/*","packages/*"]【/cache/repos/github.com/cordiverse/cordis/main/package.json】, which includes the core runtime, HMR utilities, and create CLI.

If you do not have Yarn 4 installed globally, install it first:

npm i -g yarn@4

Then install all workspace dependencies:

yarn

Running yarn at the repository root resolves all internal and external packages into the shared node_modules directory.

Build the Source with Yakumo

Cordis uses the yakumo build system—a thin wrapper around esbuild, TypeScript compiler (tsc), and Vitest—to compile packages. The root package.json defines a build script that triggers both the esbuild bundler and TypeScript compilation.

Execute the full build across all packages:

yarn build

Internally, yakumo esbuild reads each package-level tsconfig.json (such as packages/core/tsconfig.json) and outputs compiled JavaScript under dist/ directories for every workspace package. This step is necessary before running tests or using the scaffolding CLI.

Run the Test Suite

The Cordis test suite runs on Vitest, configured in vitest.config.ts at the repository root. To execute all unit tests across the workspace:

yarn test

For alternative output formats, use the helper scripts defined in package.json:

• yarn test:text for plain text output
• yarn test:json for JSON reports
• yarn test:html for HTML reports

Develop Individual Packages

Each logical component resides in its own package under packages/:

• packages/core/ contains the core runtime API
• packages/hmr/ implements hot-module-replacement utilities
• packages/loader/ provides the dynamic module loader
• packages/create/ houses the scaffolding CLI

To work on a specific package, navigate to its directory and run tests directly:

cd packages/core
yarn test

Changes to source files in packages/core/src/ will require rebuilding the package or using the HMR test harness for live reload during development.

Scaffold a New Project Using the CLI

The create-cordis CLI, implemented in packages/create/src/index.ts, bootstraps new Cordis applications. After building the monorepo, invoke the CLI via:

node packages/create/src/bin.ts <project-name>

This command executes the full scaffolding lifecycle defined in the source code: it fetches a template from the npm registry, extracts the tarball, stages a compatible Yarn binary via the stageYarnBin implementation, writes a customized package.json, and optionally initializes a Git repository and installs dependencies.

Enable Hot-Module-Replacement (Optional)

If you wish to experiment with HMR during development, the packages/hmr folder contains a full test harness in packages/hmr/tests/. While the HMR utilities are primarily used at runtime in generated applications, you can verify the hot-reload behavior by running the dedicated HMR tests from the workspace root:

cd packages/hmr
yarn test

This spins up a live-reload environment that watches for changes in the source packages and validates the module replacement logic.

Summary

Setting up a Cordis development environment involves these key steps:

• Use Yarn 4 with the node-modules linker as specified in .yarnrc.yml to ensure consistent dependency resolution
• Install workspace dependencies by running yarn at the root to populate node_modules for all packages in packages/ and external/
• Build the source using yarn build to trigger the yakumo build system, which compiles TypeScript via esbuild and tsc to dist/ directories
• Run tests with yarn test to execute the Vitest suite across the entire monorepo
• Scaffold applications using node packages/create/src/bin.ts to test the create-cordis CLI and stageYarnBin functionality

Frequently Asked Questions

Why does Cordis use Yarn 4 with the node-modules linker instead of Plug'n'Play?

Cordis explicitly sets nodeLinker: node-modules in .yarnrc.yml to maintain compatibility with tooling that expects standard node_modules resolution while still leveraging Yarn 4's improved workspace management and dependency deduplication. This configuration allows the monorepo to use standard Node.js module resolution for the yakumo build system and Vitest test runner.

What is the yakumo build system used for in Cordis?

Yakumo is a build orchestration tool used by Cordis to coordinate esbuild for fast bundling and the TypeScript compiler for type checking across all workspace packages. When you run yarn build, yakumo reads each package's tsconfig.json and outputs compiled artifacts to dist/ folders, ensuring consistent build outputs for the core runtime, loader, and HMR packages.

How do I run tests for a specific package only instead of the entire monorepo?

Navigate to the individual package directory and execute yarn test. For example, running cd packages/core && yarn test executes only the unit tests defined in the core package using the root Vitest configuration. This approach reduces feedback time when developing isolated features in packages/core or packages/hmr.

Can I use the create-cordis CLI without building the entire monorepo first?

No, you must run yarn build before invoking the CLI via node packages/create/src/bin.ts. The CLI source in packages/create/src/index.ts is written in TypeScript and requires compilation to JavaScript. Additionally, the CLI depends on the compiled versions of packages/core and other workspace dependencies to properly stage the Yarn binary and scaffold new projects.

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