options.ts

import type { RuleSetCondition } from '@rspack/core';
import type { IntegrationType } from './utils/getSocketIntegration';

interface OverlayOptions {
  entry: string;
  module: string;
  sockIntegration: IntegrationType | false;
  sockHost?: string;
  sockPath?: string;
  sockPort?: string;
  sockProtocol?: string;
}

export type PluginOptions = {
  /**
   * Specifies which files should be processed by the React Refresh loader.
   * This option is passed to the `builtin:react-refresh-loader` as the `rule.test` condition.
   * Works identically to Rspack's `rule.test` option.
   * @see https://rspack.dev/config/module#ruletest
   */
  test?: RuleSetCondition;
  /**
   * Explicitly includes files to be processed by the React Refresh loader.
   * This option is passed to the `builtin:react-refresh-loader` as the `rule.include` condition.
   * Use this to limit processing to specific directories or file patterns.
   * Works identically to Rspack's `rule.include` option.
   * @default /\.([cm]js|[jt]sx?|flow)$/i
   * @see https://rspack.dev/config/module#ruleinclude
   */
  include?: RuleSetCondition | null;
  /**
   * Exclude files from being processed by the plugin.
   * The value is the same as the `rule.exclude` option in Rspack.
   * @default /node_modules/
   * @see https://rspack.dev/config/module#ruleexclude
   */
  exclude?: RuleSetCondition | null;
  /**
   * Can be used to exclude certain resources from being processed by
   * the plugin by the resource query.
   * @see https://rspack.dev/config/module#ruleresourcequery
   *
   * @example
   * To exclude all resources with the `raw` query, such as
   * `import rawTs from './ReactComponent.ts?raw';`, use the following:
   * ```ts
   * { resourceQuery: { not: /raw/ } }
   * ```
   */
  resourceQuery?: RuleSetCondition;
  /**
   * Sets a namespace for the React Refresh runtime.
   * It is most useful when multiple instances of React Refresh is running
   * together simultaneously.
   * @default `output.uniqueName || output.library`
   */
  library?: string;
  /**
   * Whether to force enable the plugin.
   * By default, the plugin will not be enabled in non-development environments.
   * If you want to force enable the plugin, you can set this option to `true`.
   * @default false
   */
  forceEnable?: boolean;
  /**
   * Modify the behavior of the error overlay.
   * @default false
   */
  overlay?: boolean | Partial<OverlayOptions>;

  /**
   * Whether to inject the builtin:react-refresh-loader
   * @default true
   */
  injectLoader?: boolean;

  /**
   * Whether to inject the client/reactRefreshEntry.js
   * @default true
   */
  injectEntry?: boolean;
  /**
   * Whether to reload the page on runtime errors. E.g: undefined module factory
   * @default false
   */
  reloadOnRuntimeErrors?: boolean;
};

export interface NormalizedPluginOptions extends Required<PluginOptions> {
  overlay: false | OverlayOptions;
}

const d = <K extends keyof PluginOptions>(
  object: PluginOptions,
  property: K,
  defaultValue?: PluginOptions[K],
) => {
  // TODO: should we also add default for null?
  if (
    typeof object[property] === 'undefined' &&
    typeof defaultValue !== 'undefined'
  ) {
    object[property] = defaultValue;
  }
  return object[property];
};

const normalizeOverlay = (options: PluginOptions['overlay']) => {
  const defaultOverlay: OverlayOptions = {
    entry: require.resolve('../client/errorOverlayEntry.js'),
    module: require.resolve('../client/overlay/index.js'),
    sockIntegration: 'wds',
  };
  if (!options) {
    return false;
  }
  if (typeof options === 'undefined' || options === true) {
    return defaultOverlay;
  }
  options.entry = options.entry ?? defaultOverlay.entry;
  options.module = options.module ?? defaultOverlay.module;
  options.sockIntegration =
    options.sockIntegration ?? defaultOverlay.sockIntegration;
  return options;
};

export function normalizeOptions(
  options: PluginOptions,
): NormalizedPluginOptions {
  d(options, 'exclude', /node_modules/i);
  d(options, 'include', /\.([cm]js|[jt]sx?|flow)$/i);
  d(options, 'library');
  d(options, 'forceEnable', false);
  d(options, 'injectLoader', true);
  d(options, 'injectEntry', true);
  d(options, 'reloadOnRuntimeErrors', false);
  options.overlay = normalizeOverlay(options.overlay);
  return options as NormalizedPluginOptions;
}