> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Monorepo

This guide explains how to use Rstack CLI in a monorepo, including how it works with task orchestrators such as [Turborepo](https://turborepo.com/docs) and [Nx](https://nx.dev/docs/getting-started/intro).

It covers managing the Rstack CLI dependency, configuring lint, formatting, and staged-file tasks at the root, and defining separate configurations for web applications and libraries.

## Project structure

The recommended setup has two levels:

- The root manages the shared Rstack CLI version, lint and formatting rules, and staged-file tasks.
- Each application or library has its own [Rstack configuration](/guide/configuration.md) for build, test, or documentation configuration.

```text
.
├── package.json
├── rstack.config.ts
├── apps/
│   └── web/
│       ├── package.json
│       └── rstack.config.ts
└── packages/
    └── utils/
        ├── package.json
        └── rstack.config.ts
```

This structure keeps the Rstack CLI version in one place while keeping build and test configuration close to the project that uses it.

## Rstack CLI dependency management \{#rstack-dependency-management}

Declare the `rstack` package in the root `package.json` so projects use one Rstack CLI version by default. See [Quick start](/guide/quick-start.md#install-rstack) for installation instructions.

If a project needs a different Rstack CLI version from the root, declare that version as a dependency of the project.

Project-specific dependencies, such as Rsbuild plugins and testing libraries, should be declared in the projects that use them.

## Root configuration

Use [`define.lint()`](/guide/configuration.md#define-lint), [`define.fmt()`](/guide/configuration.md#define-fmt), and [`define.staged()`](/guide/configuration.md#define-staged) in the root `rstack.config.ts` for checks and formatting that apply to the entire repository:

```ts title="rstack.config.ts"
import { define } from 'rstack';

define.lint(({ js, ts }) => [
  js.configs.recommended,
  ts.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: ['./apps/*/tsconfig.json', './packages/*/tsconfig.json'],
      },
    },
  },
]);

define.fmt({
  singleQuote: true,
  ignorePatterns: ['**/dist/**'],
});

define.staged({
  '*.{js,jsx,ts,tsx,mjs,cjs}': ['rs lint', 'rs fmt'],
  '*.{json,md,mdx,css,html,yml,yaml}': 'rs fmt',
});
```

`parserOptions.project` lists the `tsconfig.json` of each project for type-aware presets and `rs check --type-check`. See [Typed linting](/guide/cli/lint.md#typed-linting).

Expose these tasks through scripts in the root `package.json`:

```json title="package.json"
{
  "private": true,
  "scripts": {
    "check": "rs check --type-check",
    "format": "rs fmt",
    "lint": "rs lint",
    "staged": "rs staged"
  }
}
```

Unless the root is itself a buildable project, you do not need to add application or library build configuration to the root config.

### Project-specific lint rules

If some projects need different lint rules, use [`files`](https://rslint.rs/config/#files) patterns to match the relevant files. These paths are resolved from the repository root:

```ts title="rstack.config.ts"
import { define } from 'rstack';

define.lint(({ js, ts }) => [
  js.configs.recommended,
  ts.configs.recommendedTypeChecked,
  {
    files: ['apps/web/**/*.{ts,tsx}'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
]);
```

## Project configuration

For each project that uses [Rstack CLI commands](/guide/quick-start.md#cli-commands), create a [`rstack.config.ts`](/guide/configuration.md#configuration-file) and register only the configuration that project needs.

Rstack CLI loads the configuration from the current working directory. It does not merge a project's configuration with the root configuration.

### Web application

A web application usually needs application build configuration and optional test configuration:

```ts title="apps/web/rstack.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';
import { define } from 'rstack';

define.app({
  plugins: [pluginReact()],
});

define.test({
  globals: true,
});
```

Add scripts to the application's `package.json`, for example:

```json title="apps/web/package.json"
{
  "name": "@example/web",
  "scripts": {
    "dev": "rs dev",
    "build": "rs build",
    "preview": "rs preview",
    "test": "rs test"
  }
}
```

### Library project

A library can define its build, test, and documentation configuration in one file:

```ts title="packages/utils/rstack.config.ts"
import { define } from 'rstack';

define.lib({
  dts: true,
  format: 'esm',
});

define.test({
  testEnvironment: 'node',
});

// Configure this only when the library needs a documentation site.
define.doc({
  root: 'docs',
  title: 'Utils',
});
```

Add scripts to the library's `package.json`, for example:

```json title="packages/utils/package.json"
{
  "name": "@example/utils",
  "scripts": {
    "build": "rs lib",
    "dev": "rs lib -w",
    "test": "rs test",
    "doc": "rs doc"
  }
}
```