Registry /
web-framework / alveron-middleware-persistence
Alveron Middleware Persistence is a specialized middleware designed to integrate a state persistence layer into Alveron applications. Alveron is a lightweight, Elm-inspired state management library for React (approx. 1.2kb) that leverages React's `useState` hook and handles asynchronous side effects. This middleware enables Alveron stores to automatically persist their state to browser storage mechanisms like `localStorage` or `sessionStorage`, ensuring that application data endures across page reloads or browser sessions. The current stable version, 8.0.3, is designed to work seamlessly with Alveron versions greater than 8.0.0. While a specific release cadence for this middleware is not publicly documented, its versioning typically aligns with major releases of the core `alveron` library. Its primary differentiator is its direct compatibility and integration within the Alveron ecosystem, providing a structured approach to state hydration and rehydration tailored for Alveron's model, actions, and effects architecture.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
persistenceMiddleware
✓ import persistenceMiddleware from 'alveron-middleware-persistence';
✗ const persistenceMiddleware = require('alveron-middleware-persistence');
The library primarily uses ESM exports. Use named imports if specific utility functions are also exported.
PersistenceConfig
✓ import persistenceMiddleware, { PersistenceConfig } from 'alveron-middleware-persistence';
Type import for configuring the middleware (if exported, otherwise define inline).
This example demonstrates how to integrate `alveron-middleware-persistence` with an Alveron store to persist and rehydrate a simple counter's state using `localStorage`. It shows the basic setup of an Alveron store with actions and how to apply the configured persistence middleware.
import * as React from 'react';
import { useStoreWithMiddleware, Middleware } from 'alveron';
import persistenceMiddleware from 'alveron-middleware-persistence';
interface Model {
count: number;
lastUpdate: string;
}
interface Actions {
increment: (amount?: number) => Model;
decrement: (amount?: number) => Model;
}
const initialModel: Model = {
count: 0,
lastUpdate: new Date().toISOString(),
};
const actions = {
increment: (amount: number = 1) => (prevState: Model) => [
{ ...prevState, count: prevState.count + amount, lastUpdate: new Date().toISOString() },
],
decrement: (amount: number = 1) => (prevState: Model) => [
{ ...prevState, count: prevState.count - amount, lastUpdate: new Date().toISOString() },
],
};
// Define persistence configuration
const persistenceConfig = {
key: 'my-alveron-app-state', // Unique key for localStorage
storage: localStorage, // or sessionStorage
// Optional: only persist `count`, not `lastUpdate`
partialize: (state: Model) => ({ count: state.count }),
};
const persistedCounterMiddleware: Middleware<Model, Actions> = persistenceMiddleware(persistenceConfig);
function Counter() {
const [state, { increment, decrement }] = useStoreWithMiddleware(
actions,
initialModel,
[persistedCounterMiddleware]
);
return (
<div>
<h1>Count: {state.count}</h1>
<p>Last updated: {new Date(state.lastUpdate).toLocaleTimeString()}</p>
<button onClick={() => increment()}>Increment</button>
<button onClick={() => decrement()}>Decrement</button>
<button onClick={() => localStorage.clear()}>Clear Storage</button>
<p>Refresh the page to see the count persist!</p>
</div>
);
}
function App() {
return (
<React.StrictMode>
<Counter />
</React.StrictMode>
);
}
export default App;
Errors
Common errors & fixes
Uncaught TypeError: Cannot read properties of undefined (reading 'getItem')
Attempting to use the middleware in a Node.js environment (e.g., SSR) where `localStorage` or `sessionStorage` are not defined.
fixWrap your Alveron store initialization with a check for `typeof window !== 'undefined'` or provide `localStorage` / `sessionStorage` polyfills for Node.js environments.
TypeError: (0 , _alveron_middleware_persistence__WEBPACK_IMPORTED_MODULE_1__.default) is not a function
Incorrect CommonJS `require()` usage for an ESM-first package or incorrect named vs default import syntax in an ESM context.
fixFor ESM, use `import persistenceMiddleware from 'alveron-middleware-persistence';`. For CommonJS (if supported), ensure correct interop or use a bundler that handles ESM imports correctly.
Error: Alveron: useStoreWithMiddleware expects the 'alveron' library to be installed. Please ensure it's in your dependencies.
The peer dependency `alveron` is missing or an incompatible version is installed.
fixInstall or upgrade Alveron: `npm install alveron@'>8.0.0'` or `yarn add alveron@'>8.0.0'`.
Audit
Dependencies
alveronrequiredRequired as a peer dependency for Alveron state management functionality.