{"id":12009,"library":"server-only","title":"Server-Only Module Enforcer for React","description":"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.","status":"active","version":"0.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","react"],"install":[{"cmd":"npm install server-only","lang":"bash","label":"npm"},{"cmd":"yarn add server-only","lang":"bash","label":"yarn"},{"cmd":"pnpm add server-only","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { someExport } from 'server-only';","symbol":"Side Effect Import","correct":"import 'server-only';"}],"quickstart":{"code":"/* src/lib/server-utils.ts */\n// This directive ensures that this entire file can only be imported in Server Components.\nimport 'server-only';\n\nimport { promises as fs } from 'fs';\n\nexport async function getSecretData() {\n  // This code will only run on the server.\n  // Accessing process.env directly is safe here.\n  const apiKey = process.env.DATABASE_API_KEY ?? 'default_api_key';\n  console.log('Fetching secret data on the server...');\n\n  // Simulate reading from a server-side file system\n  const fileContent = await fs.readFile(process.cwd() + '/src/lib/server-config.txt', 'utf-8');\n\n  return {\n    message: `Hello from the server! Key used: ${apiKey.substring(0, 5)}...`,\n    config: fileContent\n  };\n}\n\n/* src/app/page.tsx (Server Component) */\n// This is a Server Component, so it can safely import 'server-utils.ts'\nimport { getSecretData } from '../lib/server-utils';\n\nexport default async function HomePage() {\n  const data = await getSecretData();\n  \n  return (\n    <div>\n      <h1>Welcome to the Server Component App</h1>\n      <p>{data.message}</p>\n      <p>Server config snippet: {data.config.substring(0, 20)}...</p>\n      {/* You cannot import 'use client' components here that directly use getSecretData */}\n    </div>\n  );\n}\n\n// Example of how to prevent client-side usage, if you tried to import getSecretData in a 'use client' component:\n// /* src/components/ClientComponent.tsx */\n// 'use client';\n// import { getSecretData } from '../lib/server-utils'; // This line would cause a build error\n// export default function ClientComponent() { return <div>Client component</div>; }","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Attempting 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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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).","error":"You're importing a component that needs \"server-only\". This only works in a Server Component environment."}],"ecosystem":"npm"}