RSC Environment Discriminator

Common errors

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

  cause 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

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

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

Warnings

• breaking As 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.
• gotcha The 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.
• 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.

Install

• npm install rsc-env npm
• yarn add rsc-env yarn
• pnpm add rsc-env pnpm

Imports

• rsc
  wrong:

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

  correct:

  import { rsc } from '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.

Quickstart

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>
  );
}