rsc-env

library0.0.2jsnpmunverified

rsc-env is a focused utility package designed to provide a reliable method for discriminating between React Server Component (RSC) and other JavaScript environments (e.g., client components, traditional server-side rendering). It achieves this by leveraging export conditions, a modern module feature that allows bundlers to statically determine the correct environment at build time. This enables aggressive tree-shaking, ensuring that server-only logic is entirely removed from client bundles, thereby optimizing bundle size and improving application performance. The package is currently in its early stages, at version 0.0.2, and its release cadence is expected to align with the evolving React Server Components ecosystem. A key differentiator for rsc-env is its targeted approach to the `react-server` condition, offering a more robust and future-proof solution for conditional code execution in modern React applications, especially those built with frameworks like Next.js App Router, compared to heuristic-based methods (e.g., checking for `useEffect` presence). This explicit approach ensures bundler compatibility and optimal performance.

web-framework

npm install rsc-env

github ↗package ↗

INSTALL

IMPORT

SIG · RSC-ENV

rsc-env

web-frameworkjavascriptv0.0.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.

rsc

✓ import { rsc } from 'rsc-env';

✗ const { rsc } = require('rsc-env');

The package is designed for modern ESM environments, particularly React Server Components, where `require()` is not typically used and may bypass bundler optimizations relying on export conditions.

rsc

✓ import type { rsc } from 'rsc-env';

When only importing the type for `rsc`, use `import type` to ensure no runtime code is included, which is beneficial for static analysis and bundle size.

This code demonstrates how `rsc-env` can be used within a shared utility function and component to conditionally execute or include code based on whether it's running in a React Server Component or a client component environment, leveraging static tree-shaking.

// utils/feature-toggle.ts import { rsc } from "rsc-env"; interface FeatureConfig { name: string; enabledInServer: boolean; message: string; } const getFeatureStatus = (feature: string): FeatureConfig => { if (rsc) { // This block is only included in server component builds console.log(`[RSC] Checking feature '${feature}' status.`); return { name: feature, enabledInServer: true, message: `Feature '${feature}' is active on the server.` }; } else { // This block is tree-shaken from server component builds console.log(`[Client] Checking feature '${feature}' status.`); return { name: feature, enabledInServer: false, message: `Feature '${feature}' is active on the client.` }; } }; // Example usage in a shared component or utility export function MySharedComponent() { const status = getFeatureStatus("new-dashboard-widget"); return ( <div> <h2>Feature Status: {status.name}</h2> <p>{status.message}</p> {rsc && <p>Server-side logic: {status.enabledInServer ? 'Enabled' : 'Disabled'}</p>} {!rsc && <p>Client-side logic: {status.enabledInServer ? 'Enabled' : 'Disabled'}</p>} </div> ); }

Debug

Known issues

breakingAs a nascent package (v0.0.2), `rsc-env` is subject to potential API changes in minor or even patch releases, as the underlying React Server Components ecosystem is still evolving and stabilizing. Developers should anticipate that future versions might introduce breaking changes to the `rsc` export or its behavior.

fix

Always consult the latest `rsc-env` documentation and release notes when upgrading to new versions, and be prepared to adapt code.

affects: >=0.0.1

gotchaThe package's core functionality relies on bundlers correctly interpreting and applying export conditions for the `react-server` environment. Incompatible or misconfigured bundlers (e.g., older versions, custom setups not fully supporting RSC export conditions) may lead to `rsc` not resolving correctly, preventing static tree-shaking, or producing incorrect runtime behavior.

fix

Ensure your project's bundler (e.g., Webpack 5+, Vite with `@vitejs/plugin-rsc`) is up-to-date and configured to support React Server Components and their associated export conditions.

affects: >=0.0.1

gotcha`rsc-env` is specifically designed to distinguish between React Server Components and other *React* environments. It is not a general-purpose utility for differentiating between a Node.js server and a browser client in traditional SSR setups. Misapplying it for non-RSC client/server differentiation could lead to logical errors or unexpected results, as traditional SSR environments might resolve `rsc` differently than true RSC build targets.

fix

For general client/server environment checks, continue using standard methods like `typeof window === 'undefined'`. Use `rsc-env` exclusively for conditional logic pertinent to React Server Components.

affects: >=0.0.1

Errors

Common errors & fixes

rsc is always true/false, regardless of whether it's a server or client component.

The bundler is not correctly processing `rsc-env`'s export conditions, or the `react-server` condition isn't being activated as expected during the build process.

fix

Verify your bundler (e.g., Vite with `@vitejs/plugin-rsc`, Next.js App Router's built-in bundler) is properly configured for React Server Components. Ensure it supports the `exports` field and the `react-server` condition, and update to the latest compatible bundler version if necessary.

SyntaxError: Cannot use import statement outside a module

React Server Components and `rsc-env` are fundamentally built around the ES Module (ESM) ecosystem. Attempting to import `rsc-env` using CommonJS `require()` syntax in an environment where it's expecting ESM can cause this error.

fix

Always use ESM `import { rsc } from 'rsc-env';` syntax. Ensure your project is configured for ESM, especially in a React Server Component context.

Module not found: Can't resolve 'rsc-env' in ...

This error in a client bundle suggests the bundler failed to tree-shake the `rsc-env` import, or the conditional logic led to its inclusion when it should have been removed.

fix

Review the conditional logic (e.g., `if (rsc) { ... }`) to ensure it's statically analyzable by the bundler. Check bundler configuration for tree-shaking and dead code elimination settings. Ensure the `react-server` condition is only applied to server component entry points.

Upgrade

Version history

0.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/LorisSigrist/rsc-env ↗

packagehttps://www.npmjs.com/package/rsc-env ↗