pretty-good-state

A just-enough state management library for React. Built on top of valtio.

``bash
npm install pretty-good-state
`

✅ Fine-grained reactivity

✅ Simple and intuitive mutations

✅ Unified API for local, global, and context state

✅ Full TypeScript support

Usage

$3

Use the defineState() function to create reusable state:

`tsx
import { defineState } from "pretty-good-state";

const CounterState = defineState({
count: 0,
});
`

You can also define methods on the state that directly mutate it:

`tsx
const CounterState = defineState({
count: 0,
increment(amount = 1) {
// this is bound to the state
this.count += amount;
},
});
`

$3

Use useLocalState() to initialize component-local state:

`tsx
import { useLocalState } from "pretty-good-state";

function Counter() {
const counter = useLocalState(CounterState);

return (


`tsx
const counter = useLocalState(CounterState, (state) => {
state.count = 10;
});
`

$3

Use useProvidedState() with a Provider to share state for a portion
of your React tree:

`tsx
import { useProvidedState } from "pretty-good-state";

function Counter() {
const counter = useProvidedState(CounterState);

return (


function Page() {
return (

{/ The following counters will share the same state /}



);
}
`

You can also call useProvidedState() without a Provider, in which case it will
use a shared global state.

If you pass a state object to the Provider, it will use that state object
instead of creating a new one. This is useful when you want to access the state
in the same component that renders the Provider:

`tsx
import { useLocalState } from "pretty-good-state";

function Page() {
const counter = useLocalState(CounterState);

return (


counter.increment(10)}>Increment 10

);
}
`

$3

In addition to defining state methods, you can also directly modify the state in
components:

`tsx
import { useLocalState } from "pretty-good-state";

const counter = useLocalState(CounterState);

(counter.count = 0)}>Reset;
`

The library detects mutations and re-renders the components that depend on those
exact changes.

$3

You can directly pass state to child components:

`tsx
import { defineState, useLocalState } from "pretty-good-state";

const TodoListState = defineState({
items: [] as Todo[],
});

type Todo = {
id: string;
text: string;
done: boolean;
};

function TodoList() {
const todoList = useLocalState(TodoListState);
return (


However, note that the hook useLocalState() is in the parent component,
and as a result the parent is tracking changes to all state properties accessed
in the child. The parent re-renders unnecessarily when, for example, todo.done
is toggled.

To optimize this, we can use the usePassedState() hook to allow the child
component to track its own state:

`tsx
import { usePassedState } from "pretty-good-state";

function TodoItem({ todo: _todo }: { todo: Todo }) {
const todo = usePassedState(_todo);
return (


Notice how we rename todo to _todo as we destructure the component props.
This helps to avoid accidental reads from the parent's copy of the state.

$3

The globalStore object lets you access global state outside of a component:

`tsx
import { globalStore } from "pretty-good-state";

const counter = globalStore.getState(CounterState);
counter.increment();
`

$3

There may be cases where you want to have access to hooks from within a state.
The runInComponent() function lets you do this.

`tsx
import { defineState, runInComponent } from "pretty-good-state";

const EmailFormState = defineState({
getIntl: runInComponent(() => {
return useIntl();
}),
email: "",
errorMessage: "",
validate() {
if (!this.email) {
this.errorMessage = this.getIntl().format("Email is required");
return false;
}
this.errorMessage = "";
return true;
},
});
`

These runInComponent() functions are called in the component where the local
state is created – i.e. when useLocalState() is called or when a Provider is
rendered.

Note that since runInComponent() requires a component context, it cannot be
used in global state (i.e.
globalStore.getState(EmailFormState).validate() will throw an error).

$3

You can infer the types of the state from its constructor:

`tsx
import { defineState, Infer } from "pretty-good-state";

const CounterState = defineState({
count: 0,
});

type CounterShape = Infer; // { count: number }
``