# CLI

The `react-server` CLI is the main tool for developing and deploying your `@lazarv/react-server` applications. It provides a set of commands to help you build, run, and deploy your app.

To check out the available commands, run:

```sh
pnpm react-server --help
```

## Commands

You need to always define the entrypoint of your app as the first argument of the `react-server` command. Only exception is when you use the file-system based router as it will define the entrypoint for you.

- **[root]**: start development server for your app
- **build [root]**: build your app for production
- **start**: start your app in production

The `[root]` of your app has to export default a React Server Component. This is the entrypoint of your app and this will be rendered on the server side for every request.

You can also use a hash fragment in the entrypoint to specify a specific export. For example, if you have an entrypoint at `./index.jsx` and you want to use the `App` export, you can use `./index.jsx#App`.

## Development server options

If your entrypoint is at `./App.jsx`, you can start the development server with:

```sh
pnpm react-server ./App.jsx
```

To start the development server, you can use the following options:

### --host

The host to listen on. Default is `localhost`.

### --port

The port to listen on. Default is `3000`.

### --https

Use HTTPS protocol. Default is `false`.

When you want to use HTTPS for your development server. You need to specify your HTTPS configuration in your `react-server.config.mjs` or `vite.config.mjs` file. See details in the Vite documentation at [server.https](https://vitejs.dev/config/server-options.html#server-https).

### --cors

Enable CORS. Default is `false`.

This is useful when you want to allow cross-origin requests. If you need more detailed CORS configuration, you can define the CORS configuration in your `react-server.config.mjs` or `vite.config.mjs` file. See details in the Vite documentation at [server.cors](https://vitejs.dev/config/server-options.html#server-cors).

### --origin

Specify the origin part of the URL to a constant value. Same as using the `ORIGIN` environment variable.

### --trust-proxy

Trust `X-Forwarded-*` headers.

### --open

Open browser on server start. Default is `false`. Opens your app in the default browser.

### --force

Force optimize deps. Default is `false`. This is equal to `vite --force`. It will force the optimization of dependencies and clears the Vite cache.

### --watch

Watch for config changes. Default is `true`. To disable watching for config changes, use `--no-watch`.

### --clear-screen

Clear screen on server start. Default is `false`. If you want to start with a clean terminal screen.

### --devtools

Enable the built-in react-server DevTools. Default is `false`.

When enabled, a DevTools panel is injected into your application during development. It provides real-time inspection of your app's internals including RSC payload, cache entries, routes, outlets, remote components, live components, workers, and server logs.

You can also enable DevTools via your `react-server.config.mjs`:

```js
export default {
  devtools: true,
};
```

### --no-color

Disable color output. Default is `false`. This is useful for CI/CD environments.

### --no-validation

Skip configuration validation. Default is `false`.

When set, the development server will not validate your `react-server.config.*` file on startup. This is useful as an escape hatch if validation incorrectly rejects a valid configuration, or when you intentionally need to use an option that is normally forbidden.

### --eval

Evaluate the server entrypoint from the argument, like `node -e`. Pass `--eval` without a value to read the entrypoint from _stdin_ instead. Stdin is **never** auto-consumed — it is only read when `--eval` is explicitly passed. This type of entrypoint becomes a virtualized entrypoint and is not written to the file system.

```sh
# Inline code
pnpm exec react-server --eval "export default () => <h1>Hello</h1>;"

# From stdin (note the bare --eval, with no value)
echo 'export default () => <h1>Hello from stdin</h1>;' | pnpm exec react-server --eval

# From a file via shell redirect
pnpm exec react-server --eval < ./entry.jsx
```

### --version

Display version number. Output will also include your machine's architecture and node.js version.

### --outDir

Output directory for the build. Default is `.react-server`.

### --name

Name of the server. Default is `react-server`. Used for logging.

## Build options

### --minify

Minify your build. Default is `true`.

You don't need to minify your app if you only use React Server Components and you are not using any client components, like in the [Todo](https://github.com/lazarv/react-server/tree/main/examples/todo) example. If you want to disable minification of client component code, use `--no-minify`.

### --sourcemap

Generate source maps for production builds. Default is `false`.

Accepted values: `true`, `inline`, `hidden`, `server`, or `server-inline`.

| Value | Description |
|-------|-------------|
| `true` | Generates `.map` files for both server and client bundles |
| `inline` | Embeds source maps inline in the output files |
| `hidden` | Generates `.map` files without `sourceMappingURL` comments |
| `server` | Generates `.map` files **only for server bundles** |
| `server-inline` | Embeds source maps inline **only in server bundles** |

When source maps are enabled, server-side error stack traces in production are automatically rewritten to show original source file locations using `source-map-support`. If `NODE_OPTIONS='--enable-source-maps'` is already set, the `source-map-support` package is skipped to avoid conflicts.

Use `--sourcemap=server` or `--sourcemap=server-inline` to keep your source code private from browser devtools while still getting mapped stack traces on the server.

You can also configure this in `react-server.config.mjs`:

```js
export default {
  sourcemap: true, // or "inline", "hidden", "server", "server-inline"
};
```

> **Note:** When deploying with adapters, source maps are automatically handled per platform:
> - **Vercel**: `.map` files are included in the function bundle and `NODE_OPTIONS='--enable-source-maps'` is set.
> - **Cloudflare**: `upload_source_maps` is enabled in `wrangler.toml` for dashboard and `wrangler tail` support.
> - **Netlify**: `.map` files are deployed alongside functions. Deno-based edge functions pick them up natively.
>
> On edge runtimes, the `source-map-support` package is skipped since these platforms handle source maps at the infrastructure level.

See more details in the Vite documentation at [build.sourcemap](https://vitejs.dev/config/build-options.html#build-sourcemap).

### --no-color

Disable color output. Default is `false`. This is useful for CI/CD environments.

### --no-validation

Skip configuration validation. Default is `false`.

When set, the build process will not validate your `react-server.config.*` file before building. This is useful as an escape hatch if validation incorrectly rejects a valid configuration, or when you intentionally need to use an option that is normally forbidden.

### --export

Static export. Default is `false`.

You can export your app as static HTML pages. You can define the routes to export in your `react-server.config.mjs` file. See more details at [Static generation](/router/static).

### --export-concurrency

Number of parallel processes used to render static export paths. Default is between `2` and `4`, scaled to the number of available CPU cores.

Pass `1` to run the export in a single in-process pipeline — paths are rendered one at a time in the main process, with no fork or IPC overhead. This is the lowest-overhead mode and is a good fit for small exports or for debugging.

Pass `>1` to fork that many render-worker child processes. Each child runs its own RSC main thread plus an SSR worker thread and renders one path at a time. The coordinator dispatches paths to free children over IPC; output bytes never cross the IPC boundary — every artifact (HTML, `.gz` / `.br` sidecars, `.postponed.json`, `.prerender-cache.json`) is written to disk inside the child. Both modes produce the same artifact set.

This is the right knob to reach for when exporting tens of thousands of pages or when individual pages do heavy server-side work (Shiki highlighting, large MDX trees, costly server components). On smaller exports the per-fork startup cost dominates and a value of `1` may be faster overall.

```sh
pnpm react-server build --export --export-concurrency 8
```

You can also set this in your `react-server.config.mjs` as `exportConcurrency`.

### --compression

Enable compression. Default is `false`.

You can enable compression if you want to compress your static build. Compression is not enabled by default for static builds. Gzip and Brotli compression is used when compression is enabled. The production mode server serves these compressed files by default when the compressed static files are present.

### --deploy

Deploy using adapter. Default is `false`.

If you use an adapter in your `react-server.config.mjs` file, the adapter will pre-build your app for deployment and when you use this argument, the adapter will also deploy your app at the end of the build process.

You can also pass a JSON string to `--deploy` to provide adapter-specific options at deploy time. These options are merged with the `adapterOptions` from your configuration file, with the CLI values taking precedence.

```sh
pnpm react-server build --deploy '{"project": "my-project"}'
```

This is useful when you want to override or provide adapter options without modifying your configuration file, for example specifying a deployment target project or environment.

### --eval

Evaluate the server entrypoint from the argument, like `node -e`. Pass `--eval` without a value to read the entrypoint from _stdin_ instead. Stdin is **never** auto-consumed — it is only read when `--eval` is explicitly passed. This type of entrypoint becomes a virtualized entrypoint and is not written to the file system.

```sh
# Inline code
pnpm exec react-server build --eval "export default () => <h1>Hello</h1>;"

# From stdin
echo 'export default () => <h1>Hi</h1>;' | pnpm exec react-server build --eval

# From a file via shell redirect
pnpm exec react-server build --eval < ./entry.jsx
```

### --outDir

Output directory for the build. Default is `.react-server`.

### --mode

Set the mode for the build. Default is `production`.

### --edge

Enable edge build mode. Default is `false`. Builds your app for edge runtime environments.

### --silent

Suppress build output. Default is `false`.

This option suppresses all build output from the bundler. Useful for CI/CD environments or when running builds programmatically where you don't want verbose output.

### --verbose

Verbose build output. Default is `false`. Enables detailed build logs from the bundler.

## Start options

**host**, **port**, **https** and **cors** are the same as in the development server options.

### --origin

Specify the origin part of the URL to a constant value. Same as using the `ORIGIN` environment variable.

### --trust-proxy

Trust `X-Forwarded-*` headers.

### --build

Runs the build command before starting the server using the provided entrypoint.

### --outDir

Output directory for the build. Default is `.react-server`. You need to specify this option if you used a different output directory in the build command than the default.