@necolo/react-state NPM

@necolo/react-state

A lightweight React state manager built on React Hooks. This simple yet powerful library allows you to share state across multiple React components without complex setup or configuration.

npm License

Features

Lightweight with zero dependencies (besides React)
Hook-based API that integrates naturally with React
Simple model creation with intuitive patterns
Cross-component state sharing without prop drilling
TypeScript support with full type definitions
Memoization support to optimize re-renders
Multiple model management without provider nesting

Installation

npm install @necolo/react-state

Basic Usage

Creating and using a shared state model is simple:

import React, { useState } from 'react';
import { Provider, createModel } from '@necolo/react-state';

// 1. Create your model
const CounterModel = createModel(function() {
  const [value, setValue] = useState(1);
  
  function increase() {
    setValue(value + 1);
  }
  
  return {
    value,
    increase,
  };
});

// 2. Register model at the root component
function App() {
  return (
    <Provider model={CounterModel}>
      <SubPage />
    </Provider>
  );
}

// 3. Use model in any child component
function SubPage() {
  // Access the model with the .use() method
  const counter = CounterModel.use();
  
  return (
    <div>
      <p>Count: {counter.value}</p>
      <button onClick={counter.increase}>Increase</button>
    </div>
  );
}

Advanced Usage

Models with Initial Values

You can create models that accept initial values:

import React, { useState } from 'react';
import { Provider, createModel } from '@necolo/react-state';

const CounterModel = createModel(function(initialValue) {
  const [value, setValue] = useState(initialValue);
  
  function increase() {
    setValue(value + 1);
  }
  
  return {
    value,
    increase,
  };
});

function App() {
  // Pass initial value via the args prop
  return (
    <Provider model={CounterModel} args={10}>
      <SubPage />
    </Provider>
  );
}

Managing Multiple Models

Instead of nesting multiple Provider components, use Providers:

import React from 'react';
import { Providers } from '@necolo/react-state';

function App() {
  return (
    <Providers 
      models={[
        { model: CounterModel },
        { model: UserModel, args: { username: 'guest' } },
        { model: ThemeModel, args: 'light', memo: true },
      ]}
    >
      <YourApp />
    </Providers>
  );
}

This is equivalent to writing:

function App() {
  return (
    <Provider model={CounterModel}>
      <Provider model={UserModel} args={{ username: 'guest' }}>
        <Provider model={ThemeModel} args="light" memo>
          <YourApp />
        </Provider>
      </Provider>
    </Provider>
  );
}

Optimizing with Memoization

Use the memo flag to prevent unnecessary re-renders:

<Provider model={CounterModel} memo>
  <YourApp />
</Provider>

Selective Re-renders with Dependencies

You can optimize renders by specifying dependencies:

function ProfilePage() {
  // Only re-render when user.name changes
  const user = UserModel.use(user => [user.name]);
  
  return <div>Hello, {user.name}</div>;
}

API Reference

`createModel(modelFunction)`

Creates a model with a .use() method for accessing it in components.

`Provider` Component

Props:

model: The model to provide
args (optional): Initial arguments to pass to model
memo (optional): Whether to memoize the model to prevent unnecessary re-renders
modelRef (optional): Ref to access the model instance outside React's lifecycle

`Providers` Component

Props:

models: Array of model configurations with { model, args, memo }

`useModel(model, deps?)`

Hook to use a model directly (the .use() method uses this internally).

`Consumer` Component

Props:

model: The model to consume
deps (optional): Selector function for optimizing re-renders
children: Function that receives the model state

TypeScript Support

This library is written in TypeScript and provides full type definitions:

import { createModel, Provider } from '@necolo/react-state';

interface User {
  name: string;
  age: number;
}

// Properly typed model with TypeScript
const UserModel = createModel(function(initialUser: User) {
  const [user, setUser] = useState<User>(initialUser);
  
  function updateName(name: string) {
    setUser({ ...user, name });
  }
  
  return {
    user,
    updateName
  };
});

// TypeScript will ensure you pass the correct arguments
<Provider model={UserModel} args={{ name: "John", age: 30 }}>
  <App />
</Provider>