Strongly typed read-only object methods
npm install recoil-extSome very small utilities for Recoil including an entity adapter, a dev tool debugger, and indexeddb persistence.
Bundle sizes for different formats:
| Format | Raw Size | Gzipped |
|--------|----------|---------|
| ESM | 3.97 KB | ~1.4 KB |
| CJS | 4.48 KB | ~1.5 KB |
| IIFE | 534 KB | ~145 KB |
You will most likely use ESM, but CJS and IIFE are included for compatibility with older systems / use via public CDNs (e.g.
)
- Recoil Ext
- recoil-ext
- Table of Contents
- Installation
- Features
- Entity Adapter
- IndexedDB Persistence
- Debug Observer
- Usage \& Examples
- Entity Adapter Example
- IndexedDB Persistence Example
- Debug Observer Example
- API Reference
- Entity Adapter
- IndexedDB Effect
- Debug Observer
- Best Practices
- Database Organization
- Data Loading
- Development Tools
- TypeScript Support
- Contributing
- License
- Related Projects



recoil-ext provides utility functions for Recoil state management in React applications. It focuses on normalized data handling, IndexedDB persistence, and state debugging tools.
- Recoil Ext
- recoil-ext
- Table of Contents
- Installation
- Features
- Entity Adapter
- IndexedDB Persistence
- Debug Observer
- Usage \& Examples
- Entity Adapter Example
- IndexedDB Persistence Example
- Debug Observer Example
- API Reference
- Entity Adapter
- IndexedDB Effect
- Debug Observer
- Best Practices
- Database Organization
- Data Loading
- Development Tools
- TypeScript Support
- Contributing
- License
- Related Projects
This package requires recoil and react as peer dependencies.
``bash`
npm install recoil-ext recoil react
Compatible with:
- Recoil ^0.7.0
- React ^17.0.0 || ^18.0.0
Provides normalized storage for collections of data with consistent CRUD operations:
- Stores entities in a normalized format (dictionary by ID)
- Maintains ordered ID list
- TypeScript support for entity types and operations
Syncs atom state with IndexedDB:
- Automatic read on initialization
- Writes on state changes
- Configurable database and store names
- Error handling with fallbacks
Development tool for monitoring Recoil state changes:
- Logs atom/selector updates
- Shows previous and current values
- Development-only by default
`typescript
interface Todo {
id: string;
text: string;
completed: boolean;
}
// Create adapter
const todoAdapter = createEntityAdapter
key: 'todoState',
idKey: 'id'
});
// Use in component
function TodoList() {
const todos = todoAdapter.useAllEntities();
const { addOne, removeOne, updateOne } = todoAdapter.createUseEntityActions()();
return (
$3
`typescript
interface UserSettings {
theme: 'light' | 'dark';
notifications: boolean;
}const settingsAtom = atom({
key: 'settingsAtom',
default: {
theme: 'light',
notifications: true
},
effects: [
idbEffect({
dbName: 'AppDB',
storeName: 'settings',
key: 'userSettings'
})
]
});
function Settings() {
const [settings, setSettings] = useRecoilState(settingsAtom);
return (
Settings
);
}
`$3
`typescript
import { DebugObserver } from 'recoil-ext';function App() {
return (
{process.env.NODE_ENV === 'development' && }
);
}
`API Reference
$3
`typescript
function createEntityAdapter(options: {
key: string; // Recoil atom key (for state)
idKey: K; // Entity ID field
initialState?: T[]; // Optional initial entities
}): {
useAllEntities: () => T[]; createUseEntityActions: () => {
addOne: (entity: T) => void;
addMany: (entities: T[]) => void;
updateOne: (update: { id: T[K]; changes: Partial }) => void;
removeOne: (id: T[K]) => void;
removeMany: (ids: T[K][]) => void;
};
// Additional methods documented in source code
}
`$3
`typescript
function idbEffect(options: {
dbName: string; // Database name
storeName: string; // Object store name
key: string; // Storage key
}): AtomEffect
`Error handling:
- Falls back to atom default if read fails
- Logs errors in development
- Continues operating if persistence fails
$3
Component that logs state changes to console:
`typescript
function DebugObserver(): JSX.Element
`Output format:
`typescript
interface DebugLog {
key: string;
previous: unknown;
current: unknown;
timestamp: number;
}
``Consider these factors when structuring IndexedDB storage:
- Group related data in the same store
- Use separate databases for distinct features
- Plan for version upgrades
- Handle storage limits
Recommendations for server data:
- Load data before storing in adapters
- Handle loading states explicitly
- Consider cache invalidation
- Implement error boundaries
Debug Observer usage:
- Enable only in development
- Use with React DevTools
- Consider performance impact
- Filter noise as needed
Type checking covers:
- Entity shapes and ID fields
- Action parameters
- State updates
- Database operations
Limitations:
- Runtime type information not available
- Some advanced type patterns may require explicit annotations
- Generic constraints follow TypeScript rules
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Update documentation
5. Submit pull request
Development requirements:
- Node.js 16+
- TypeScript 4.5+
- Jest for testing
MIT License
- Recoil - Core state management
- Redux Toolkit - Similar entity patterns
- IDB - IndexedDB utilitie