Server-Only Module Enforcer for React

Common errors

• You're importing a component that needs "server-only". This only works in a Server Component environment.

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

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install server-only npm
• yarn add server-only yarn
• pnpm add server-only pnpm

Imports

• Side Effect Import
  wrong:

  import { someExport } from 'server-only';

  correct:

  import '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.

Quickstart

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>; }