vite-plugin-react-server 1.2.0-alpha.1 → 1.2.1

package/plugin/config/createModuleID.ts

@@ -1,9 +1,11 @@
 import type { ResolvedUserOptions } from "../types.js";
 import { replaceExtension } from "./extMap.js";
-import { getNodeEnv } from "../getNodeEnv.js";
+import { getNodeEnv } from "./getNodeEnv.js";
 import { DEFAULT_CONFIG } from "./defaults.js";
 import type { ConfigEnv } from "vite";
-import { sep } from "node:path";
+import { sep, resolve, join } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
 
 export type ModuleIDKey =
   | "modulePattern"
@@ -20,19 +22,182 @@ export type ModuleIDKey =
 export const createDefaultModuleID = (
   options: Pick<
     ResolvedUserOptions,
-    "moduleBase" | "moduleBasePath" | "autoDiscover" | "build" | "moduleBaseURL"
+    "moduleBase" | "moduleBasePath" | "autoDiscover" | "build" | "dev" | "moduleBaseURL" | "projectRoot"
   >,
   configEnv?: ConfigEnv,
   mode = getNodeEnv()
 ) => {
-  const { moduleBase, moduleBasePath, build, moduleBaseURL } = options;
+  const { moduleBase, moduleBasePath, build, moduleBaseURL, projectRoot, autoDiscover } = options;
   const assetsDir = build.assetsDir || DEFAULT_CONFIG.BUILD.assetsDir;
   const isBuild = configEnv?.command === "build";
+  // CRITICAL: In development mode, NEVER hash, even if command is "build" (optimizer)
+  const isDevelopment = mode === "development";
+  const shouldHash = isBuild && !isDevelopment;
   const isProd = mode === "production" || isBuild;
+  // CRITICAL: In development mode, NEVER remove moduleBase (src/), even if command is "build" (optimizer)
   const removeModuleBase =
-    isProd || isBuild || options.build.preserveModulesRoot;
-  return (id: string) => {
+    (isProd || isBuild) && !isDevelopment && !options.build.preserveModulesRoot;
+  
+
+  // Hash configuration
+  const hashOption = build?.hash ?? DEFAULT_CONFIG.BUILD.hash;
+  
+  // Virtual pattern for excluding virtual modules from hashing
+  const virtualPattern = autoDiscover?.virtualPattern ?? DEFAULT_CONFIG.AUTO_DISCOVER.virtualPattern;
+  
+  // Client component pattern for hashing
+  const clientPattern = /\.client\.[cm]?[jt]sx?$/;
+
+  // Clean hash API that mimics Rollup's behavior
+  const createRollupLikeHash = (content: string, hashCharacters: 'base36' | 'base64' | 'hex' = 'base36') => {
+    const hash = createHash('sha1');
+    hash.update(content);
+    const fullHash = hash.digest('hex');
+    
+    // Apply the same character set logic as Rollup
+    switch (hashCharacters) {
+      case 'base36':
+        // Convert hex to base36 (0-9, a-z)
+        return parseInt(fullHash.substring(0, 8), 16).toString(36);
+      case 'base64':
+        // Convert to base64-like format (A-Z, a-z, 0-9, -, _)
+        return Buffer.from(fullHash.substring(0, 8), 'hex').toString('base64')
+          .replace(/\+/g, '-')
+          .replace(/\//g, '_')
+          .replace(/=/g, '');
+      case 'hex':
+      default:
+        // Return hex format
+        return fullHash.substring(0, 8);
+    }
+  };
+
+  // Hash function for client components - same logic as resolveOptions.ts
+  const hash = (input: string | null, _ssr: boolean, sourceContent?: string) => {
+    if (!input) return "";
+    if (new RegExp(/\.(node|d\.ts)$/).test(input)) {
+      return input;
+    }
+    
+    // CRITICAL: Never hash node_modules files - Vite/Rollup handles those
+    if (input.includes("node_modules")) {
+      return input;
+    }
     
+    // CRITICAL: Never hash virtual modules (_virtual or matching virtualPattern) - Vite handles those
+    if (input.includes("_virtual") || (virtualPattern && virtualPattern.test(input))) {
+      return input;
+    }
+    
+    // Check if hashing is disabled
+    if (hashOption === "false") {
+      return input;
+    }
+    
+    // Only hash client components - server files should not be hashed
+    const isClientComponent = clientPattern.test(input);
+
+    if (!isClientComponent) {
+      return input;
+    }
+    
+    // Always hash the source content for consistency across builds
+    // This ensures the same hash is generated in transformer and build process
+    let contentToHash: string;
+    
+    if (sourceContent) {
+      // Use provided source content (preferred)
+      contentToHash = sourceContent;
+    } else {
+      // Try to read source file content
+      try {
+        const sourcePath = resolve(projectRoot, input);
+        if (existsSync(sourcePath)) {
+          contentToHash = readFileSync(sourcePath, 'utf-8');
+        } else {
+          // Fallback to filename
+          contentToHash = input;
+        }
+      } catch (error) {
+        // Fallback to filename
+        contentToHash = input;
+      }
+    }
+    
+    // Generate hash using Rollup-like algorithm
+    const hashCharacters = typeof hashOption === 'object' && hashOption?.format === 'hex' ? 'hex' : 'base36';
+    const contentHash = createRollupLikeHash(contentToHash, hashCharacters);
+    
+    // Apply naming logic
+    const extensionIndex = input.lastIndexOf(".");
+    if (extensionIndex !== -1) {
+      const extension = input.slice(extensionIndex);
+      const filename = input.slice(0, extensionIndex);
+      return filename + "-" + contentHash + extension;
+    } else {
+      return input + "-" + contentHash;
+    }
+  };
+  const staticClientDist = isBuild ? join(build?.outDir || "dist", build?.static || "static") : "";
+  const ssrClientDist = isBuild ? join(build?.outDir || "dist", build?.client || "client") : "";
+  const serverDist = isBuild ? join(build?.outDir || "dist", build?.server || "server") : "";
+  const buildDirs = isBuild ? [serverDist, ssrClientDist, staticClientDist] : [];
+
+  return (id: string, sourceContent?: string) => {
+    // For transformer usage (when we're in build mode and processing server components),
+    // we want to strip build directory prefixes to get relative paths
+    // This ensures the RSC stream contains paths that can be resolved by the HTML transform
+    if (shouldHash) {
+      // Strip build directory prefixes to get relative paths
+      for (const buildDir of buildDirs) {
+        if (id.startsWith(buildDir)) {
+          const result = id.slice(buildDir.length);
+          return result;
+        }
+      }
+      // Check for double path issues (like dist/client//dist/server/)
+      if (id.includes('//')) {
+        // Try to fix double path issues by finding the last occurrence of dist/
+        const lastDistIndex = id.lastIndexOf('dist/');
+        if (lastDistIndex !== -1) {
+          const result = id.slice(lastDistIndex);
+          return result;
+        }
+      }
+      
+      // For client components in build mode, transform source paths to built paths
+      const isClientComponent = clientPattern.test(id);
+      if (isClientComponent) {
+        // Transform source path to built client path
+        let transformedId = id;
+        
+        // Step 1: Remove moduleBase (typically "src/") from the beginning
+        if (removeModuleBase && transformedId.startsWith(moduleBase + sep)) {
+          transformedId = transformedId.slice(moduleBase.length + sep.length);
+        }
+        
+        // Step 2: Apply extension mapping for build
+        transformedId = replaceExtension(transformedId, {
+          build: { extensionMap: build.extensionMap },
+        });
+        
+        
+        // Step 3: Apply hashing for client components
+        transformedId = hash(transformedId, false, sourceContent);
+        
+        // Step 4: Ensure paths start with moduleBasePath
+        if (moduleBasePath && !transformedId.startsWith(moduleBasePath)) {
+          transformedId = moduleBasePath + transformedId;
+        }
+        
+        return transformedId;
+      }
+      
+      return id;
+    }
+    
+    // Normal build path transformation (existing logic)
+
     // Step 1: Handle assets directory paths - remove src from within assets path
     // Transform: assets/src/page/file.css -> assets/page/file.css
     if (id.startsWith(assetsDir + sep + moduleBase + sep)) {
@@ -55,18 +220,44 @@ export const createDefaultModuleID = (
       id = id.slice(moduleBase.length + sep.length);
     }
 
-    // Step 5: Ensure paths start with a moduleBasePath
-    if (!id.startsWith(moduleBasePath)) {
+    // Step 5: Ensure paths start with moduleBasePath (avoid double-prefix)
+    if (moduleBasePath && !id.startsWith(moduleBasePath)) {
       id = moduleBasePath + id;
     }
     
-    // Step 6: Apply extension mapping for build
-    if (isBuild) {
+    // Step 6: Apply extension mapping
+    // ALWAYS replace extensions for client components (browser can't import .tsx)
+    // For other files, only replace in build mode
+    const isClientComponent = clientPattern.test(id);
+    if (isBuild || isClientComponent) {
       id = replaceExtension(id, {
         build: { extensionMap: build.extensionMap },
       });
     }
     
+    // Step 7: Ensure CSS files are placed in the assets directory
+    if (isBuild && id.endsWith('.css') && !id.startsWith(assetsDir + sep)) {
+      id = assetsDir + sep + id;
+    }
+    
+    // Step 8: Apply hashing for client components (only in production builds, not dev)
+    if (shouldHash) {
+      id = hash(id, false, sourceContent);
+    }
+    
+    // For client components, ensure no leading slash to allow proper relative resolution
+    // (isClientComponent already defined in Step 6)
+    if (isClientComponent && moduleBasePath === '') {
+      return id; // No leading slash for client components
+    }
+    
+    // Don't add leading slash for relative paths - this causes module resolution issues
+    if (moduleBasePath === '') {
+      return id; // Return as-is without leading slash
+    }
+    
+    // id already has moduleBasePath from Step 5 — return as-is
     return id;
   };
 };
+

package/plugin/config/defaults.tsx

@@ -2,8 +2,10 @@ import { Root } from "../components/root.js";
 import { Html } from "../components/html.js";
 import { parse } from "../loader/parse.js";
 import { pluginRoot } from "../root.js";
-import { getNodeEnv } from "../getNodeEnv.js";
-
+import { getNodeEnv } from "./getNodeEnv.js";
+import { getCondition } from "./getCondition.js";
+import { createLogger } from "vite";
+const LOGGER = createLogger();
 // Directive patterns - matching the logic in findDirectiveMatches.ts
 const DIRECTIVE_PATTERNS = {
   // Client directive must be at start of file
@@ -24,6 +26,13 @@ const IS_CLIENT_COMPONENT_CODE = (code: string, moduleId?: string) =>
   code.match(CLIENT_COMPONENT_FILE) != null ||
   (moduleId && CLIENT_COMPONENT_FILE.test(moduleId.toLowerCase())) ||
   false;
+
+// Separate functions for checking client components by code vs by name
+const IS_CLIENT_COMPONENT_BY_CODE = (code: string) =>
+  code.match(CLIENT_COMPONENT_FILE) != null || false;
+
+const IS_CLIENT_COMPONENT_BY_NAME = (moduleId: string, _transformedModuleId?: string) =>
+  CLIENT_COMPONENT_FILE.test(moduleId.toLowerCase()) || false;
 // Directive configurations
 export const DIRECTIVE_CONFIGS = {
   client: {
@@ -67,6 +76,15 @@ export const getDirectiveType = (
   return undefined;
 };
 
+export const MODE = getNodeEnv();
+export const CONDITION = getCondition();
+export const IS_SERVER = CONDITION === "react-server";
+export const IS_CLIENT = CONDITION === "react-client";
+// Note: This should be replaced with configEnv.command === "build" in functions that receive configEnv
+// This is kept for backward compatibility but should not be used in new code
+export const IS_BUILD = process.argv.includes("build");
+export const IS_SERVE = !IS_BUILD; // dont have to check for dev since it's the default
+
 // Helper to normalize directive strings
 // const normalizeDirective = (directive: string) => directive.replace(/\s+/g, '').toLowerCase();
 
@@ -77,6 +95,8 @@ export const DEFAULT_LOADER_CONFIG = {
   directivePattern: DIRECTIVE_PATTERNS.ANY,
   isServerFunctionCode: IS_SERVER_ACTION_CODE,
   isClientComponentCode: IS_CLIENT_COMPONENT_CODE,
+  isClientComponentByCode: IS_CLIENT_COMPONENT_BY_CODE,
+  isClientComponentByName: IS_CLIENT_COMPONENT_BY_NAME,
   allowedDirectives: DIRECTIVE_CONFIGS,
   importServerPath: "react-server-dom-esm/server",
   importClientPath: "react-server-dom-esm/server",
@@ -84,7 +104,11 @@ export const DEFAULT_LOADER_CONFIG = {
   registerServerReferenceName: "registerServerReference",
   getDirectiveType,
   parse: parse,
-  mode: getNodeEnv(),
+  mode: MODE,
+  verbose: false,
+  logger: LOGGER,
+  moduleID: (moduleId: string, _sourceContent?: string) =>
+    typeof moduleId === "string" ? moduleId : String(moduleId),
 } as const;
 
 // Define base patterns that can be reused
@@ -108,12 +132,11 @@ export const BASE_PATTERNS = {
     NODE: ".node",
   },
 } as const;
-
 export const DEFAULT_CONFIG = {
   CLIENT_ASSETS_DIR: "assets",
   RSC_DIR: "rsc",
   MODULE_BASE: "src",
-  MODULE_BASE_PATH: "/",
+  MODULE_BASE_PATH: "",
   MODULE_BASE_URL: "/",
   PUBLIC_ORIGIN: "",
   PAGE: "page.tsx",
@@ -134,7 +157,8 @@ export const DEFAULT_CONFIG = {
   RSC_EXTENSION: ".rsc",
   ROOT: undefined,
   HTML: undefined,
-  ON_METRICS: () => {},
+  ON_METRICS: undefined,
+  ON_EVENT: undefined,
   DEV_PORT: 5173,
   PREVIEW_PORT: 4173,
   DEV_HOST: "localhost",
@@ -142,8 +166,11 @@ export const DEFAULT_CONFIG = {
   ENV_PREFIX: "VITE_",
   REACT_DIRECTIVES: new Set(["use client", "use server"]),
   RSC_TIMEOUT: 5000, // 5 seconds default timeout for RSC operations
+  HTML_TIMEOUT: 15000, // 15 seconds default timeout for HTML generation operations
   HTML_WORKER_STARTUP_TIMEOUT: 3000, // 3 seconds default timeout for HTML worker startup
   RSC_WORKER_STARTUP_TIMEOUT: 3000, // 3 seconds default timeout for RSC worker startup
+  FILE_WRITE_TIMEOUT: 10000, // 10 seconds default timeout for file write operations
+  WORKER_SHUTDOWN_TIMEOUT: 1000, // Reduced to 1 second for faster test cleanup
   COMPONENTS: {
     Html: Html,
     Root: Root,
@@ -184,17 +211,36 @@ export const DEFAULT_CONFIG = {
     rscExtension: BASE_PATTERNS.EXT.RSC,
     cssModuleExtension: BASE_PATTERNS.EXT.CSS_MODULE,
     nodeExtension: BASE_PATTERNS.EXT.NODE,
+    // these defaults rely on process.argv
+    // even better is to use configEnv.command === "build"
+    // which will be done in createHandlerOptions.server.ts and createHandlerOptions.client.ts
+    useRscWorker: !IS_SERVER && IS_BUILD,
+    useHtmlWorker: IS_SERVER && IS_BUILD,
+  },
+  DEV: {
+    // these defaults rely on process.argv
+    useHtmlWorker: false, // during dev, the browser is the html-worker..
+    // if the user opts-in to creating the html-worker, the stream utilities
+    // will be able to stream html during development - the plugin never does this
+    // so we don't have to create the html-worker during dev by default
+    useRscWorker: !IS_SERVER && IS_SERVE, // during dev without server-conditions,
+    // the rsc-worker is created during dev by default
+    // this is because the rsc-worker is used to stream rsc during development
   },
   CSS: {
-    inlineCss: false,
+    inlineCss: undefined,
     purgeCss: false,
     inlineThreshold: 4096, // 4KB
     inlinePatterns: [] as RegExp[], // Always inline CSS modules
     linkPatterns: [] as RegExp[], // Always link node_modules CSS
   },
-  MODULE_BASE_EXCEPTIONS: [] as string[],
 
   AUTO_DISCOVER: {
+    clientEntry: "**/*.client.*",
+    serverEntry: "**/*.server.*",
+    cssEntry: "**/*.css",
+    jsonEntry: "**/*.json",
+    htmlEntry: "**/*.html",
     // Pattern matchers
     modulePattern: new RegExp(BASE_PATTERNS.MODULE),
     serverPattern: new RegExp(BASE_PATTERNS.SERVER),
@@ -217,7 +263,9 @@ export const DEFAULT_CONFIG = {
   },
   MODULE_ID: (id: string) => id,
   VERBOSE: false,
-  PANIC_THRESHOLD: "none" as const,
+  PANIC_THRESHOLD: (MODE === "development"
+    ? "critical_errors"
+    : "all_errors") as "critical_errors" | "all_errors",
   // Centralized loader config for RSC boundaries
   RSC_LOADER: {
     development: {
@@ -238,4 +286,5 @@ export const DEFAULT_CONFIG = {
   REACT_LOADER_PATH: pluginRoot + "/loader/react-loader.js",
   CSS_LOADER_PATH: pluginRoot + "/loader/css-loader.js",
   ENV_LOADER_PATH: pluginRoot + "/loader/env-loader.js",
+  
 };

package/plugin/config/envPrefixFromConfig.ts

@@ -0,0 +1,10 @@
+import type { ResolvedConfig } from "vite";
+import { DEFAULT_CONFIG } from "./defaults.js";
+
+export function envPrefixFromConfig(config: Pick<ResolvedConfig, "envPrefix">) {
+  return typeof config.envPrefix === "string"
+    ? config.envPrefix
+    : Array.isArray(config.envPrefix)
+    ? config.envPrefix[0]
+    : DEFAULT_CONFIG.ENV_PREFIX;
+}

package/plugin/config/getCondition.ts

@@ -1,13 +1,270 @@
-export const getCondition = <Prefix extends string = "react-">(
-  prefix: Prefix = "react-" as Prefix
-): `${Prefix}client` | `${Prefix}server` => {
-  return process.env["NODE_OPTIONS"]?.match(/--conditions[= ]react-server/)
-    ? (`${prefix}server` as `${Prefix}server`)
-    : (`${prefix}client` as `${Prefix}client`);
+// Note: do not import Node-only modules here (e.g., 'node:worker_threads').
+// This file is consumed in both server and client plugin contexts.
+
+/**
+ * Tokenizes NODE_OPTIONS string into individual arguments
+ * Handles quoted strings, spaces, and special characters
+ */
+const tokenizeNodeOptions = (): string[] => {
+  const nodeOptions = process.env["NODE_OPTIONS"] || "";
+  if (!nodeOptions.trim()) {
+    return [];
+  }
+
+  const tokens: string[] = [];
+  let current = "";
+  let inQuotes = false;
+  let quoteChar = "";
+  let i = 0;
+
+  while (i < nodeOptions.length) {
+    const char = nodeOptions[i];
+
+    if (inQuotes) {
+      if (char === quoteChar) {
+        inQuotes = false;
+        quoteChar = "";
+        if (current.trim()) {
+          tokens.push(current.trim());
+          current = "";
+        }
+      } else {
+        current += char;
+      }
+    } else {
+      if (char === '"' || char === "'") {
+        if (current.trim()) {
+          tokens.push(current.trim());
+          current = "";
+        }
+        inQuotes = true;
+        quoteChar = char;
+      } else if (char === " " || char === "\t" || char === "\n") {
+        if (current.trim()) {
+          tokens.push(current.trim());
+          current = "";
+        }
+      } else {
+        current += char;
+      }
+    }
+    i++;
+  }
+
+  if (current.trim()) {
+    tokens.push(current.trim());
+  }
+
+  return tokens.filter(Boolean);
+};
+
+/**
+ * Parses command-line arguments for conditions and other flags
+ */
+const parseNodeArgs = (args: string[]) => {
+  const conditions: string[] = [];
+  const flags = new Set<string>();
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--conditions" || arg === "-C") {
+      // Next argument is the condition value
+      if (i + 1 < args.length) {
+        const conditionValue = args[i + 1];
+        conditions.push(
+          ...conditionValue
+            .split(",")
+            .map((c) => c.trim())
+            .filter(Boolean)
+        );
+        i++; // Skip the next argument since we consumed it
+      }
+    } else if (arg.startsWith("--conditions=")) {
+      // Condition value is part of the same argument
+      const conditionValue = arg.substring("--conditions=".length);
+      conditions.push(
+        ...conditionValue
+          .split(",")
+          .map((c) => c.trim())
+          .filter(Boolean)
+      );
+    } else if (arg === "--no-addons") {
+      flags.add("no-addons");
+    } else if (arg.startsWith("--")) {
+      // Other flags
+      flags.add(arg);
+    }
+  }
+
+  return { conditions, flags };
+};
+
+/**
+ * Gets all conditions from both NODE_OPTIONS and command-line arguments
+ */
+export const getAllConditions = (): string[] => {
+  // Parse NODE_OPTIONS
+  const nodeOptionsTokens = tokenizeNodeOptions();
+  const { conditions: envConditions } = parseNodeArgs(nodeOptionsTokens);
+
+  // Parse command-line arguments
+  const { conditions: cliConditions } = parseNodeArgs(process.execArgv);
+
+  // Combine all conditions
+  return [...envConditions, ...cliConditions];
+};
+
+// ----------------------------------------------------------------------------
+// Ambiguity detection and warning
+// ----------------------------------------------------------------------------
+let didWarnAmbiguousConditions = false;
+// react-static does not exists, because you still need condition react-server for the .static imports to work.
+const reactConditionSet = new Set(["react-server", "react-client"]);
+
+export const detectReactConditionAmbiguity = (): string[] => {
+  const conditions = getAllConditions();
+  const found = conditions.filter((c) => reactConditionSet.has(c));
+  const unique = Array.from(new Set(found));
+  return unique;
 };
 
-export const isReactServerCondition = (condition: string = getCondition()) =>
-  condition === "react-server";
+export const warnIfAmbiguousReactConditions = (): void => {
+  if (didWarnAmbiguousConditions) return;
+  const unique = detectReactConditionAmbiguity();
+  if (unique.includes("react-server") && unique.includes("react-client")) {
+    didWarnAmbiguousConditions = true;
+    const nodeOptions = process.env["NODE_OPTIONS"] || "";
+    const argv = process.execArgv.join(" ");
+    const msg =
+      `Both react-server and react-client conditions detected in NODE_OPTIONS/execArgv. ` +
+      `This can lead to ambiguous resolution. Found: [${unique.join(", ")}]\n` +
+      `NODE_OPTIONS="${nodeOptions}"\nexecArgv="${argv}"\n` +
+      `Tip: set exactly one condition or let the plugin manage worker conditions.`;
+    // Use process.emitWarning to avoid throwing
+    try {
+      process.emitWarning(msg, {
+        code: "VPRS_CONDITION_AMBIGUITY",
+        detail: "vite-plugin-react-server detected conflicting conditions",
+      } as any);
+    } catch {
+      // Fallback
+
+      console.warn(`[vite-plugin-react-server] ${msg}`);
+    }
+  }
+};
+
+/**
+ * Gets the current condition, defaulting to "react-client" if no conditions are set
+ */
+export const getCurrentCondition = ():
+  | "react-server"
+  | "react-client"
+  | undefined => {
+  // Warn if we detect both conditions present
+  warnIfAmbiguousReactConditions();
+
+  // Check both NODE_OPTIONS and execArgv for conditions
+  const conditions = getAllConditions();
+  if (conditions.includes("react-server")) return "react-server";
+  if (conditions.includes("react-client")) return "react-client";
+
+  // Default to react-client when nothing is set
+  return undefined;
+};
+
+/**
+ * Gets the condition with a custom prefix
+ */
+export const getCondition = <Prefix extends string = "react-", DefaultCondition extends `${Prefix}${string}` = `${Prefix}client`>(
+  prefix: Prefix = "react-" as Prefix,
+  defaultReturn:
+    | `${Prefix}server`
+    | `${Prefix}client` = `${prefix}client` as `${Prefix}client`
+): `${Prefix}client` | `${Prefix}server` | DefaultCondition => {
+  const condition = getCurrentCondition();
+  if (condition === "react-server") {
+    return `${prefix}server` as `${Prefix}server`;
+  }
+  if (condition === "react-client") {
+    return `${prefix}client` as `${Prefix}client`;
+  }
+  return defaultReturn;
+};
+
+/**
+ * Asserts that the current condition is react-server
+ * Throws an error with a descriptive message if not
+ */
+export function assertReactServer(): asserts this is {
+  condition: "react-server";
+} {
+  const currentCondition = getCurrentCondition();
+  if (currentCondition !== "react-server") {
+    // Debug-only: avoid Node-only APIs to keep this file browser-safe
+    throw new Error(
+      `Condition mismatch, should be react-server. Set NODE_OPTIONS="--conditions=react-server" or --conditions=react-server`
+    );
+  }
+}
+
+export function assertNonReactServer(): asserts this is {
+  condition: "react-client";
+} {
+  const currentCondition = getCurrentCondition();
+  if (currentCondition === "react-server") {
+    // Debug-only: avoid Node-only APIs to keep this file browser-safe
+    throw new Error(
+      `Condition mismatch, should not be react-server. Remove NODE_OPTIONS="--conditions=react-server" or --conditions=react-server`
+    );
+  }
+}
+
+/**
+ * Checks if the current condition is react-server (strict - requires both NODE_OPTIONS and execArgv)
+ * Use this for React Server DOM compatibility checks
+ */
+export const isReactServerCondition = (): boolean =>
+  getCurrentCondition() === "react-server";
+
+/**
+ * Checks if the current condition is react-client (strict - requires both NODE_OPTIONS and execArgv)
+ * Use this for React Server DOM compatibility checks
+ */
+export const isReactClientCondition = (): boolean =>
+  getCurrentCondition() === "react-client";
+
+/**
+ * Checks if react-server condition is present in either NODE_OPTIONS OR execArgv (lenient)
+ * Use this for plugin internal environment gating
+ */
+export const hasReactServerCondition = (): boolean => {
+  const allConditions = getAllConditions();
+  return allConditions.includes("react-server");
+};
+
+/**
+ * Checks if react-client condition is present in either NODE_OPTIONS OR execArgv (lenient)
+ * Use this for plugin internal environment gating  
+ */
+export const hasReactClientCondition = (): boolean => {
+  const allConditions = getAllConditions();
+  return allConditions.includes("react-client");
+};
+
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use getAllConditions() instead
+ */
+export const getNodeOptionsConditions = (): string[] => {
+  const nodeOptionsTokens = tokenizeNodeOptions();
+  const { conditions } = parseNodeArgs(nodeOptionsTokens);
+  return conditions;
+};
 
-export const isReactClientCondition = (condition: string = getCondition()) =>
-  condition === "react-client";
+/**
+ * Legacy export for backward compatibility
+ * @deprecated Use getCurrentCondition() instead
+ */
+export const condition = getCurrentCondition();