@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
• Published Fict package metadata (dist/index.fict.meta.json) for cross-package hook return reactivity
• Strong type and coverage gates (lint, typecheck, test:types, test:coverage, build, verify:metadata, test:attw)

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

• Runtime consumers: Node.js >= 18
• Repository development/build/test: Node.js ^22.18.0 || >=24.11.0 (the supported range of the build toolchain)
• Release publishing: Node.js 24.11 or newer
• Peer dependency: @fictjs/runtime@^0.32.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

Fict Metadata

pnpm build emits:

• dist/index.fict.meta.json
• ESM/CJS runtime files
• .d.ts and .d.cts type declarations

package.json#fict.metadata points at the generated metadata file so Fict 0.32.0 consumers can recover hook return reactivity from the published npm package.

Run pnpm verify:metadata after pnpm build to verify the generated metadata and the npm tarball contents.

Fict 0.32.0 compiler compatibility

Fict 0.32.0 consumes object-return hook metadata when reactive properties are read through the returned object:

const counter = useCounter();
return <div>{counter.count}</div>;

Its native compiler does not preserve object-property metadata through destructuring. When destructuring with Fict 0.32.0, call the accessor explicitly:

const { count } = useCounter();
return <div>{count()}</div>;

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 are versioned with each release under 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

Release Process

Prepare the package version and all versioned documentation links without creating a tag:

pnpm release:prepare 0.30.0

Review the resulting package.json and README.md, then run pnpm prepublishOnly. Commit and push the release candidate, and wait for Node CI to pass on that exact commit before creating and pushing its matching v<version> tag. Rerunning a workflow for an older tag does not include newer fix commits.

Quality Gates

Before publish, these checks must pass:

1. pnpm audit:dev
2. pnpm lint
3. pnpm format:check
4. pnpm typecheck
5. pnpm test:types
6. pnpm test:types:ts53
7. pnpm test:coverage
8. pnpm build
9. pnpm verify:size
10. pnpm lint:dist
11. pnpm verify:metadata
12. pnpm test:attw

prepublishOnly already enforces this pipeline.

License

MIT