Rstack CLI Best Practices

Rstack CLI is the rstack package, exposed through the rs binaries. It provides one CLI, one config file, and a consistent workflow for the Rstack JavaScript toolchain.

It covers web app, library, docs, test, lint, Git hook, and staged-file workflows.

Commands

Use rs -h for top-level help, and rs <command> -h for command help where supported.

Key behavior:

• Unless define.test already sets extends, rs test extends define.app through @rstest/adapter-rsbuild or falls back to define.lib through @rstest/adapter-rslib. The app config takes precedence when both are defined.
• rs doc requires the optional @rspress/core dependency.

rstack.config.ts

Rstack CLI loads rstack.config.{ts,js,mts,mjs} by default.

Register config with define.*:

import { define } from 'rstack';

define.app({
  // Rsbuild config for `rs dev`, `rs build`, and `rs preview`
});

define.test({
  // Rstest config for `rs test`
});

• define.app(config): Rsbuild config for rs dev, rs build, and rs preview. Docs: https://rsbuild.rs/config/
• define.lib(config): Rslib config for rs lib; Docs: https://rslib.rs/config/
• define.doc(config): Rspress config for rs doc; Docs: https://rspress.rs/api/config/config-basic
• define.test(config): Rstest config for rs test; Docs: https://rstest.rs/config/
• define.lint(config): Rslint config for rs lint; Docs: https://rslint.rs/config/
• define.staged(config): lint-staged config for rs staged; accepts Record<string, string | string[]>.

Lazy Configuration

Prefer async functions with dynamic imports for dependencies. Avoid top-level sync imports of heavy dependencies in rstack.config.ts.

import { define } from 'rstack';

define.app(async () => {
  const { pluginReact } = await import('@rsbuild/plugin-react');
  return {
    plugins: [pluginReact()],
  };
});

Import Paths

Prefer Rstack-exported paths:

Git Hooks

Use rs setup for project-local Git hooks, commonly with rs staged in a pre-commit hook.