Reusable primitives for
reatom state management
A jsrepo registry of 12 drop-in extensions, factories, and utilities. Copy-paste the pieces you need — no extra packages.
npx jsrepo init github/reatom/reusables Extensions
Focuses the first field with a validation error after a failed submit.
Auto-submits a Reatom form after the user stops changing fields for a short time.
Adds a `handleSubmit` action to a form for event-driven submission with an optional dirty-guard.
Warns the user before leaving the page when the form has unsaved changes, using the browser's `beforeunload` event.
Atom extension that tracks state history with configurable length.
Atom extension that adds a lifecycle-managed `.instance` property derived from the atom's value.
Atom/action extension that logs all state changes and action calls.
Atom extension that adds a `.reset()` action to restore the atom to its initial value.
Utilities
FAQ
How reusables work
Quick answers about the reusables pattern, jsrepo, and where new ideas belong.
What is the reusables pattern?
Instead of installing a package, you copy the source code directly into your project. This is the same "open code" approach pioneered by shadcn/ui: you own every line, so you can read, modify, and extend it without fighting a library's API. No version lock-in, no wrapping third-party components — just code that lives in your repo and evolves with your project.
What is jsrepo?
jsrepo is a CLI that automates copy-paste code distribution. It lets you browse a registry, pick specific items, and drop them into your project — with support for updates and diffs when the upstream changes. Think of it as the plumbing behind the reusables pattern.
Do I have to use jsrepo?
No. Every reusable is a plain TypeScript file you can copy by hand. jsrepo just makes discovery, adding, and updating easier with a single command. Use it if you want convenience; skip it if you prefer to vendor files yourself.
How do I test Reatom code?
Add the test harness utility with npx jsrepo add test. It provides automatic Reatom context management and mock
subscription utilities for Vitest tests.
The test harness is also automatically included when you add any
reusable with the --with-tests flag:
npx jsrepo add withHistory --with-tests
Can I include tests, docs, and examples?
Yes. Use flags to include additional files when adding a reusable:
- --with-tests — includes test files and the test harness utility
- --with-docs — includes documentation files (like detailed API docs)
- --with-examples — includes example usage files when available
Combine multiple flags: npx jsrepo add withLogger --with-tests --with-docs
What makes a good reusable?
A focused pattern that is useful out of the box but small enough to understand and modify. Good reusables have a clear single purpose, readable code, and minimal assumptions about how they'll be used. Third-party dependencies are fine when they're the point of the integration (like a Tweakpane binding). The key test: would a developer benefit from owning and tweaking this code rather than importing it as a fixed dependency?
Core package, separate library, or reusable?
Reatom distributes code three ways, each for a different kind of thing:
- Core (
@reatom/core) — stable, dependency-free primitives with broad applicability. Changes here affect everyone, so the bar is high. - Separate library (e.g.
@reatom/zod) — a complete, cohesive integration with a stable upstream API where the surface is large enough to justify a dedicated package. - Reusable — smaller or opinionated pieces where users benefit from owning the code: partial integrations, niche patterns, or cases where upstream APIs shift often and you'd rather adapt locally.
Can I contribute a reusable?
Yes — open a PR. If the idea is opinionated or niche, that's perfectly fine: we'll either generalize it together or ship it as-is. Reusables are meant to be adapted by users, so a useful starting point matters more than universal consensus.