tessl/npm-react-refresh

React Refresh runtime and Babel plugin for Fast Refresh functionality that enables live editing of React components without losing state

—

Pending

Overview

Eval results

Files

Family & Instance Management

Name: tessl/npm-react-refresh
Author: tessl

Advanced APIs for querying component families and finding affected DOM instances during refresh operations. Component families group related component versions together for efficient refresh decisions.

Capabilities

getFamilyByID

Retrieves a component family by its registration ID.

/**
 * Retrieves component family by registration ID
 * @param id - Component registration ID used during register() call
 * @returns Family object if found, undefined otherwise
 * @throws Error if called in production environment
 */
function getFamilyByID(id: string): Family | void;

Usage Example:

// After registering a component
ReactRefreshRuntime.register(MyComponent, 'MyComponent%default%');

// Later retrieve the family
const family = ReactRefreshRuntime.getFamilyByID('MyComponent%default%');
if (family) {
  console.log('Current component type:', family.current);
}

getFamilyByType

Retrieves a component family by the component type itself.

/**
 * Retrieves component family by component type
 * @param type - Component type (function or class)
 * @returns Family object if found, undefined otherwise
 * @throws Error if called in production environment
 */
function getFamilyByType(type: any): Family | void;

Usage Example:

function MyComponent() {
  return <div>Hello</div>;
}

ReactRefreshRuntime.register(MyComponent, 'MyComponent');

// Retrieve family by component type
const family = ReactRefreshRuntime.getFamilyByType(MyComponent);
if (family) {
  console.log('Component is registered for refresh');
}

findAffectedHostInstances

Finds all DOM instances that are affected by changes to the specified component families.

/**
 * Finds DOM instances affected by component family changes
 * @param families - Array of component families to check
 * @returns Set of affected host DOM instances
 * @throws Error if called in production environment
 */
function findAffectedHostInstances(families: Array<Family>): Set<Instance>;

Usage Example:

// Get families for components that changed
const family1 = ReactRefreshRuntime.getFamilyByID('Component1');
const family2 = ReactRefreshRuntime.getFamilyByID('Component2');

if (family1 && family2) {
  // Find affected DOM nodes
  const affectedInstances = ReactRefreshRuntime.findAffectedHostInstances([
    family1,
    family2
  ]);
  
  console.log(`${affectedInstances.size} DOM nodes will be affected`);
}

isLikelyComponentType

Heuristic function to determine if a given type is likely a React component.

/**
 * Heuristic to determine if type is likely a React component
 * @param type - Type to check (function, class, or object)
 * @returns True if type appears to be a React component
 * @throws Error if called in production environment
 */
function isLikelyComponentType(type: any): boolean;

Usage Example:

function RegularFunction() {
  return "not a component";
}

function MyComponent() {
  return <div>Component</div>;
}

class MyClassComponent extends React.Component {
  render() {
    return <div>Class Component</div>;
  }
}

// Check component likelihood
console.log(ReactRefreshRuntime.isLikelyComponentType(RegularFunction)); // false
console.log(ReactRefreshRuntime.isLikelyComponentType(MyComponent)); // true
console.log(ReactRefreshRuntime.isLikelyComponentType(MyClassComponent)); // true

Component Family Lifecycle

Understanding how component families work:

Family Creation

// First registration creates a new family
ReactRefreshRuntime.register(MyComponentV1, 'MyComponent');

const family = ReactRefreshRuntime.getFamilyByID('MyComponent');
console.log(family.current === MyComponentV1); // true

Family Updates

// Later registration with same ID updates the family
ReactRefreshRuntime.register(MyComponentV2, 'MyComponent');

// Family now points to new version
const updatedFamily = ReactRefreshRuntime.getFamilyByID('MyComponent');
console.log(updatedFamily.current === MyComponentV2); // true

// This triggers a pending update for the next refresh cycle

Refresh Decisions

// During performReactRefresh(), families are categorized:
const refreshResult = ReactRefreshRuntime.performReactRefresh();

// Components that can preserve state
refreshResult.updatedFamilies.forEach(family => {
  console.log('Fast refresh:', family.current.name);
});

// Components that must remount
refreshResult.staleFamilies.forEach(family => {
  console.log('Full refresh:', family.current.name);
});

Types

interface Family {
  /** Current component type in this family */
  current: any;
}

/** React host instance (DOM node in browsers) */
type Instance = any;