# Configuration

To configure the behavior of `@lazarv/react-server`, you need to create a `react-server.config.*` or `+*.config.*` file in the root of your project. This file is used to configure the server and the build process. The file type could be `.js`, `.mjs`, `.ts`, `.mts` or `.json`.

You can use the `+*.config.*` file to extend the configuration of `@lazarv/react-server`. The `+*.config.*` file is merged with the `react-server.config.*` file.

The `+*.config.*` file is useful when you want to extend the configuration of the runtime. You can use as many `+*.config.*` files as you want. All the configuration files are merged together in the order they are loaded.

## Typed configuration

For **JavaScript and TypeScript** config files, wrap your config with `defineConfig` to get full IntelliSense — autocompletion, type checking, and inline descriptions with examples for every option:

```mjs filename="react-server.config.mjs"
import { defineConfig } from "@lazarv/react-server/config";

export default defineConfig({
  port: 3000,
  adapter: "vercel",
});
```

For **JSON** config files, add a `$schema` property to enable validation and autocomplete directly in your editor:

```json filename="react-server.config.json"
{
  "$schema": "https://react-server.dev/schema.json",
  "port": 3000,
  "adapter": "vercel"
}
```

The JSON Schema is also available from the package itself for offline use:

```json filename="react-server.config.json"
{
  "$schema": "node_modules/@lazarv/react-server/config/schema.json"
}
```

If you want to only add configuration to use when running the runtime in production mode, then use the `.production.config.*` extension. These configuration files only loaded in production mode.

In a similar way, you can create configuration files with the `.development.config.*` extension to use a different configuration for development mode.

To add configuration to the build process, you can create `.build.config.*` files and these configuration files will only be used during a production build.

Configuration files with the `.runtime.config.*` or `.server.config.*` extensions are not used during the build process.

The configuration object you need to export as default is an extension of the Vite config object. You can find the full list of options [here](https://vitejs.dev/config/).

## Vite configuration

To provide full control over the Vite configuration, you can use the `vite` option to configure the Vite server and the build process. The `vite` option is an object that extends the Vite config object or a function that returns a new Vite config object. As a function you can discover and mutate the default configuration for Vite.

You can also use a `vite.config.*` file to configure Vite as you would do in a Vite project. The `vite.config.*` file is merged with the `react-server.config.*` file.

Best practice is to use a `vite.config.*` file to configure Vite as you would do in a Vite project and use the `react-server.config.*` file to configure the runtime specific options.

## Additional configuration

The following options are specific to `@lazarv/react-server`.

#### Runtime

Add new entries to the runtime context. The runtime context is a singleton store and can be used to share state in your application.

```json filename="react-server.runtime.config.json"
{
  "runtime": {
    "myEntry": "myValue"
  }
}
```

The `runtime` option can also be a function that returns the runtime context object. This is useful when you want to mutate the runtime context.

```mjs filename="react-server.runtime.config.mjs"
export default {
  runtime: (runtime) => {
    return {
      ...runtime,
      myEntry: "myValue",
    };
  },
};
```

In your application you can retrieve the runtime context using the `getRuntime` function.

```mjs
import { getRuntime } from "@lazarv/react-server";

const runtime = getRuntime();
```

You can also directly access the runtime context entries by key using the `getRuntime` function.

```mjs
import { getRuntime } from "@lazarv/react-server";

const entry = getRuntime("myEntry");
```

#### Cookies

Provide cookies configuration, see available options [here](https://www.npmjs.com/package/cookie#options-1).

```mjs filename="react-server.config.mjs"
export default {
  cookies: {
    path: "/",
    maxAge: 60 * 60 * 24 * 30,
    secure: true,
    httpOnly: true,
    sameSite: "lax",
  },
};
```

#### Handlers

You can add `pre` and `post` handlers to the middleware stack. Asynchronous handler functions can be defined in an array for each of the `pre` and `post` options.

```mjs filename="react-server.config.mjs"
export default {
  handlers: {
    pre: [async () { ... }],
    post: [async () { ... }]
  }
}
```

The `handlers` option can also be a function that returns the handlers array. This is useful when you want to mutate the middlewares used.

```mjs filename="react-server.config.mjs"
export default {
  handlers: (handlers) => {
    return [...handlers, async () { ... }];
  }
}
```

Or the `handlers` option can be an array, where the array of handlers will be used as `post` handlers.

#### Public directory

The public directory is the directory where the static assets are served from. The default value is `public`.

#### Module preload

To disable the automatic module preloading of client components, you can use the `modulePreload` option. The `modulePreload` option can be a boolean value or a function that returns a boolean value. The function can also be an async function. When the `modulePreload` option evaluates to `false`, the modules for the client components will not be preloaded.

```json filename="react-server.config.json"
{
  "modulePreload": false
}
```

Using a function to disable the module preloading of client components:

```mjs filename="react-server.config.mjs"
export default {
  modulePreload: () => false,
};
```

As the whole application context is available in the function, you can use all helpers or hooks provided by `@lazarv/react-server` to determine whether to preload the client components.

```mjs filename="react-server.config.mjs"
import { usePathname } from "@lazarv/react-server";

export default {
  modulePreload: () => {
    const pathname = usePathname();
    return pathname !== "/";
  },
};
```

#### Error overlay

To disable the error overlay in development mode, you can use the `overlay` option. The `overlay` option can be a boolean value. When the `overlay` option is set to `false`, the error overlay will not be displayed.

```json filename="react-server.config.json"
{
  "overlay": false
}
```

#### Console forwarding

Console forwarding is a feature that allows you to forward the console output from the browser to the development server. This is useful for debugging purposes, as it allows you to see the console output from the browser in your terminal when running the development server.

Console forwarding is enabled by default in your application. To disable console forwarding, you can use the `console` option. The `console` option can be a boolean value. When the `console` option is set to `false`, the console output from the browser will not be forwarded to the development server.

```json filename="react-server.config.json"
{
  "console": false
}
```

#### Initial configuration via environment variable

You can provide initial configuration at runtime using the `REACT_SERVER_INITIAL_CONFIG` environment variable. This is a JSON string that is merged into the configuration before the prebuilt config file values.

This is useful when deploying to edge runtimes where the configuration needs to be provided at runtime rather than baked into the build, or when you need to override configuration without modifying the config file.

```sh
REACT_SERVER_INITIAL_CONFIG='{"scrollRestoration":true}' pnpm react-server start
```

The environment variable is parsed as JSON and merged with lower priority than the config file — config file values always take precedence.

#### Config validation

By default, `@lazarv/react-server` validates your configuration file on startup (development) and before building (production). If the configuration contains invalid or forbidden options, you will see a clear error message.

To disable config validation, use the `--no-validation` CLI flag:

```sh
pnpm react-server ./App.jsx --no-validation
pnpm react-server build --no-validation
```

This is useful as an escape hatch if validation incorrectly rejects a valid configuration, or when you intentionally need to bypass a forbidden option.