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

> Set up your Cordis development environment quickly. Clone the repo, install Yarn 4, and run a few commands to build the monorepo and its dependencies.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: getting-started
- Published: 2026-09-13

---

**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`](https://github.com/cordiverse/cordis/blob/main/.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:

```bash
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`](https://github.com/cordiverse/cordis/blob/main/.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`](https://github.com/cordiverse/cordis/blob/main/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:

```bash
npm i -g yarn@4

```

Then install all workspace dependencies:

```bash
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`](https://github.com/cordiverse/cordis/blob/main/package.json) defines a `build` script that triggers both the esbuild bundler and TypeScript compilation.

Execute the full build across all packages:

```bash
yarn build

```

Internally, `yakumo esbuild` reads each package-level [`tsconfig.json`](https://github.com/cordiverse/cordis/blob/main/tsconfig.json) (such as [`packages/core/tsconfig.json`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/vitest.config.ts) at the repository root. To execute all unit tests across the workspace:

```bash
yarn test

```

For alternative output formats, use the helper scripts defined in [`package.json`](https://github.com/cordiverse/cordis/blob/main/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:

```bash
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`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts), bootstraps new Cordis applications. After building the monorepo, invoke the CLI via:

```bash
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`](https://github.com/cordiverse/cordis/blob/main/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:

```bash
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`](https://github.com/cordiverse/cordis/blob/main/.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`](https://github.com/cordiverse/cordis/blob/main/.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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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.