Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
3.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file devWarning.ts
 * @input A component/hook name and a message
 * @output Standardized `Component: message` console warnings and errors
 * @position Shared dev-logging utility used across components and hooks
 *
 * Every message reads `Component: message`, so the source is clear in the
 * console. Prefer `useDevWarning` in components, because it does not repeat
 * a warning on each render. These helpers are for plain functions, module
 * initialization and effects.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/utils/index.ts
 * - /packages/core/src/hooks/useDevWarning.ts (the render-path counterpart)
 */

// Bundlers replace this value at build time. The declaration lets a product
// without Node's types type-check this file.
declare const process: {readonly env: {readonly NODE_ENV?: string}};

const isDev = process.env.NODE_ENV !== 'production';

/** Format a message as `Component: message`. */
export function formatDevMessage(component: string, message: string): string {
  return `${component}: ${message}`;
}

/**
 * Dev-only `console.warn` in the standardized `Component: message` format.
 * A no-op in production — warnings are builder guardrails, not shipped noise.
 * Extra args (e.g. an offending value) are forwarded to `console.warn`.
 *
 * @example
 * ```
 * devWarn('Popover', 'children must contain a <button>.');
 * ```
 */
export function devWarn(
  component: string,
  message: string,
  ...args: unknown[]
): void {
  if (!isDev) {
    return;
  }
  console.warn(formatDevMessage(component, message), ...args);
}

/** Warns once for each key. Internal. */
export type DevWarnings = (
  component: string,
  message: string,
  key?: string,
) => void;

/** Per-instance diagnostics for hooks and imperative callbacks. Internal. */
export function createDevWarnings(): DevWarnings {
  const warned = new Set<string>();
  return (component: string, message: string, key: string = message): void => {
    if (process.env.NODE_ENV === 'production' || warned.has(key)) {
      return;
    }
    warned.add(key);
    devWarn(component, message);
  };
}

/**
 * `console.error` in the standardized `Component: message` format. Unlike
 * {@link devWarn}, this runs in production too: it reports real runtime
 * failures (e.g. a thrown callback) that should reach error telemetry.
 *
 * @example
 * ```
 * devError('Table', 'Plugin at index 0 threw in transform:', error);
 * ```
 */
export function devError(
  component: string,
  message: string,
  ...args: unknown[]
): void {
  console.error(formatDevMessage(component, message), ...args);
}

const warnedKeys = new Set<string>();

/**
 * Dev-only warning that fires at most once per `key` for the lifetime of the
 * app. Use for singleton warnings that aren't tied to a component instance —
 * a missing translation key, a per-theme perf hint, a one-time fallback.
 * For per-component-instance warnings, use the `useDevWarning` hook instead.
 *
 * @example
 * ```
 * warnOnce(`theme:${name}`, 'Theme', `"${name}" uses runtime injection.`);
 * ```
 */
export function warnOnce(
  key: string,
  component: string,
  message: string,
  ...args: unknown[]
): void {
  if (!isDev || warnedKeys.has(key)) {
    return;
  }
  warnedKeys.add(key);
  console.warn(formatDevMessage(component, message), ...args);
}

/**
 * Clear `warnOnce` dedup state. Test-only.
 * @internal
 */
export function __resetDevWarnings(): void {
  warnedKeys.clear();
}