{"id":12004,"library":"server-cli-only","title":"server-cli-only","description":"The `server-cli-only` package, currently at version 0.3.2, acts as a build-time failsafe to prevent specific modules from being bundled into client-side (browser) code. Its primary function is to restrict imports of designated modules exclusively to server-side environments such as React Server Components, Node.js, Bun, Deno, and various edge runtimes (Vercel, Netlify, Cloudflare). Unlike the `server-only` package, which strictly targets the 'react-server' runtime, `server-cli-only` expands its allowed runtimes to encompass a broader range of server and CLI execution environments, including those defined by WinterCG specifications. This ensures sensitive code or data remains server-side, throwing build-time errors if inadvertently imported into a browser context or an unknown runtime, thereby preventing potential security vulnerabilities and unexpected client behavior. The package maintains a stable, low-frequency release cadence as it primarily focuses on a core, foundational restriction mechanism.","status":"active","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/destacks/core-ts/tree/main/packages/server-cli-only","tags":["javascript","nextjs","next","react","server-only","cli-only","cli","server"],"install":[{"cmd":"npm install server-cli-only","lang":"bash","label":"npm"},{"cmd":"yarn add server-cli-only","lang":"bash","label":"yarn"},{"cmd":"pnpm add server-cli-only","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is imported purely for its side effect, which triggers build-time checks based on conditional exports. It does not export any values.","wrong":"import { someValue } from \"server-cli-only\";","symbol":"(side-effect import)","correct":"import \"server-cli-only\";"},{"note":"For CommonJS environments, ensure it's a side-effect `require` call. Attempting to assign its (non-existent) exports will result in `undefined`.","wrong":"const serverCliOnly = require(\"server-cli-only\");","symbol":"(side-effect import with CommonJS)","correct":"if (typeof require !== 'undefined') { require(\"server-cli-only\"); }"},{"note":"This package provides runtime restrictions, not types for direct consumption. Its type declarations simply point to an empty module.","wrong":"import type { ServerCliOnly } from \"server-cli-only\";","symbol":"(type import - N/A)","correct":"// No types are exported or intended to be used directly from this package."}],"quickstart":{"code":"import \"server-cli-only\"; // This line prevents the module from being bundled into browser code\n\ninterface SensitiveConfig {\n  apiKey: string;\n  databaseUrl: string;\n}\n\nexport function getSensitiveConfig(): SensitiveConfig {\n  // In a real application, fetch from environment variables or a secure store\n  return {\n    apiKey: process.env.MY_API_KEY ?? 'sk_test_123',\n    databaseUrl: process.env.DATABASE_URL ?? 'mongodb://localhost:27017/mydb',\n  };\n}\n\n// Example usage for a server or CLI script:\n// If this file is executed directly via Node.js, Bun, or Deno:\n// e.g., `ts-node src/server-logic.ts`\nif (typeof process !== 'undefined' && process.argv[1] === require.main?.filename) {\n  console.log(\"Executing server-side logic directly via CLI.\");\n  const config = getSensitiveConfig();\n  console.log(\"Retrieved API Key (first 5 chars):\", config.apiKey.substring(0, 5) + '...');\n  console.log(\"Database URL:\", config.databaseUrl);\n}\n// If imported into a React Server Component, it would execute there.\n// If imported into a React Client Component, it would throw a build error.","lang":"typescript","description":"Demonstrates how to use `server-cli-only` to restrict a module containing sensitive configuration to server/CLI environments, preventing client-side leakage."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install server-cli-only` or `yarn add server-cli-only` to add the package to your project dependencies.","cause":"The `server-cli-only` package is not installed in your project, or your build tool cannot locate it in `node_modules`.","error":"Module not found: Can't resolve 'server-cli-only'"},{"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.","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.","error":"error: [filepath] cannot be imported into the 'browser' runtime."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'someServerSideMethod')"}],"ecosystem":"npm"}