{"id":16200,"library":"rsc-env","title":"RSC Environment Discriminator","description":"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.","status":"active","version":"0.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/LorisSigrist/rsc-env","tags":["javascript","rsc","react-server-components","nextjs","next","next-14","app-router","rsc-env","esm-env","typescript"],"install":[{"cmd":"npm install rsc-env","lang":"bash","label":"npm"},{"cmd":"yarn add rsc-env","lang":"bash","label":"yarn"},{"cmd":"pnpm add rsc-env","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { rsc } = require('rsc-env');","symbol":"rsc","correct":"import { rsc } from 'rsc-env';"},{"note":"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.","symbol":"rsc","correct":"import type { rsc } from 'rsc-env';"}],"quickstart":{"code":"// utils/feature-toggle.ts\nimport { rsc } from \"rsc-env\";\n\ninterface FeatureConfig {\n  name: string;\n  enabledInServer: boolean;\n  message: string;\n}\n\nconst getFeatureStatus = (feature: string): FeatureConfig => {\n  if (rsc) {\n    // This block is only included in server component builds\n    console.log(`[RSC] Checking feature '${feature}' status.`);\n    return {\n      name: feature,\n      enabledInServer: true,\n      message: `Feature '${feature}' is active on the server.`\n    };\n  } else {\n    // This block is tree-shaken from server component builds\n    console.log(`[Client] Checking feature '${feature}' status.`);\n    return {\n      name: feature,\n      enabledInServer: false,\n      message: `Feature '${feature}' is active on the client.`\n    };\n  }\n};\n\n// Example usage in a shared component or utility\nexport function MySharedComponent() {\n  const status = getFeatureStatus(\"new-dashboard-widget\");\n  return (\n    <div>\n      <h2>Feature Status: {status.name}</h2>\n      <p>{status.message}</p>\n      {rsc && <p>Server-side logic: {status.enabledInServer ? 'Enabled' : 'Disabled'}</p>}\n      {!rsc && <p>Client-side logic: {status.enabledInServer ? 'Enabled' : 'Disabled'}</p>}\n    </div>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Always consult the latest `rsc-env` documentation and release notes when upgrading to new versions, and be prepared to adapt code.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"rsc is always true/false, regardless of whether it's a server or client component."},{"fix":"Always use ESM `import { rsc } from 'rsc-env';` syntax. Ensure your project is configured for ESM, especially in a React Server Component context.","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","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.","error":"Module not found: Can't resolve 'rsc-env' in ..."}],"ecosystem":"npm"}