rollup-plugin-preserve-use-client

3.0.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin to preserve the 'use client' directive in React 18 components during bundling, ensuring proper separation between server and client components. Current stable version is 3.0.1, released under MIT, with ESM and CJS support and TypeScript type definitions. Unlike alternatives like rollup-plugin-preserve-directives, this plugin does not require 'preserveModules: true', avoiding conflicts with CSS module imports. The plugin uses Rollup's moduleParsed hook (v3.0.0+) and targets Rollup ^4.0.0 as a peer dependency. It solves a specific pain point for library authors distributing npm packages with both server and client components.

Common errors

error Error: The named export 'preserveUseClientDirective' is not provided by the module 'rollup-plugin-preserve-use-client' ↓

cause Attempted to import named export but plugin uses default export only.

fix

Use default import: import preserveUseClientDirective from 'rollup-plugin-preserve-use-client'

error TypeError: preserveUseClientDirective is not a function ↓

cause Possible incorrect import or missing plugin invocation (called as property instead of function).

fix

Ensure you call the imported default as a function: preserveUseClientDirective()

error Error: Cannot find module 'rollup-plugin-preserve-use-client' ↓

cause Package not installed or incorrect path.

fix

Run: npm install rollup-plugin-preserve-use-client --save-dev

error RollupError: This plugin requires Rollup version ^4.0.0 ↓

cause Incompatible Rollup version installed.

fix

Update Rollup to v4.x: npm install rollup@^4.0.0

Warnings

breaking v3.0.0 changed hook from 'transform' to 'moduleParsed' for detecting 'use client' directives. Custom configuration relying on plugin-specific behavior may break. ↓

fix Update to v3.0.0+ and verify no reliance on previous transform-based internals.

deprecated v2.0.0 introduced ESM and CJS support. Older v1.x only supported CommonJS and may be incompatible with modern Rollup setups. ↓

fix Upgrade to v2.0.0 or later. If using ES modules, ensure import syntax is correct.

gotcha Plugins like rollup-plugin-preserve-directives may conflict if used together. This plugin only preserves 'use client', not other directives like 'use strict'. ↓

fix Use only one directive-preserving plugin, or ensure they do not interfere.

gotcha The plugin only preserves directives in modules identified with 'use client' at the top of the file. Dynamically inserted or injected directives are not handled. ↓

fix Ensure 'use client' is a literal string at the top of each client component module.

gotcha If using Vite's environment variables or custom transformations that alter directive placement, the plugin may not detect the directive correctly. ↓

fix Place 'use client' as the first statement in the file, before any imports or other code.

Install

npm install rollup-plugin-preserve-use-client

yarn add rollup-plugin-preserve-use-client

pnpm add rollup-plugin-preserve-use-client

Imports

default

wrong

import { preserveUseClientDirective } from 'rollup-plugin-preserve-use-client'

correct

import preserveUseClientDirective from 'rollup-plugin-preserve-use-client'

Default export only; named import causes undefined error.

default

wrong

const { preserveUseClientDirective } = require('rollup-plugin-preserve-use-client')

correct

const preserveUseClientDirective = require('rollup-plugin-preserve-use-client')

CommonJS: use default require, not destructured named import.

PreserveUseClientOptions

wrong

import { PreserveUseClientOptions } from 'rollup-plugin-preserve-use-client'

correct

import type { PreserveUseClientOptions } from 'rollup-plugin-preserve-use-client'

Type import for TypeScript; the type is not a runtime value, so regular import at runtime may cause error.

Quickstart

Basic Rollup configuration using ESM imports. Adds the plugin to preserve 'use client' directives in bundled output.

import preserveUseClientDirective from 'rollup-plugin-preserve-use-client';
import { defineConfig } from 'rollup';

export default defineConfig({
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm',
  },
  plugins: [
    preserveUseClientDirective(),
  ],
});