A collection of essential hooks designed for both React and Voby environments. This library provides a comprehensive set of utility hooks that help you build better applications with less code, featuring dual builds optimized for both browser and server-side rendering (SSR) environments.

• 🎯 50+ Essential Hooks - State management, effects, events, utilities
• ⚡ Dual Builds - Optimized bundles for browser (37KB) and SSR (15KB)
• 🔒 Type Safe - Full TypeScript support with separate type definitions
• 🌐 Universal Compatibility - Works with React 16.8+ and Voby
• 📦 Tree Shakeable - Only import what you need

# Using npm
npm install @woby/use

# Using yarn
yarn add @woby/use

# Using pnpm
pnpm add @woby/use

The library provides separate builds for browser and server-side rendering (SSR) environments:

// Default import - works in both environments (uses SSR-safe hooks only)
import { useCounter, useBoolean } from '@woby/use';

// Explicit browser import - includes ALL hooks (browser + SSR-safe)
import { useLocalStorage, useEventListener } from '@woby/use/browser';

// Explicit SSR import - only SSR-compatible hooks
import { useCounter, useDebounce } from '@woby/use/ssr';

Recommendation: Start with the default import. Only use /browser when you specifically need browser-only hooks like useLocalStorage or useEventListener.

The library is split into two builds to optimize for different environments:

These hooks work perfectly in SSR environments and don't require browser APIs:

State Management:

• useBoolean, useCounter, useMap, useSet, useStep, useToggle, useInvert, useDestruct

Timers & Effects:

• useDebounce, useTimeout, useInterval, useTimer, usePause

Callbacks & Refs:

• useEventCallback, useIsomorphicLayoutEffect, useId, useWith

Utilities:

• useTry, useSsr, Array, Object, Ratio, use

These hooks require browser APIs (window, document, navigator, etc.) and should NOT be used during SSR:

Storage:

• useLocalStorage, useSessionStorage

DOM Events:

• useEventListener, useClickAway, useClickAnyWhere, useOnClickOutside, useHover

Layout & Size:

• useElementSize, useWindowSize, useViewportSize, useAspect, useComputedStyle

Location & Screen:

• useLocation, useGpsLocation, useScreen, useScreenOrientation, useMediaQuery

Observers:

• useIntersectionObserver

Document Operations:

• useDocumentTitle, useLockedBody

Browser APIs:

• useCopyToClipboard, useScript, useImageOnLoad, useFetch, useSelection

Theme:

• useDarkMode, useTernaryDarkMode

Other:

• isLocalhost

// This works in both browser and server - perfect for Next.js pages, Nuxt components, etc.
import { useCounter, useDebounce } from '@woby/use';

function Counter() {
  const { count, increment } = useCounter(0);
  const debouncedCount = useDebounce(count, 300);
  
  return <div>{debouncedCount}</div>;
}

// Only import browser hooks in client components
'use client'; // If using Next.js app router

import { useLocalStorage, useEventListener } from '@woby/use/browser';

function StorageComponent() {
  const value = useLocalStorage('key', 'default');
  
  return <div>{value}</div>;
}

// Universal component (SSR-safe)
import { useCounter } from '@woby/use';

export function Counter() {
  const { count } = useCounter(0);
  return <div>{count}</div>;
}

// Client component (with browser hooks)
'use client';
import { useLocalStorage } from '@woby/use/browser';

export function PersistentCounter() {
  const [value, setValue] = useLocalStorage('counter', 0);
  return <div>{value}</div>;
}

Next.js App Router:

// Server Component (default)
import { useCounter } from '@woby/use'; // ✅ Works fine

// Client Component
'use client';
import { useLocalStorage } from '@woby/use/browser'; // ✅ Has browser APIs

Nuxt 3:

<script setup>
// Auto-imported in templates, but explicit imports needed for composables
import { useCounter } from '@woby/use'
import { useLocalStorage } from '@woby/use/browser'
</script>

React SPA (No SSR):

// You can safely import everything from browser build
import { useLocalStorage, useEventListener } from '@woby/use/browser';

import { useToggle, useCounter, useLocalStorage } from '@woby/use/browser';

function MyComponent() {
  const [value, toggle] = useToggle(false);
  const { count, increment, decrement } = useCounter(0);
  const [name, setName] = useLocalStorage('name', '');
  
  return (
    <div>
      <p>Toggle value: {() => $(value) ? 'ON' : 'OFF'}</p>
      <button onClick={toggle}>Toggle</button>
      
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
      <button onClick={decrement}>-</button>
      
      <input 
        value={name} 
        onChange={(e) => setName(e.target.value)} 
        placeholder="Enter your name" 
      />
    </div>
  );
}

Note: The example above uses @woby/use/browser because it includes useLocalStorage. For SSR-safe components, use the default import and avoid browser-only hooks.

• use - Convert values to observables with optional cloning

• useBoolean - Tracks state of a boolean value
• useCounter - Tracks numerical state with increment/decrement functions
• useToggle - Toggles between two values
• useMap - Tracks state of a Map
• useSet - Tracks state of a Set
• useStep - Manages step navigation
• useCountdown - Manages countdown timers

• useLocalStorage - Manages localStorage values
• useSessionStorage - Manages sessionStorage values
• useReadLocalStorage - Reads localStorage values
• useWindowSize - Tracks window size changes
• useAspect - Calculates window aspect ratio
• useViewportSize - Accesses visual viewport properties
• useDarkMode - Tracks and toggles dark mode state
• useTernaryDarkMode - Advanced dark mode management
• useMediaQuery - Tracks media query matches
• useCopyToClipboard - Copies text to clipboard
• useDocumentTitle - Sets the document title
• useLockedBody - Locks body scrolling
• useElementSize - Tracks element size
• useIntersectionObserver - Observes element intersections
• useImageOnLoad - Handles image loading
• useScreen - Accesses screen information
• useGpsLocation - Accesses GPS location
• useLocation - Accesses browser location
• useScreenOrientation - Accesses screen orientation
• useSelection - Accesses text selection

• useEventListener - Subscribes to events
• useClickAnyWhere - Subscribes a callback to clicks anywhere on the page
• useClickAway - Detects clicks outside an element
• useOnClickOutside - Detects clicks outside an element

• useDebounce - Debounces a value or function
• useTimeout - Sets up a timeout that runs a callback
• useInterval - Sets up an interval that runs a callback
• useIsomorphicLayoutEffect - useLayoutEffect in browser, useEffect in server
• useEffectOnce - Runs an effect only once
• useUpdateEffect - Runs an effect on updates only

• useFetch - Fetches data from a URL
• useScript - Loads external scripts
• useHover - Tracks hover state of an element
• useDestruct - Destructures objects and arrays
• useEventCallback - Creates stable event callbacks
• useId - Generates unique IDs
• useInvert - Inverts boolean values
• usePause - Creates timed delays
• useTimer - Creates timers
• useTry - Executes functions with error handling

• useSsr - Handles server-side rendering
• useIsClient - Checks if running on client
• useIsFirstRender - Checks if it's the first render
• useIsMounted - Checks if component is mounted

Check out our full documentation for detailed information about each hook:

• Getting Started Guide
• API Reference
• Hook Documentation
• Examples
• Contributing Guide

# Clone the repository
git clone https://github.com/wobyjs/use
cd @woby/use

# Install dependencies
pnpm install

# Start development server (browser)
pnpm dev

# Build for production
pnpm build

# Build browser-only version
pnpm build:browser

# Build SSR-only version  
pnpm build:ssr

# Run tests
pnpm test

# Serve documentation
pnpm docs

The build process creates two separate bundles:

Browser Build (dist/browser/):

• index.browser.es.js (37 KB) - ES module format for modern bundlers
• index.browser.umd.js (43 KB) - UMD format for direct browser usage
• Full type definitions with DOM APIs (68 type files)
• Includes: All 60+ hooks (SSR-safe + browser-only)

SSR Build (dist/ssr/):

• index.ssr.es.js (15 KB) - ES module format
• index.ssr.cjs.js (17 KB) - CommonJS format for Node.js
• Type definitions without DOM dependencies (29 type files)
• Includes: Only 29 SSR-safe hooks

Bundle Size Comparison:

• Browser build: ~37 KB (gzipped: ~9 KB)
• SSR build: ~15 KB (gzipped: ~5 KB) - 60% smaller!

1. Smaller Server Bundles - SSR build excludes 30+ browser-only hooks
2. Type Safety - Prevents accidental browser API usage in SSR context
3. Better Tree-Shaking - Explicit imports enable better dead code elimination
4. Faster Compilation - Smaller bundles compile faster
5. Clear Intent - Import paths clearly indicate environment compatibility

# Clean build (removes dist folder)
pnpm build:clean

# Build everything (browser + SSR + types)
pnpm build

# Build only browser version
pnpm build:browser

# Build only SSR version
pnpm build:ssr

# Generate TypeScript declarations
pnpm build:types

# Watch mode for development
pnpm watch

The hooks in this library are designed to work with:

• React (16.8+) - Full support for all React features
• Voby - Optimized for Voby's reactive system with JSX configuration
• Next.js - SSR-safe hooks work in Server Components, browser hooks in Client Components
• Nuxt 3 - Compatible with Nuxt's composition API
• Remix - Works with both client and server rendering
• Astro - Use SSR-safe hooks in islands, browser hooks in interactive components

Next.js:

• Default imports (@woby/use) work in Server Components
• Browser hooks require 'use client' directive
• Recommended pattern: Universal components + client islands

Nuxt 3:

• Auto-imported in templates when configured
• Explicit imports needed in composables
• Use @woby/use/ssr for server plugins

React SPA (No SSR):

• Safe to use @woby/use/browser everywhere
• No need to worry about server compatibility

All hooks come with full TypeScript support and type definitions included:

• ✅ Strict Mode - Full type inference
• ✅ Generics - Proper generic type handling
• ✅ Separate Types - Different types for browser vs SSR builds
• ✅ DOM Types - Only included in browser build types
• ✅ JSX Support - Configured for both React and Voby JSX

// Full type inference
const { count, increment } = useCounter(0); // count is Observable<number>

// Generic hooks
const map = useMap<string, number>(new Map()); // Map<string, number>

// Type-safe event handlers
useEventListener(window, 'resize', (event) => {
  // event is inferred as UIEvent
  console.log(event.target);
});

Contributions are welcome! Please read our contributing guide to get started.

# Fork and clone the repository
git clone https://github.com/wobyjs/use
cd @woby/use

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

@woby/use/
├── src/
│   ├── index.ssr.tsx      # SSR entry point (29 hooks)
│   ├── index.browser.tsx  # Browser entry point (60+ hooks)
│   ├── useCounter/        # Individual hook folders
│   ├── useLocalStorage/
│   └── ...
├── dist/
│   ├── browser/           # Browser build output
│   │   ├── *.es.js       # ES modules
│   │   ├── *.umd.js      # UMD format
│   │   └── types/        # Type definitions
│   └── ssr/              # SSR build output
│       ├── *.es.js
│       ├── *.cjs.js      # CommonJS
│       └── types/
├── docs/                  # Documentation
├── demo/                  # Example usage
└── test/                  # Test suite

1. Create a new folder in src/ with your hook name
2. Implement the hook with TypeScript
3. Add tests (.test.ts or .spec.ts)
4. Add documentation in docs/hooks/
5. Export from appropriate entry point:
   • SSR-safe → index.ssr.tsx
   • Browser-only → index.browser.tsx
6. Update this README with hook details

• All hooks must have tests
• Use chk testing framework
• Tests run with renderToString for SSR compatibility
• Include both unit tests and integration examples
• Test edge cases and error conditions

• Use TypeScript strict mode
• Follow existing code formatting (Prettier)
• Write JSDoc comments for public APIs
• Keep hooks small and focused (single responsibility)
• Provide clear error messages

MIT

• Voby - A reactive JavaScript framework
• React - A JavaScript library for building user interfaces
• @woby/chk - Testing framework used by @woby/use
• @woby/vite-plugin-test - Vite plugin for testing

• GitHub Issues - Report bugs or request features
• Discussions - Ask questions and share ideas
• Twitter - Follow for updates

Made with ❤️ by the Woby Team | Documentation | Examples