-
-
Notifications
You must be signed in to change notification settings - Fork 90
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add package @preact/signals-react-transform
#375
Changes from 35 commits
cb1b618
476b216
b0d846f
76014fa
e8c583d
594593a
528f190
f7863bc
df40e32
4ad28ab
c46c7cd
eb838c4
15e83de
73fb6f4
c705084
b2f8b9d
73da9dc
be03ccf
ff17284
e4a8ce8
b0bcd75
74696f3
6802bfc
372671a
58b3a25
2e6e4ae
959a83f
67d6099
d5527a6
fe7f7f2
a76706b
ed01656
a122e59
50bc4ee
1ace900
dd070c9
1bab05b
59115d9
cd3a22d
b90a938
f01b413
033224a
1099b7b
255208a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,3 @@ | ||
declare const expect: Chai.ExpectStatic; | ||
declare const sinon: import("sinon").SinonStatic; | ||
declare const transformSignalCode: (code: string, options?: import("@preact/signals-react-transform").PluginOptions) => string; |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,119 @@ | ||
# Signals React Transform | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unsure what's the right level of detail here. Would love other's thoughts. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it's perfectly fine. We could theoretically shorten the intro paragraph about what signals are by just pointing to the blog post. But then again that I think leaving as is, is fine too. |
||
|
||
> A Babel plugin to transform React components to automatically subscribe to Preact 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](https://preactjs.com/blog/introducing-signals/) to learn more about which problems signals solves and how it came to be. | ||
|
||
## Installation: | ||
|
||
```sh | ||
npm install @preact/signals-react-transform | ||
``` | ||
|
||
## Usage | ||
|
||
This package works with the `@preact/signals-react` package to integrate signals into React. You use the `@preact/signals-react` package to setup and access signals inside your components and this package is one way to automatically subscribe your components to rerender when the signals you use change. | ||
|
||
To understand how to use signals in your components, check out the [Signals React documentation](../react/README.md). This babel transform is one of a couple different ways to use signals in React. To see other ways, including integrations that don't require a build step, see the [Signals React documentation](../react/README.md). | ||
|
||
Then, setup the transform plugin in your Babel config: | ||
|
||
```js | ||
// babel.config.js | ||
module.exports = { | ||
plugins: [["@preact/signals-react-transform"]], | ||
}; | ||
``` | ||
|
||
Here is an example of a component using signals: | ||
|
||
```js | ||
import { signal } from "@preact/signals-react"; | ||
|
||
const count = signal(0); | ||
|
||
function CounterValue() { | ||
// Whenever the `count` signal is updated, we'll | ||
// re-render this component automatically for you | ||
return <p>Value: {count.value}</p>; | ||
} | ||
``` | ||
|
||
After the babel transform runs, it'll look something like: | ||
|
||
```js | ||
import { signal, useSignals } from "@preact/signals-react"; | ||
|
||
const count = signal(0); | ||
|
||
function CounterValue() { | ||
const endTracking = useSignals(); | ||
try { | ||
// Whenever the `count` signal is updated, we'll | ||
// re-render this component automatically for you | ||
return <p>Value: {count.value}</p>; | ||
} finally { | ||
endTracking(); | ||
} | ||
} | ||
``` | ||
|
||
The `useSignals` hook setups the machinery to observe what signals are used inside the component and then automatically re-render the component when those signals change. The `endTracking` function notifies the tracking mechanism that this component has finished rendering. When your component unmounts, it also unsubscribes from all signals it was using. | ||
|
||
Fundamentally, this Babel transform needs to answer two questions in order to know whether to transform a function: | ||
|
||
1. Is a function a component? | ||
2. If so, does this component use signals? | ||
|
||
Currently we use the following heuristics to answer these questions: | ||
|
||
1. A function is a component if it has a capitalized name (e.g. `function MyComponent() {}`) and contains JSX. | ||
2. If a function's body includes a member expression referencing `.value` (i.e. `something.value`), we assume it's a signal. | ||
|
||
If your function/component meets these criteria, this plugin will transform it. If not, it will be left alone. If you have a function that uses signals but does not meet these criteria (e.g. a function that manually calls `createElement` instead of using JSX), you can add a comment with the string `@trackSignals` to instruct this plugin to transform this function. You can also manually opt-out of transforming a function by adding a comment with the string `@noTrackSignals`. | ||
|
||
```js | ||
// This function will be transformed | ||
/** @trackSignals */ | ||
function MyComponent() { | ||
return createElement("h1", null, signal.value); | ||
} | ||
|
||
// This function will not be transformed | ||
/** @noTrackSignals */ | ||
function MyComponent() { | ||
return <p>{signal.value}</p>; | ||
} | ||
``` | ||
|
||
## Plugin Options | ||
|
||
### `mode` | ||
|
||
The `mode` option enables you to control how the plugin transforms your code. There are two modes: | ||
|
||
- `mode: "auto"` (default): This mode will automatically transform any function that meets the criteria described above. This is the easiest way to get started with signals. | ||
- `mode: "manual"`: This mode will only transform functions that have a comment with the string `@trackSignals`. This is useful if you want to manually control which functions are transformed. | ||
|
||
```js | ||
// babel.config.js | ||
module.exports = { | ||
plugins: [ | ||
[ | ||
"@preact/signals-react-transform", | ||
{ | ||
mode: "manual", | ||
}, | ||
], | ||
], | ||
}; | ||
``` | ||
|
||
## License | ||
|
||
`MIT`, see the [LICENSE](../../LICENSE) file. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
{ | ||
"name": "@preact/signals-react-transform", | ||
"version": "0.0.1-alpha.0", | ||
"license": "MIT", | ||
"description": "Manage state with style in React", | ||
"keywords": [], | ||
"authors": [ | ||
"The Preact Authors (https://github.com/preactjs/signals/contributors)" | ||
], | ||
"repository": { | ||
"type": "git", | ||
"url": "https://github.com/preactjs/signals", | ||
"directory": "packages/react" | ||
}, | ||
"bugs": "https://github.com/preactjs/signals/issues", | ||
"homepage": "https://preactjs.com", | ||
"funding": { | ||
"type": "opencollective", | ||
"url": "https://opencollective.com/preact" | ||
}, | ||
"main": "dist/signals-transform.js", | ||
"module": "dist/signals-transform.module.js", | ||
"types": "dist/signals-transform.d.ts", | ||
"source": "src/index.ts", | ||
"exports": { | ||
".": { | ||
"types": "./dist/signals-transform.d.ts", | ||
"import": "./dist/signals-transform.mjs", | ||
"require": "./dist/signals-transform.js" | ||
} | ||
}, | ||
"mangle": "../../mangle.json", | ||
"scripts": { | ||
"prepublishOnly": "cd ../.. && pnpm build:react-transform" | ||
}, | ||
"dependencies": { | ||
"@babel/helper-module-imports": "^7.22.5", | ||
"@babel/helper-plugin-utils": "^7.22.5", | ||
"@preact/signals-react": "workspace:^1.3.2", | ||
"use-sync-external-store": "^1.2.0" | ||
}, | ||
"peerDependencies": { | ||
"@babel/core": "^7.22.8", | ||
"react": "^16.14.0 || 17.x || 18.x" | ||
}, | ||
"devDependencies": { | ||
"@babel/core": "^7.22.8", | ||
"@types/babel__core": "^7.20.1", | ||
"@types/babel__helper-module-imports": "^7.18.0", | ||
"@types/babel__helper-plugin-utils": "^7.10.0", | ||
"@types/react": "^18.0.18", | ||
"@types/react-dom": "^18.0.6", | ||
"@types/use-sync-external-store": "^0.0.3", | ||
"assert": "^2.0.0", | ||
"buffer": "^6.0.3", | ||
"path": "^0.12.7", | ||
"react": "^18.2.0", | ||
"react-dom": "^18.2.0", | ||
"react-router-dom": "^6.9.0" | ||
} | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Whoops - will undo this. Did this to not downlevel async/await while debugging tests