CLI

Run React framework scripts and renoun utilities from a single command-line interface.

The renoun CLI keeps the background language tools in sync with your project while you work. It starts a persistent server that handles syntax highlighting, type checking, and grammar loading so your React framework can focus on rendering.

Framework commands

When you run a framework command through the CLI, renoun boots its background services before forwarding every flag and positional argument to the framework. This keeps the developer experience identical to your existing scripts while ensuring renoun stays connected to your content.

  • Next.js — renoun next dev (defaults to dev when no subcommand is supplied)
  • Vite — renoun vite dev
  • Waku — renoun waku dev

Update your package.json scripts to prepend renoun to the framework commands you already use:

{
  "scripts": {
    "dev": "renoun next dev",
    "build": "renoun next build"
  }
}

You can pass through additional flags with the standard -- separator. For example, the following command enables Vite’s production optimizations while renoun keeps the grammar cache in sync:

renoun vite build -- --mode production

App commands

In addition to running your own framework app, the CLI can run renoun apps that live in node_modules (like @renoun/blog or @renoun/docs) and let your project override files. This is called app mode (or “Apps as Templates”).

You can invoke app mode in two ways:

  • Auto-detected app : 
    renoun dev
    renoun finds the first installed dependency that:
    • declares renoun in any dependency block, and
    • installs exactly one supported framework (Next.js, Vite, or Waku),
    and treats that as the app to run.
  • Explicit app : 
    renoun @renoun/blog dev

Both forms go through the same app runtime:

  • renoun builds a runtime under .renoun/ ,
  • copies the app’s source files into it,
  • applies your local files as overrides on top,
  • and then launches the underlying framework inside that runtime.

Dependency resolution in app mode

The runtime directory includes the app’s node_modules (symlinked), so the template controls its primary dependency graph. When your overrides import packages that are only installed in your project, Node can still resolve them by walking up to your project’s node_modules.

To make this easier to reason about, renoun also merges your project’s dependency sections into the runtime package.json (without changing the install graph).

Overriding app files

When you run an app through the CLI, your project and the app package are merged into a single runtime view:

  • The app provides the base (routes, layouts, components, default content).
  • Your project overrides by path —any file or directory you create with the same relative path takes precedence over the app’s version.

For example, if the app ships posts/hello-world.mdx under its own app/ or pages/ tree, you can override it by adding posts/hello-world.mdx next to your package.json. At runtime, the framework only sees your version.

See how to run a renoun app for a deep dive into how app mode works and when to use it.

Pruning theme files

Use renoun theme to minimize VS Code theme JSON files. The command validates the input file, removes unused properties, and writes the optimized JSON back to the same path:

renoun theme path/to/theme.json

Use renoun validate to check for broken internal links in your MDX content or on a running site.

  • Static analysis (default) : Parses MDX to collect links and validates them against routes inferred from your MDX file structure. External links and dynamic JSX href values are skipped. Files and directories matched by your root .gitignore are ignored.
  • Runtime crawler (URL) : Follows links on a running site and checks responses.

Usage

Run static MDX analysis across the workspace:

renoun validate

Run static MDX analysis only for files under the provided directory:

renoun validate ./docs

Run live validation by crawling the provided URL:

renoun validate http://localhost:3000/

When broken links are found, the command reports the source MDX file and the normalized link path (for static), or the failing URL and HTTP status (for live).

Last updated