🦖 Hank-Zilla

Global React state with the ergonomics of useState — no Provider, no boilerplate, no dependencies.

Features

• No Provider — read and write the same state from any component
• Familiar — useAppState reads like useState, but global
• Tiny — zero dependencies, ~0.7 KB gzipped
• Correct — built on useSyncExternalStore, concurrent-safe
• Typed — full TypeScript inference

Install

npm install hank-zilla

Quick start

useAppState returns the value and subscribes to it. Write with setAppState from anywhere — no props, no context.

import { useAppState, setAppState } from 'hank-zilla'

function Counter() {
    const count = useAppState('count', 0)
    return <button onClick={() => setAppState('count', (n) => n + 1)}>{count}</button>
}

// Another component, same state — nothing passed down
function Readout() {
    const count = useAppState('count')
    return <p>Count is {count}</p>
}

API

useAppState<T>(key, defaultValue?, removeOnUnmount?, silent?) → T

Subscribe to a key and get its current value. Re-renders only when that key changes.

const count = useAppState('count', 0)
const user = useAppState<User>('user', null)
const temp = useAppState('draft', '', true) // removed from the store on unmount

setAppState(key, value | updater, silent?)

Write a key from anywhere. A plain value replaces; a function is an updater (prev) => next.

setAppState('count', 42) // replace
setAppState('count', (n) => n + 1) // updater
setAppState('user', { name: 'Jane' }) // replaces the whole value
setAppState('user', (u) => ({ ...u, name: 'Jane' })) // merge — via updater
setAppState('items', (list) => [...list, item]) // append — via updater

Each key is independent: writing count never touches user. Pass silent to update without notifying subscribers.

getAppState(key?)

Read without subscribing — no re-render. Handy in callbacks and utilities.

getAppState('count') // one key
getAppState() // the whole store

deleteAppState(key)

Remove a key and re-render its subscribers (they fall back to their default).

$getAppState() — console helper

Exposed on globalThis for debugging in the browser console.

$getAppState() // the whole store
$getAppState('count') // one key

Comparison

| | Hank-Zilla | Context API | Redux | Zustand | | --- | --- | --- | --- | --- | | Provider needed | No | Yes | Yes | No | | Boilerplate | None | Some | High | Low | | Global access | Yes | Provider scope | Yes | Yes | | Bundle (gzip) | ~0.7 KB | built-in | large | ~1 KB | | TypeScript | Full | Manual | Full | Full |

Migration

// Local state
const [count, setCount] = useState(0)
setCount((n) => n + 1)

// Global state
const count = useAppState('count', 0)
setAppState('count', (n) => n + 1)

License

MIT — see LICENSE.

Built by phamdung2209 🦖