Registry / web-framework / server-only

server-only

JSON →
library0.0.1jsnpmunverified

The `server-only` package is a fundamental marker utility in the React Server Components (RSC) architecture. Its primary purpose is to enforce that a JavaScript module, and any code within it, can only be executed within a server-side environment. This is crucial for preventing sensitive server-side logic, such as database queries, direct file system access, or API keys, from accidentally being bundled and exposed to the client-side. The package achieves this through a clever use of conditional exports in its `package.json`. In a React Server Component build environment, it resolves to an empty file, effectively doing nothing. However, if imported into a client-side component, it resolves to a file that throws a build-time error, acting as a safeguard against data leaks, increased bundle sizes, and runtime failures. It is maintained by the React team, currently at version `0.0.1`, and its stability reflects its minimalistic and declarative role within the RSC paradigm. It differentiates itself by providing a strict, compile-time guarantee for server-only code separation, complementing newer runtime APIs like `experimental_taintObjectReference` which offer finer-grained control.

npm install server-only
INSTALL
IMPORT
SIG · SERVER-ONLY
S
server-only
web-frameworkjavascriptv0.0.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.

Side Effect Import
import 'server-only';
import { someExport } from 'server-only';
This package is used purely for its side effect (or lack thereof, depending on the environment) and has no named or default exports. It acts as a build-time directive.

Demonstrates marking a utility file as server-only and its safe usage within a React Server Component, illustrating how to prevent accidental client-side imports.

/* src/lib/server-utils.ts */ // This directive ensures that this entire file can only be imported in Server Components. import 'server-only'; import { promises as fs } from 'fs'; export async function getSecretData() { // This code will only run on the server. // Accessing process.env directly is safe here. const apiKey = process.env.DATABASE_API_KEY ?? 'default_api_key'; console.log('Fetching secret data on the server...'); // Simulate reading from a server-side file system const fileContent = await fs.readFile(process.cwd() + '/src/lib/server-config.txt', 'utf-8'); return { message: `Hello from the server! Key used: ${apiKey.substring(0, 5)}...`, config: fileContent }; } /* src/app/page.tsx (Server Component) */ // This is a Server Component, so it can safely import 'server-utils.ts' import { getSecretData } from '../lib/server-utils'; export default async function HomePage() { const data = await getSecretData(); return ( <div> <h1>Welcome to the Server Component App</h1> <p>{data.message}</p> <p>Server config snippet: {data.config.substring(0, 20)}...</p> {/* You cannot import 'use client' components here that directly use getSecretData */} </div> ); } // Example of how to prevent client-side usage, if you tried to import getSecretData in a 'use client' component: // /* src/components/ClientComponent.tsx */ // 'use client'; // import { getSecretData } from '../lib/server-utils'; // This line would cause a build error // export default function ClientComponent() { return <div>Client component</div>; }
Debug
Known issues
breakingAttempting to import a module marked with `server-only` into any client-side component or file will result in a build-time error. This is by design to prevent server-side code from leaking to the client.
fix
Ensure that any file importing `server-only` is exclusively part of your server-side component tree or server utilities. Refactor client components to not depend on these modules directly.
affects: >=0.0.1
gotchaThe `server-only` package itself contains very little executable code. Its functionality relies on conditional exports in its `package.json` that cause a build tool (like Next.js's bundler) to throw an error when imported in a client context.
fix
Understand that `server-only` is a build-time marker, not a runtime guard. It prevents client-side bundling, but its effectiveness depends on the framework's build process recognizing the `react-server` condition.
affects: >=0.0.1
gotchaWhile `server-only` marks an entire module as server-exclusive, it does not prevent passing server-only values (like a database client or API key) as props from a Server Component down to a Client Component. Such values must be serializable or explicitly tainted.
fix
For fine-grained control over values, consider using React's experimental `experimental_taintObjectReference` or `experimental_taintUniqueValue` APIs to prevent specific values from being serialized or used on the client. Always ensure only serializable data is passed to Client Components.
affects: >=0.0.1
Errors
Common errors & fixes
You're importing a component that needs "server-only". This only works in a Server Component environment.
A module containing `import 'server-only';` was imported into a file or component that is intended for client-side execution (e.g., a file with `'use client'` directive, or a module that's part of the client bundle).
fix
Review the import path and ensure the offending import is only used within React Server Components or server-side utility files. If the functionality is needed on the client, it must be rewritten using client-compatible APIs or passed as serializable data from a Server Component.
Upgrade
Version history
0.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
3 hits · last 30 days
node
2
Resources
server-only — npm install server-only · libregistry