Recoil Ext

Some 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


recoil-ext provides utility functions for Recoil state management in React applications. It focuses on normalized data handling, IndexedDB persistence, and state debugging tools.

Table of Contents

- 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

Installation

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

Features

$3

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

$3

Syncs atom state with IndexedDB:

- Automatic read on initialization
- Writes on state changes
- Configurable database and store names
- Error handling with fallbacks

$3

Development tool for monitoring Recoil state changes:

- Logs atom/selector updates
- Shows previous and current values
- Development-only by default

Usage & Examples

$3

`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 (



);
}
`

$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;
}
``

Best Practices

$3

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

$3

Recommendations for server data:

- Load data before storing in adapters
- Handle loading states explicitly
- Consider cache invalidation
- Implement error boundaries

$3

Debug Observer usage:

- Enable only in development
- Use with React DevTools
- Consider performance impact
- Filter noise as needed

TypeScript Support

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

Contributing

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

License

MIT License

Related Projects

- Recoil - Core state management
- Redux Toolkit - Similar entity patterns
- IDB - IndexedDB utilitie