{"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,"search_vec":"'0.0.1':156 'access':67 'accident':72 'achiev':84 'act':133 'api':69,190 'architectur':24 'build':101,130 'build-tim':129 'bundl':74,141 'clever':88 'client':80,118 'client-sid':79,117 'code':37,185 'compil':178 'compile-tim':177 'complement':187 'compon':22,100,120 'condit':91 'control':199 'crucial':52 'current':153 'data':138 'databas':62 'declar':164 'differenti':171 'direct':64 'effect':109 'empti':107 'enforc':5,30 'environ':49,102 'error':132 'execut':43 'experiment':192 'export':92 'expos':76 'failur':145 'file':65,108,125 'finer':197 'finer-grain':196 'fundament':15 'grain':198 'guarante':180 'howev':112 'import':114 'increas':140 'javascript':33,200 'key':70 'leak':139 'like':191 'logic':59 'maintain':148 'marker':16 'minimalist':162 'modul':4,34 'newer':188 'noth':111 'offer':195 'packag':12,83 'package.json':95 'paradigm':169 'prevent':54 'primari':26 'provid':174 'purpos':27 'queri':63 'react':7,20,98,151,201 'reflect':160 'resolv':104,122 'role':165 'rsc':23,168 'runtim':144,189 'safeguard':136 'sensit':55 'separ':186 'server':2,10,21,47,57,99,183 'server-on':1,9,182 'server-sid':46,56 'side':48,58,81,119 'size':142 'stabil':159 'strict':176 'system':66 'taintobjectrefer':193 'team':152 'throw':127 'time':131,179 'use':89 'util':17 'version':155 'within':38,44,166","created_at":"2026-04-19T13:40:57.431718+00:00","updated_at":"2026-04-19T13:40:57.431718+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://reactjs.org/","github":null,"docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/server-only","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}