{"id":15572,"library":"client-only","title":"Client-Side Module Marker","description":"The `client-only` package is a specialized marker module within the React Server Components (RSC) ecosystem, primarily used in frameworks like Next.js App Router. Its sole purpose is to indicate to the build system that a module and all its transitive dependencies are intended exclusively for client-side execution. It doesn't export any functions or values, acting purely as a side-effect import. When a module imports `client-only`, compatible bundlers and frameworks will enforce that this module is never included in a server bundle, providing build-time errors for misuse. This package, currently at version `0.0.1` and infrequently updated due to its static nature, complements `server-only` to clearly define server-client boundaries in a hybrid rendering environment. Its key differentiator is its explicit, declarative way of preventing accidental server-side imports of client-specific code, which helps avoid issues like 'window is not defined' errors during server rendering.","status":"active","version":"0.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","react"],"install":[{"cmd":"npm install client-only","lang":"bash","label":"npm"},{"cmd":"yarn add client-only","lang":"bash","label":"yarn"},{"cmd":"pnpm add client-only","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a marker and has no named or default exports. The import statement itself provides the necessary signal to bundlers/frameworks.","wrong":"import { someExport } from 'client-only';","symbol":"Side-effect import for client-only marking","correct":"import 'client-only';"}],"quickstart":{"code":"import 'client-only';\nimport { useState, useEffect } from 'react';\n\nexport default function ClientSideCounter() {\n  // This component will only run on the client, enforced by 'client-only'\n  const [count, setCount] = useState(0);\n  const [isBrowser, setIsBrowser] = useState(false);\n\n  useEffect(() => {\n    setIsBrowser(typeof window !== 'undefined');\n    // Example of browser-specific API usage\n    if (isBrowser) {\n      console.log('Running on browser. User agent:', window.navigator.userAgent);\n    }\n  }, [isBrowser]);\n\n  return (\n    <div>\n      {isBrowser ? (\n        <p>You clicked {count} times</p>\n      ) : (\n        <p>Loading client component...</p>\n      )}\n      <button onClick={() => setCount(count + 1)}>Click me</button>\n      {!isBrowser && <p>This component is client-only and will hydrate soon.</p>}\n    </div>\n  );\n}","lang":"typescript","description":"Demonstrates a simple React Client Component that explicitly imports `client-only` to ensure it only runs in client environments and uses browser-specific APIs."},"warnings":[{"fix":"Wrap browser-specific code in `useEffect` hooks or conditional checks (`if (typeof window !== 'undefined')`) within your client components, even if they import `client-only`.","message":"The `client-only` package is a compile-time marker, not a runtime guard. It enforces that the module is bundled only for the client. It does not automatically make server-incompatible code (e.g., direct `window` access) safe if the Client Component still undergoes a server pre-render (SSR) phase. You still need to safeguard browser-specific API calls within `useEffect` or check `typeof window !== 'undefined'` in Client Components to avoid errors during initial server rendering.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always add `'use client';` at the very top of your React component files that are intended to be Client Components. Use `import 'client-only';` for utility modules or other non-component files that must strictly only exist in the client bundle.","message":"Importing `client-only` into a module *does not* automatically turn it into a React Client Component. For React, the `'use client'` directive at the top of the file is the primary mechanism to mark a module as a Client Component. `client-only` provides an additional layer of explicit error checking for non-component client-only logic or to explicitly mark a module that *should* be part of the client bundle graph.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure that any dynamic or client-specific content within your Client Components is initialized consistently during SSR and client hydration, or is only rendered after the component mounts on the client (e.g., inside `useEffect`).","message":"While `client-only` helps prevent server-side bundling, it does not solve hydration mismatches if your client component renders different content on the server (during SSR) versus the client. Such mismatches can still lead to 'Hydration failed because the server rendered HTML didn't match the client' errors.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Consult your framework's documentation (e.g., Next.js, Remix) regarding its recommended approach for marking client-only modules. If the framework provides native equivalents, `client-only` might be redundant or serve as an additional explicit marker.","message":"The `client-only` package itself has no runtime effect and is merely a marker. Some frameworks, like Next.js App Router, have built-in mechanisms to detect client-only code and provide similar error messages. Installing `client-only` might be optional in such cases but can improve linting feedback and explicit intent.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the module importing 'client-only' is itself a Client Component (marked with 'use client';) or is only imported by other Client Components. If it's a utility, ensure it's only called from client-side code.","cause":"A module that directly or transitively imports 'client-only' was imported into a React Server Component.","error":"Error: You're importing a component that needs 'client-only'. It only works in a Client Component but you're trying to render it in a Server Component."},{"fix":"Place all code that interacts with browser-specific APIs (e.g., `window`, `localStorage`) inside a `useEffect` hook, or guard it with `if (typeof window !== 'undefined')` to ensure it only runs in a browser environment.","cause":"A Client Component (even one importing 'client-only') attempts to access a browser-specific global object like `window` or `document` during the initial server-side render phase, where these objects do not exist.","error":"ReferenceError: window is not defined"}],"ecosystem":"npm"}