@preact/signals-core

What is @preact/signals-core?

@preact/signals-core is a state management library designed for Preact applications. It provides reactive signals that can be used to manage and update state efficiently. The package is lightweight and focuses on providing a simple API for state management.

What are @preact/signals-core's main functionalities?

Creating Signals

Signals are reactive state containers. You can create a signal with an initial value and update it. The value of the signal can be accessed and modified using the `.value` property.

const { signal } = require('@preact/signals-core');
const count = signal(0);
console.log(count.value); // 0
count.value = 1;
console.log(count.value); // 1

Computed Values

Computed values are derived from other signals. They automatically update when the signals they depend on change.

const { signal, computed } = require('@preact/signals-core');
const count = signal(0);
const doubleCount = computed(() => count.value * 2);
console.log(doubleCount.value); // 0
count.value = 2;
console.log(doubleCount.value); // 4

Effects

Effects are functions that run whenever the signals they depend on change. They are useful for performing side effects in response to state changes.

const { signal, effect } = require('@preact/signals-core');
const count = signal(0);
effect(() => {
  console.log(`Count is now ${count.value}`);
});
count.value = 1; // Logs: Count is now 1

Other packages similar to @preact/signals-core

mobx

MobX is a state management library that makes it simple to connect the reactive data of your application with the UI. It provides observables, computed values, and reactions, similar to signals, computed values, and effects in @preact/signals-core. However, MobX is more feature-rich and can be used with various frameworks, not just Preact.

valtio

Valtio is a proxy-state library that captures the state and makes it reactive. It provides a simple API for creating reactive state and is framework-agnostic. Valtio's approach is similar to @preact/signals-core but uses JavaScript proxies to track state changes.

zustand

Zustand is a small, fast, and scalable state management solution. It provides a simple API for creating and managing state, with a focus on simplicity and performance. While it does not use signals, it offers a similar level of simplicity and ease of use for state management.

README

Signals

Signals is a performant state management library with two primary goals:

• Make it as easy as possible to write business logic for small up to complex apps. No matter how complex your logic is, your app updates should stay fast without you needing to think about it. Signals automatically optimize state updates behind the scenes to trigger the fewest updates necessary. They are lazy by default and automatically skip signals that no one listens to.
• Integrate into frameworks as if they were native built-in primitives. You don't need any selectors, wrapper functions, or anything else. Signals can be accessed directly and your component will automatically re-render when the signal's value changes.

Read the announcement post to learn more about which problems signals solves and how it came to be.

Installation:

# Just the core library
npm install @preact/signals-core
# If you're using Preact
npm install @preact/signals
# If you're using React
npm install @preact/signals-react
# If you're using Svelte
npm install @preact/signals-core

• Signals
  • Installation:
  • Guide / API
    • signal(initialValue)
      • signal.peek()
    • computed(fn)
    • effect(fn)
    • batch(fn)
    • untracked(fn)
  • License

Guide / API

The signals library exposes four functions which are the building blocks to model any business logic you can think of.

signal(initialValue)

The signal function creates a new signal. A signal is a container for a value that can change over time. You can read a signal's value or subscribe to value updates by accessing its .value property.

import { signal } from "@preact/signals-core";

const counter = signal(0);

// Read value from signal, logs: 0
console.log(counter.value);

// Write to a signal
counter.value = 1;

Writing to a signal is done by setting its .value property. Changing a signal's value synchronously updates every computed and effect that depends on that signal, ensuring your app state is always consistent.

You can also pass options to signal() and computed() to be notified when the signal gains its first subscriber and loses its last subscriber:

const counter = signal(0, {
	watched: function () {
		console.log("Signal has its first subscriber");
	},
	unwatched: function () {
		console.log("Signal lost its last subscriber");
	},
});

These callbacks are useful for managing resources or side effects that should only be active when the signal has subscribers. For example, you might use them to start/stop expensive background operations or subscribe/unsubscribe from external event sources.

signal.peek()

In the rare instance that you have an effect that should write to another signal based on the previous value, but you don't want the effect to be subscribed to that signal, you can read a signals's previous value via signal.peek().

const counter = signal(0);
const effectCount = signal(0);

effect(() => {
	console.log(counter.value);

	// Whenever this effect is triggered, increase `effectCount`.
	// But we don't want this signal to react to `effectCount`
	effectCount.value = effectCount.peek() + 1;
});

Note that you should only use signal.peek() if you really need it. Reading a signal's value via signal.value is the preferred way in most scenarios.

computed(fn)

Data is often derived from other pieces of existing data. The computed function lets you combine the values of multiple signals into a new signal that can be reacted to, or even used by additional computeds. When the signals accessed from within a computed callback change, the computed callback is re-executed and its new return value becomes the computed signal's value.

import { signal, computed } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");

const fullName = computed(() => name.value + " " + surname.value);

// Logs: "Jane Doe"
console.log(fullName.value);

// Updates flow through computed, but only if someone
// subscribes to it. More on that later.
name.value = "John";
// Logs: "John Doe"
console.log(fullName.value);

Any signal that is accessed inside the computed's callback function will be automatically subscribed to and tracked as a dependency of the computed signal.

effect(fn)

The effect function is the last piece that makes everything reactive. When you access a signal inside its callback function, that signal and every dependency of said signal will be activated and subscribed to. In that regard it is very similar to computed(fn). By default all updates are lazy, so nothing will update until you access a signal inside effect.

import { signal, computed, effect } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => name.value + " " + surname.value);

// Logs: "Jane Doe"
effect(() => console.log(fullName.value));

// Updating one of its dependencies will automatically trigger
// the effect above, and will print "John Doe" to the console.
name.value = "John";

You can destroy an effect and unsubscribe from all signals it was subscribed to, by calling the returned function.

import { signal, computed, effect } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => name.value + " " + surname.value);

// Logs: "Jane Doe"
const dispose = effect(() => console.log(fullName.value));

// Destroy effect and subscriptions
dispose();

// Update does nothing, because no one is subscribed anymore.
// Even the computed `fullName` signal won't change, because it knows
// that no one listens to it.
surname.value = "Doe 2";

The effect callback may return a cleanup function. The cleanup function gets run once, either when the effect callback is next called or when the effect gets disposed, whichever happens first.

import { signal, effect } from "@preact/signals-core";

const count = signal(0);

const dispose = effect(() => {
	const c = count.value;
	return () => console.log(`cleanup ${c}`);
});

// Logs: cleanup 0
count.value = 1;

// Logs: cleanup 1
dispose();

batch(fn)

The batch function allows you to combine multiple signal writes into one single update that is triggered at the end when the callback completes.

import { signal, computed, effect, batch } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => name.value + " " + surname.value);

// Logs: "Jane Doe"
effect(() => console.log(fullName.value));

// Combines both signal writes into one update. Once the callback
// returns the `effect` will trigger and we'll log "Foo Bar"
batch(() => {
	name.value = "Foo";
	surname.value = "Bar";
});

When you access a signal that you wrote to earlier inside the callback, or access a computed signal that was invalidated by another signal, we'll only update the necessary dependencies to get the current value for the signal you read from. All other invalidated signals will update at the end of the callback function.

import { signal, computed, effect, batch } from "@preact/signals-core";

const counter = signal(0);
const double = computed(() => counter.value * 2);
const triple = computed(() => counter.value * 3);

effect(() => console.log(double.value, triple.value));

batch(() => {
	counter.value = 1;
	// Logs: 2, despite being inside batch, but `triple`
	// will only update once the callback is complete
	console.log(double.value);
});
// Now we reached the end of the batch and call the effect

Batches can be nested and updates will be flushed when the outermost batch call completes.

import { signal, computed, effect, batch } from "@preact/signals-core";

const counter = signal(0);
effect(() => console.log(counter.value));

batch(() => {
	batch(() => {
		// Signal is invalidated, but update is not flushed because
		// we're still inside another batch
		counter.value = 1;
	});

	// Still not updated...
});
// Now the callback completed and we'll trigger the effect.

untracked(fn)

In case when you're receiving a callback that can read some signals, but you don't want to subscribe to them, you can use untracked to prevent any subscriptions from happening.

const counter = signal(0);
const effectCount = signal(0);
const fn = () => effectCount.value + 1;

effect(() => {
	console.log(counter.value);

	// Whenever this effect is triggered, run `fn` that gives new value
	effectCount.value = untracked(fn);
});

License

MIT, see the LICENSE file.