Registry / devops / babel-plugin-transform-next-use-client

babel-plugin-transform-next-use-client

JSON →
library1.1.1jsnpmunverified

The `babel-plugin-transform-next-use-client` is a specialized Babel plugin designed to automatically inject the "use client" directive into React components within a Next.js application. It identifies components that utilize React client-only APIs, such as `useEffect` and `useState`, and programmatically adds the directive, ensuring these components are correctly designated for client-side rendering according to Next.js App Router conventions. This automation helps prevent common errors where client-specific code might accidentally be rendered on the server. The current stable version is 1.1.1. As a utility within the build toolchain, its release cadence is generally stable, with updates typically driven by significant changes in React or Next.js's component model. Its key differentiator is simplifying the management of client components, reducing manual boilerplate and ensuring proper separation of client and server code within the App Router paradigm. It also provides an option (`customClientImports`) to specify custom client-only hooks or modules for accurate detection.

npm install babel-plugin-transform-next-use-client
INSTALL
IMPORT
SIG · BABEL-PLUGIN-TRANS
B
babel-plugin-transform-next-use-client
devopsjavascriptv1.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Babel Plugin String Name
plugins: ['babel-plugin-transform-next-use-client']
import { transformNextUseClient } from 'babel-plugin-transform-next-use-client'
Babel plugins are configured as strings in `babel.config.js` or `.babelrc`, not imported directly into application code. Ensure it's listed within the `plugins` array.
Plugin with Options
plugins: [['babel-plugin-transform-next-use-client', { customClientImports: ['useMyClientHook'] }]]
plugins: ['babel-plugin-transform-next-use-client', { customClientImports: ['useMyClientHook'] }]
When passing options, the plugin name and its options object must be wrapped in an array, like `['plugin-name', { options }]`.

Demonstrates the basic setup of the plugin in a Babel configuration and an example React component that would be automatically marked as a 'use client' component due to its use of `useState` and `useEffect`.

{ // In your babel.config.js or .babelrc file "presets": [ // ... other presets like '@babel/preset-env', '@babel/preset-react', 'next/babel' ], "plugins": [ // ... other plugins 'babel-plugin-transform-next-use-client', // If you have custom client-only hooks or modules, specify them: // [ // 'babel-plugin-transform-next-use-client', // { // customClientImports: [ // 'useAuthClientStore', // Example: a custom hook that uses browser APIs // 'myClientSideUtility' // ] // } // ] ] } // Example React component that would trigger the plugin: // components/MyClientComponent.tsx // (No need for manual 'use client' here if plugin is active) import React, { useState, useEffect } from 'react'; interface MyClientComponentProps { initialCount?: number; } export default function MyClientComponent({ initialCount = 0 }: MyClientComponentProps) { const [count, setCount] = useState(initialCount); useEffect(() => { // This effect runs only on the client console.log('Component mounted on client'); document.title = `Count: ${count}`; return () => { console.log('Component unmounted from client'); }; }, [count]); return ( <div> <h1>Client Component Example</h1> <p>Current count: {count}</p> <button onClick={() => setCount(prev => prev + 1)}>Increment</button> <p>This component uses `useState` and `useEffect`, triggering the 'use client' directive automatically.</p> </div> ); }
Debug
Known issues
breakingThis plugin is specifically designed for Next.js applications utilizing the App Router and its client/server component architecture. It has no functional purpose or effect in Pages Router applications or non-Next.js React projects.
fix
Ensure your project is a Next.js App Router application. If not, this plugin is unnecessary and should be removed.
affects: >=1.0.0
gotchaThe plugin relies on detecting common React client-only APIs (e.g., `useState`, `useEffect`). If you abstract these APIs into custom hooks or utility functions within separate modules, the plugin might not automatically add the 'use client' directive to the consuming component. This can lead to server-side rendering errors if those custom modules are implicitly client-only.
fix
Use the `customClientImports` option in your Babel configuration to explicitly list the names of your custom client-only hooks or functions. For example: `[['babel-plugin-transform-next-use-client', { customClientImports: ['useMyHook'] }]]`.
affects: >=1.0.0
gotchaBabel plugin order matters. Ensure this plugin runs *before* other transformations that might alter the AST in a way that prevents the detection of client-only APIs, or that might themselves introduce directives.
fix
Review your `plugins` array in `babel.config.js`. Generally, this plugin should be placed early in the `plugins` array to ensure it processes the code before other major transformations occur.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: window is not defined
A component intended to be client-side was inadvertently rendered on the server due to the 'use client' directive being missing, potentially because the plugin failed to detect a custom client API.
fix
Verify your `babel.config.js` includes the plugin. If you're using custom client-only hooks or modules, ensure they are listed in the `customClientImports` option of the plugin configuration.
Error: Plugin 'babel-plugin-transform-next-use-client' not found.
The plugin is referenced in the Babel configuration but is not installed or incorrectly named.
fix
Run `npm install babel-plugin-transform-next-use-client` or `yarn add babel-plugin-transform-next-use-client`. Double-check the spelling in your `babel.config.js`.
Upgrade
Version history
1.1.1latest on npm
Audit
Dependencies
@babel/corerequiredRequired peer dependency for Babel plugin execution.
Agent activity
4 hits · last 30 days
node
4
Resources
babel-plugin-transform-next-use-client — npm install babel-plugin-transform-next-use-client · libregistry