server-cli-only

Common errors

• Module not found: Can't resolve 'server-cli-only'

  cause The `server-cli-only` package is not installed in your project, or your build tool cannot locate it in `node_modules`.
  fix Run `npm install server-cli-only` or `yarn add server-cli-only` to add the package to your project dependencies.

• error: [filepath] cannot be imported into the 'browser' runtime.

  cause A module that contains `import "server-cli-only"` is being included in a bundle targeted for the browser runtime (e.g., a React Client Component). This is an intentional build-time error from the package.
  fix Refactor your application to ensure the offending module is only imported by server-side components, API routes, or CLI scripts. For React, ensure the component importing it is a Server Component or that the import path is conditionally excluded from client bundles.

• TypeError: Cannot read properties of undefined (reading 'someServerSideMethod')

  cause This error occurs if a server-only function or object, despite the `server-cli-only` declaration, was accidentally included in a client-side bundle and is being called. This indicates a failure in the conditional exports mechanism.
  fix This is a critical leakage. Immediately review your `package.json#exports` and build configuration (e.g., Next.js `next.config.js`) to ensure the `server-cli-only` restriction is correctly enforced and not being bypassed.

Warnings

• breaking Attempting to import a module marked with `import "server-cli-only"` into a browser-targeted client component or an unknown runtime *will* intentionally cause a build-time error. This is the package's core function and expected behavior.
  Fix: Ensure the module is only imported by React Server Components, Node.js, Bun, Deno, or supported edge runtimes. Verify your bundler's conditional export configuration to correctly identify runtimes.
• gotcha This package relies on Node.js conditional exports and bundler support (like in Next.js) to enforce its restrictions. Misconfiguration of your build toolchain or `package.json`'s `exports` map might bypass the `server-cli-only` check, potentially leading to sensitive server-side code leaking into the client bundle without an explicit build error.
  Fix: Thoroughly review your project's `package.json` for correct `exports` field definitions. Ensure your build tools are correctly interpreting runtime conditions. Always test explicitly for client-side leaks in sensitive modules.
• gotcha This package differs from `server-only`. While `server-only` strictly limits modules to the `react-server` runtime, `server-cli-only` allows a broader set of server and CLI runtimes (Node, Bun, Deno, various edge functions). Choose the correct package based on your specific runtime restrictions.
  Fix: Understand the allowed runtimes for `server-cli-only` (`react-server`, `node`, `bun`, `deno`, `edge-light`, `netlify`, `workerd`). If you *only* want `react-server` exclusivity, use `server-only` instead.

Install

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

Imports

• (side-effect import)
  wrong:

  import { someValue } from "server-cli-only";

  correct:

  import "server-cli-only";

  This package is imported purely for its side effect, which triggers build-time checks based on conditional exports. It does not export any values.
• (side-effect import with CommonJS)
  wrong:

  const serverCliOnly = require("server-cli-only");

  correct:

  if (typeof require !== 'undefined') { require("server-cli-only"); }

  For CommonJS environments, ensure it's a side-effect `require` call. Attempting to assign its (non-existent) exports will result in `undefined`.
• (type import - N/A)
  wrong:

  import type { ServerCliOnly } from "server-cli-only";

  correct:

  // No types are exported or intended to be used directly from this package.

  This package provides runtime restrictions, not types for direct consumption. Its type declarations simply point to an empty module.

Quickstart

Demonstrates how to use `server-cli-only` to restrict a module containing sensitive configuration to server/CLI environments, preventing client-side leakage.

import "server-cli-only"; // This line prevents the module from being bundled into browser code

interface SensitiveConfig {
  apiKey: string;
  databaseUrl: string;
}

export function getSensitiveConfig(): SensitiveConfig {
  // In a real application, fetch from environment variables or a secure store
  return {
    apiKey: process.env.MY_API_KEY ?? 'sk_test_123',
    databaseUrl: process.env.DATABASE_URL ?? 'mongodb://localhost:27017/mydb',
  };
}

// Example usage for a server or CLI script:
// If this file is executed directly via Node.js, Bun, or Deno:
// e.g., `ts-node src/server-logic.ts`
if (typeof process !== 'undefined' && process.argv[1] === require.main?.filename) {
  console.log("Executing server-side logic directly via CLI.");
  const config = getSensitiveConfig();
  console.log("Retrieved API Key (first 5 chars):", config.apiKey.substring(0, 5) + '...');
  console.log("Database URL:", config.databaseUrl);
}
// If imported into a React Server Component, it would execute there.
// If imported into a React Client Component, it would throw a build error.