@winglet/react-utils

yarn add @winglet/react-utils

React utility library providing custom hooks, higher-order components (HOCs), a Portal system, and helper functions. Supports React 16–19, with full TypeScript types and tree-shakeable sub-path exports.

Installation

yarn add @winglet/react-utils
# peer deps: react >=16 <20, react-dom >=16 <20

Sub-path Exports

Import path	Contents
@winglet/react-utils	All exports
@winglet/react-utils/hook	Custom hooks
@winglet/react-utils/hoc	Higher-order components
@winglet/react-utils/portal	Portal component system
@winglet/react-utils/filter	React type-checking utilities
@winglet/react-utils/object	React-specific object utilities
@winglet/react-utils/render	Component rendering helpers

Key Exports

Hooks (/hook)

Hook	Description
useConstant(factory)	Memoizes a value on first render only
useHandle(fn)	Stable callback that always calls the latest function
useMemorize(deps, factory)	Enhanced memoization with intuitive API
useSnapshot(value)	Returns a stable snapshot of a value
useDebounce(value, delay)	Debounced value
useWindowSize()	Tracks browser window dimensions
useEffectUntil(effect, condition)	Runs effect until condition is true
useOnMount(fn)	Runs callback once on mount
useOnUnmount(fn)	Runs callback once on unmount

HOCs (/hoc)

• withErrorBoundary(Component, options) — wraps with error boundary
• withErrorBoundaryForwardRef(Component, options) — with ref forwarding
• withUploader(Component, options) — file upload handling

Portal (/portal)

• Portal — renders children at a designated anchor in the DOM
• Portal.Anchor — declares where portal content mounts
• withPortal(Component) — HOC providing portal context

Usage Examples

import { useConstant, useHandle, useWindowSize } from '@winglet/react-utils/hook';

function MyComponent({ onSave }: { onSave: () => void }) {
  const manager = useConstant(() => new ExpensiveManager());
  const handleSave = useHandle(onSave); // stable ref
  const { width, height } = useWindowSize();

  return <div>{width}x{height}</div>;
}

import { withErrorBoundary } from '@winglet/react-utils/hoc';
import { Portal, withPortal } from '@winglet/react-utils/portal';

const SafeWidget = withErrorBoundary(Widget, {
  fallback: <p>Something went wrong.</p>,
});

const App = withPortal(() => (
  <>
    <Portal.Anchor name="modal" />
    <Portal name="modal"><Modal /></Portal>
  </>
));

Claude Code Integration

@winglet/react-utils ships Claude Code assets — the react-utils-skill expert skill and its knowledge base covering hooks, HOC patterns, the portal system, and utility helpers — under docs/claude/. They are published alongside the package so AI assistants can reason about React-specific utilities with package-specific context.

Inject those assets into your local Claude Code environment with @slats/claude-assets-sync (bin: inject-claude-settings):

npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/react-utils --scope=user         # inject into ~/.claude (user-level)
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/react-utils --scope=project      # inject into the nearest existing .claude, walking up from cwd

# Preview / overwrite flags
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/react-utils --scope=user --dry-run   # show the plan without writing
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/react-utils --scope=user --force     # overwrite locally-modified files

The CLI resolves @winglet/react-utils/package.json via createRequire, reads its claude.assetPath (docs/claude), and applies hash-based diff into the selected .claude/ (skip unchanged, warn on divergence, require --force to overwrite).

AI Agent Reference

AI Reference

Package: @winglet/react-utils v0.10.0 Purpose: React hooks, HOCs, portal system, and render utilities.

Key exports

./portal → Portal — Portal system for rendering React components at different DOM locations while maintaining component hierarchy.
./hoc → withErrorBoundary
        withErrorBoundaryForwardRef
        withUploader
./hook → useConstant
         useDebounce
         useEffectUntil
         useLayoutEffectUntil
         useHandle
         useMemorize
         useOnMount
         useOnMountLayout
         useOnUnmount
         useOnUnmountLayout
         useReference
         useRestProperties
         useSnapshot
         useSnapshotReference
         useTimeout
         useTruthyConstant
         useVersion
         useWindowSize
./filter → isClassComponent
           isFunctionComponent
           isMemoComponent
           isReactComponent
           isReactElement
./object → remainOnlyReactComponent
./render → renderComponent