@preact-signals/safe-react

This is a community-driven preact/signals integration for React, based on official @preact/signals-react integration.

The library differs in a few ways:
- supports SWC-based build systems, like Next.js and @vitejs/plugin-react-swc with a Rust-based plugin
- uses babel/swc plugin to subscribe your components to signals (based on official @preact/signals-react-transform).
- if environment doesn't support babel/swc plugin - exports HOC to subscribe your components to signals

Signals

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

1. 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.
2. 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.

There are two ways of tracking signals:

- automatic - using swc/babel plugin to subscribe your components to signals (based on official @preact/signals-react-transform).
- manual - manual adding tracking to your components with HOC

Table of Contents

- React Integration
- Tracking
- Hooks
- Optimization: Put signal into JSX
- Prop signal unwrapping
- Installation

- automatic
- Next.js
- Vite swc
- Vite babel
- react-native
- Manual (webpack, remix, etc)

- Guide / API
- signal(initialValue)
- signal.peek()
- computed(fn)
- effect(fn)
- batch(fn)
- untracked(fn)
- How it works
- Troubleshooting
- License

SWC plugin compatibility table

| next | @preact-signals/safe-react | @swc/core |
|--------|------------------------------|--------------|
| ^14.0.0 | 0.7.0 | - |
| 15.0.3..15.1.7 | ~0.8.0 | 1.8.0-1.9.2|
| 15.2.0..16.0.0 | ~0.9.0 | 1.11.1 |
| >=16.0.0* | ~0.10.0 | 1.13.21 |

React Integration features

> Note: please open an issue here if in some scenario you have problems with this integration.

$3

The React adapter allows you to access signals directly inside your components and will automatically subscribe to them.

``js
import { signal } from "@preact-signals/safe-react";

const count = signal(0);

function CounterValue() {
// Whenever the count signal is updated, we'll
// re-render this component automatically for you
return

Value: {count.value}

;
}
`

$3

If you need to instantiate new signals inside your components, you can use the useSignal or useComputed hook.

`js
import { useSignal, useComputed } from "@preact-signals/safe-react";

function Counter() {
const count = useSignal(0);
const double = useComputed(() => count.value * 2);

return (
count.value++}>
Value: {count.value}, value x 2 = {double.value}

);
}
`

$3

The React adapter ships with several optimizations it can apply out of the box to minimize virtual-dom diffing. If you pass a signal directly into JSX, it will behave as component which renders value of signal.

`js
import { signal } from "@preact-signals/safe-react";

const count = signal(0);

// Unoptimized: Will trigger the surrounding
// component to re-render
function Counter() {
return

Value: {count.value}

;
}

// Optimized: Will diff only value of signal
function Counter() {
return (

<>Value: {count}

);
}
`

$3

If you pass a signal as a prop to a component, it will automatically unwrap it for you. This means you can pass signals directly to DOM elements and they will be bound to the DOM node.

`js
import { signal } from "@preact-signals/safe-react";

const count = signal(0);

// data-count={count} will be unwrapped and equal to data-count={count.value}
const Counter = () =>

Value: {count.value}

;
`

Comparison table:

| Feature | @preact/signals-react | @preact-signals/safe-react (automatic) | @preact-signals/safe-react (manual) |
| ------------------- | ---------------------------------- | ---------------------------------------- | ------------------------------------- |
| Monkey patch free | ✅ (after 2.0.0 with babel plugin) | ✅ | ✅ |
| Tracking type | automatic | automatic | manual with HOC |
| Hooks | ✅ | ✅ | ✅ |
| Prop unwrapping | ❌ (removed in 2.0.0) | ✅(deprecated) | ❌ |
| Put signal into JSX | ✅ | ✅ | ✅ |



Alterations from @preact/signals-react



Ignoring updates while rendering same component in render. Since this behavior causes double or infinite rerendering in some cases.

`tsx
const A = () => {
const count = signal(0);
count.value++;
return

{count.value}

;
};
`

Installation:

`sh
npm install @preact-signals/safe-react
`

Integrations:

- Automatic
- Next.js
- Vite swc
- Vite babel
- Vite with @preact-signals/utils
- react-native
- Manual (next.js, webpack, etc)

$3

Integration playground

`js
/* @type {import('next').NextConfig} /
const nextConfig = {
experimental: {
swcPlugins: [
[
"@preact-signals/safe-react/swc",
{
// you should use auto mode to track only components which uses .value access.
// Can be useful to avoid tracking of server side components
mode: "auto",
} / plugin options here /,
],
],
},
};

module.exports = nextConfig;
`

$3

Integration playground

`ts
// vite.config.ts
import { defineConfig } from "vite";
import reactSwc from "@vitejs/plugin-react-swc";

// https://vitejs.dev/config/
export default defineConfig({
plugins: [
reactSwc({
plugins: [["@preact-signals/safe-react/swc", {}]],
}),
],
});
`

$3

`ts
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vitejs.dev/config/
export default defineConfig({
plugins: [
react({
babel: {
plugins: ["module:@preact-signals/safe-react/babel"],
},
}),
],
});
`

$3

`ts
// vite.config.ts
import { defineConfig } from "vite";
// can be used with swc plugin, too
import react from "@vitejs/plugin-react";
import { createReactAlias } from "@preact-signals/safe-react/integrations/vite";

// https://vitejs.dev/config/
export default defineConfig({
resolve: {
// add this
alias: [createReactAlias()],
},
plugins: [
react({
// add this
jsxImportSource: "@preact-signals/safe-react/jsx",
babel: {
plugins: ["module:@preact-signals/safe-react/babel"],
},
}),
],
});
`

$3

Allows to transpile components that uses @useSignals in node_modules (For example: @preact-signals/utils)

Integration playground

`ts
// vite.config.ts
import { defineConfig } from "vite";
import reactSwc from "@vitejs/plugin-react-swc";
import { createSWCTransformDepsPlugin } from "@preact-signals/safe-react/integrations/vite";

// https://vitejs.dev/config/
export default defineConfig({
resolve: {
alias: [
// if some lib uses signals it's probably using @preact/signals-react
{
find: "@preact/signals-react",
replacement: "@preact-signals/safe-react",
},
],
},
plugins: [
createSWCTransformDepsPlugin({
filter: (id) => id.includes("node_modules"),
}),
reactSwc({
plugins: [["@preact-signals/safe-react/swc", {}]],
}),
],
});
`

$3

`sh
yarn add -D babel-plugin-module-resolver
`

`js
// babel.config.js
module.exports = {
// or expo-preset or metro-react-native-babel-preset
presets: ["@rnx-kit/babel-preset-metro-react-native"],
plugins: [
[
"module-resolver",
{
alias: [
{
"@preact/signals-react": "@preact-signals/safe-react",
},
],
},
],
"module:@preact-signals/safe-react/babel",
],
};
`

$3

`tsx
import { withTrackSignals } from "@preact-signals/safe-react/manual";

const A = withTrackSignals(() => {
const count = signal(0);
count.value++;
return

{count.value}

;
});
`

$3

#### Automatic integration

Magic contains 2 parts:

- parser plugin. Which transforms your components to subscribe to signals

It will be transformed to:

`tsx
const sig = signal(0);
const A = () =>

{sig.value}

;
`

`tsx
import { useSignals } from "@preact-signals/safe-react/tracking";

const sig = signal(0);
const A = () => {
const store = useSignals();
try {
// all signals used in this function will be tracked
return

{sig.value}

;
} finally {
effectStore[EffectStoreFields.finishTracking]();
}
};
`

- (Deprecated) jsx runtime. Which unwraps signals while it passed as props to elements

`tsx
const sig = signal(0);

// data-a={sig} will be unwrapped and equal to data-a={sig.value}
const A = () =>

{sig.value}

;
`

#### How parser plugins works

Supported parsers:

- swc
- babel

Parser plugin transforms your components to subscribe to signals. It works in 3 modes:

- all (default)

- Components: will be wrapped with try/finally block to track signals
- Hooks (if transformHooks: true): all hooks that accesses .value will be wrapped with try/finally block to track signals

- auto

- Components: components which contains .value access will be wrapped with try/finally block to track signals
- Hooks (if transformHooks true) that which contains .value access will be wrapped with try/finally block to track signals

- manual - none of hooks or components are tracked by default. You can use @useSignals comment to track signals

`ts
// @useSignals
const Component = () =>