Registry / devops / server-cli-only

server-cli-only

library0.3.2jsnpmunverified

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.

devops

npm install server-cli-only

package ↗

INSTALL

IMPORT

SIG · SERVER-CLI-ONLY

server-cli-only

devopsjavascriptv0.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

(side-effect import)

✓ import "server-cli-only";

✗ import { someValue } from "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)

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

✗ const serverCliOnly = 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)

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

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

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

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.

Debug

Known issues

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

affects: >=0.1.0

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

affects: >=0.1.0

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

affects: >=0.1.0

Errors

Common errors & fixes

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

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.

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

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.

Upgrade

Version history

0.3.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/server-cli-only ↗