@fictjs/hooks

Official hooks package for Fict.

@fictjs/hooks provides official, production-ready hooks built for Fict signal/lifecycle semantics.

Highlights

• 39 official hooks across lifecycle, event, timing, state, browser, storage, observer, async and clipboard
• SSR-safe browser hooks with injectable globals (window, document, navigator) for non-browser/test environments
• Root-only public entry (@fictjs/hooks) with ESM tree shaking support
• Strong type coverage and CI quality gates (lint, typecheck, test:types, test, build)

Install

For application usage:

npm add @fictjs/hooks @fictjs/runtime
# or
yarn add @fictjs/hooks @fictjs/runtime
# or
pnpm add @fictjs/hooks @fictjs/runtime

Requirements

• Node.js >= 18
• Peer dependency: @fictjs/runtime@^0.13.0

Quick Start

import { useCounter, useMount } from '@fictjs/hooks';

export function CounterExample() {
  const { count, inc, dec, reset } = useCounter(0);

  useMount(() => {
    inc();
  });

  return { count, inc, dec, reset };
}

In plain TypeScript/JavaScript usage (without Fict compile transforms), read reactive values via accessors, for example count().

Import Policy

• Only import from @fictjs/hooks; deep imports are unsupported
• Tree shaking is supported through ESM exports and "sideEffects": false

Runtime Semantics

• Hooks follow Fict top-level hook rules (useX in component/hook top-level scope)
• Effects/listeners/timers are auto-cleaned on root dispose
• Browser hooks are SSR-safe and provide unsupported fallbacks
• Browser globals can be injected with options like window, document, or navigator when needed

Hook Docs

All hook docs live in docs/hooks.

• Lifecycle: useMount, useUnmount
• Event: useEventListener, useClickOutside, useHover, useFocusWithin, useKeyPress
• Timing: useDebounceFn, useThrottleFn, useTimeoutFn, useIntervalFn, useRafFn
• State: useToggle, useCounter, usePrevious, useVirtualList
• Browser: useScroll, useWindowScroll, useWindowSize, useTitle, useFullscreen, usePermission, useGeolocation, useIdle, useSize, useWebSocket, useMediaQuery, useDocumentVisibility, useNetwork
• Storage: useStorage, useLocalStorage, useSessionStorage
• Observer: useIntersectionObserver, useResizeObserver, useMutationObserver
• Async: useAsyncState, useFetch, useRequest
• Clipboard: useClipboard

Demo Website

Run interactive hook demos:

pnpm demo:dev

Build static demo site:

pnpm demo:build

Quality Gates

Before publish, these checks must pass:

1. pnpm lint
2. pnpm typecheck
3. pnpm test:types
4. pnpm test
5. pnpm build

prepublishOnly already enforces this pipeline.

License

MIT