client-only

library0.0.1jsnpmunverified

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.

web-framework

npm install client-only

package ↗homepage ↗

INSTALL

IMPORT

SIG · CLIENT-ONLY

client-only

web-frameworkjavascriptv0.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Side-effect import for client-only marking

✓ import 'client-only';

✗ import { someExport } from 'client-only';

This package is a marker and has no named or default exports. The import statement itself provides the necessary signal to bundlers/frameworks.

Demonstrates a simple React Client Component that explicitly imports `client-only` to ensure it only runs in client environments and uses browser-specific APIs.

import 'client-only'; import { useState, useEffect } from 'react'; export default function ClientSideCounter() { // This component will only run on the client, enforced by 'client-only' const [count, setCount] = useState(0); const [isBrowser, setIsBrowser] = useState(false); useEffect(() => { setIsBrowser(typeof window !== 'undefined'); // Example of browser-specific API usage if (isBrowser) { console.log('Running on browser. User agent:', window.navigator.userAgent); } }, [isBrowser]); return ( <div> {isBrowser ? ( <p>You clicked {count} times</p> ) : ( <p>Loading client component...</p> )} <button onClick={() => setCount(count + 1)}>Click me</button> {!isBrowser && <p>This component is client-only and will hydrate soon.</p>} </div> ); }

Debug

Known issues

gotchaThe `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.

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`.

affects: >=0.0.1

gotchaImporting `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.

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.

affects: >=0.0.1

gotchaWhile `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.

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`).

affects: >=0.0.1

gotchaThe `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.

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.

affects: >=0.0.1

Errors

Common errors & fixes

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.

A module that directly or transitively imports 'client-only' was imported into a React Server Component.

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.

ReferenceError: window is not defined

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.

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.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/client-only ↗

homepagehttps://reactjs.org/ ↗