server-cli-only

server-cli-only

This package is designed as a failsafe. All modules marked with import "server-cli-only" will throw an error on build-time if imported into a module running in the "browser" runtime (e.g., React Client Components). This package is an alternative to the server-only package, which permits the execution of React Server Components runtimes but doesn't allow using other server or edge runtimes. This package aims for the use with React but can also be used in other projects that follow this strategy.

Installation

npm i server-cli-only

Module Usage

Import server-cli-only at the beginning of a module that you want to protect from leaking to the front-end (browser):

import "server-cli-only";

Now, imports of your module importing server-cli-only into "browser" modules (e.g., React Client Components) will throw an error.

Command Line Usage

You can directly execute scripts in server runtimes like node, deno, and bun. For example:

node your-script.js

Or in your package.json:

{
  "scripts": {
    "your-cli-script": "node your-script.js"
  }
}

Context

This package tries to align with the guidelines in the React Server Module Conventions of RFC #227 but extends this guideline to also allow executions in other server and edge runtimes, not only the "react-server" runtime. The overarching goal is to restrict modules with sensitive data from being leaked to the front-end (browser) by using "conditional exports" in Node.js's package.json file. Doing so results in build-time errors for "browser" and unknown runtime modules. Following, all allowed and forbidden (error-throwing) runtimes.

Allowed Runtimes

Key	Target
react-server	React Server Components
node	Node.js runtime
bun	Bun runtime
deno	Deno runtime
edge-light	Vercel edge
netlify	Netlify edge
workerd	Cloudflare edge

Forbidden Runtimes (Error-Throwing)

Key	Target
browser	React Client Components
<unknown>	All unknown runtimes

Lookout Places for Additional Runtime Keys in the Future

Proposed Specs concerning the different runtime keys available by the Web-interoperable Runtimes Community Group (WinterCG). And React-DOM's package.json "conditional exports" field.

License

MIT License.

Links

• Source Code: https://github.com/destacks/core-ts/tree/main/packages/server-cli-only
• Project Repo: https://github.com/destacks/core-ts
• NPM Package: https://www.npmjs.com/package/server-cli-only