{"id":15535,"library":"babel-plugin-transform-next-use-client","title":"Babel Plugin for Next.js 'use client' Directive","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/kyletsang/babel-plugin-transform-next-use-client","tags":["javascript","babel","babel-plugin","react","next","client-component","use-client"],"install":[{"cmd":"npm install babel-plugin-transform-next-use-client","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-transform-next-use-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-transform-next-use-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Babel plugin execution.","package":"@babel/core","optional":false}],"imports":[{"note":"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.","wrong":"import { transformNextUseClient } from 'babel-plugin-transform-next-use-client'","symbol":"Babel Plugin String Name","correct":"plugins: ['babel-plugin-transform-next-use-client']"},{"note":"When passing options, the plugin name and its options object must be wrapped in an array, like `['plugin-name', { options }]`.","wrong":"plugins: ['babel-plugin-transform-next-use-client', { customClientImports: ['useMyClientHook'] }]","symbol":"Plugin with Options","correct":"plugins: [['babel-plugin-transform-next-use-client', { customClientImports: ['useMyClientHook'] }]]"}],"quickstart":{"code":"{\n  // In your babel.config.js or .babelrc file\n  \"presets\": [\n    // ... other presets like '@babel/preset-env', '@babel/preset-react', 'next/babel'\n  ],\n  \"plugins\": [\n    // ... other plugins\n    'babel-plugin-transform-next-use-client',\n    // If you have custom client-only hooks or modules, specify them:\n    // [\n    //   'babel-plugin-transform-next-use-client',\n    //   {\n    //     customClientImports: [\n    //       'useAuthClientStore', // Example: a custom hook that uses browser APIs\n    //       'myClientSideUtility'\n    //     ]\n    //   }\n    // ]\n  ]\n}\n\n// Example React component that would trigger the plugin:\n// components/MyClientComponent.tsx\n// (No need for manual 'use client' here if plugin is active)\n\nimport React, { useState, useEffect } from 'react';\n\ninterface MyClientComponentProps {\n  initialCount?: number;\n}\n\nexport default function MyClientComponent({ initialCount = 0 }: MyClientComponentProps) {\n  const [count, setCount] = useState(initialCount);\n\n  useEffect(() => {\n    // This effect runs only on the client\n    console.log('Component mounted on client');\n    document.title = `Count: ${count}`;\n    return () => {\n      console.log('Component unmounted from client');\n    };\n  }, [count]);\n\n  return (\n    <div>\n      <h1>Client Component Example</h1>\n      <p>Current count: {count}</p>\n      <button onClick={() => setCount(prev => prev + 1)}>Increment</button>\n      <p>This component uses `useState` and `useEffect`, triggering the 'use client' directive automatically.</p>\n    </div>\n  );\n}\n","lang":"javascript","description":"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`."},"warnings":[{"fix":"Ensure your project is a Next.js App Router application. If not, this plugin is unnecessary and should be removed.","message":"This 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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'] }]]`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Babel 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"ReferenceError: window is not defined"},{"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`.","cause":"The plugin is referenced in the Babel configuration but is not installed or incorrectly named.","error":"Error: Plugin 'babel-plugin-transform-next-use-client' not found."}],"ecosystem":"npm"}