-
-
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
Merged
Merged
Changes from all commits
Commits
Show all changes
44 commits
Select commit
Hold shift + click to select a range
cb1b618
Add hello world babel plugin
andrewiggins 476b216
Fix browser tests to only run browser and shared test files
andrewiggins b0d846f
Lazily add import statement and add hook to template
andrewiggins 76014fa
Detect value member expressions and only transform functions with may…
andrewiggins e8c583d
Use replaceWith to change function body
andrewiggins 594593a
Improve types and clean up comments
andrewiggins 528f190
Add manual mode support using `@trackSignals` comment
andrewiggins f7863bc
Add support for function expressions
andrewiggins df40e32
Add notes for future work
andrewiggins 4ad28ab
Add ability to opt-out of transform using comment
andrewiggins c46c7cd
Fix: Add missing exports declaration for runtime package
andrewiggins eb838c4
Have useSignals clear the current updater after a microtick
andrewiggins 15e83de
Add tests for calling useSignals directly
andrewiggins 73fb6f4
Move try/finally wrapping logic into a function
andrewiggins c705084
Add option to not use try/finally to wrap stop tracking signals
andrewiggins b2f8b9d
Update comments
andrewiggins 73da9dc
Use regex to match opt-in/opt-out comments
andrewiggins be03ccf
Update component detection logic to include JSX and top-level functio…
andrewiggins ff17284
Share implementation of function-like visitors
andrewiggins e4a8ce8
Initial write of react-transform readme
andrewiggins b0bcd75
Merge branch 'main' into react-babel-plugin
andrewiggins 74696f3
Add missing build scripts to package.json
andrewiggins 6802bfc
Add support for transforming custom hooks
andrewiggins 372671a
Setup react-transform E2E test infra
andrewiggins 58b3a25
Update E2E test infra
andrewiggins 2e6e4ae
Use testRequire for jsx in tests
andrewiggins 959a83f
WIP: Add test for multi-hooks in component
andrewiggins 67d6099
Align babel versions to fix tsc errors
andrewiggins d5527a6
Manually track if the babel transform is used to end signal tracking …
andrewiggins fe7f7f2
Simplify render tracking by never stopping signal tracking in a custo…
andrewiggins a76706b
Re-organize transform file a bit
andrewiggins ed01656
Fix test:prod tests
andrewiggins a122e59
Merge branch 'main' into react-babel-plugin
andrewiggins 50bc4ee
Reorganize tests
andrewiggins 1ace900
Add importSource plugin option
andrewiggins dd070c9
Add support for using `using`
andrewiggins 1bab05b
Add note about higher order components
andrewiggins 59115d9
Add changesets
andrewiggins cd3a22d
Cleanup effect store reference after using it
andrewiggins b90a938
Add test for not transforming hook callbacks
andrewiggins f01b413
Add support for trackSignals comments on object properties that are f…
andrewiggins 033224a
Add support for trackSignals comments on object property assignment
andrewiggins 1099b7b
Merge branch 'main' into react-babel-plugin
andrewiggins 255208a
Final PR tweaks
andrewiggins File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
"@preact/signals-react": patch | ||
--- | ||
|
||
Clean up effect store reference after finishing it |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
"@preact/signals-react": patch | ||
--- | ||
|
||
Update internal useSignals API |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
"@preact/signals-react-transform": patch | ||
--- | ||
|
||
Initial alpha release |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,121 @@ | ||
# Signals React Transform | ||
|
||
> 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 effect = useSignals(); | ||
try { | ||
// Whenever the `count` signal is updated, we'll | ||
// re-render this component automatically for you | ||
return <p>Value: {count.value}</p>; | ||
} finally { | ||
effect.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() {}`), contains JSX, and is declared at module scope. | ||
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>; | ||
} | ||
``` | ||
|
||
Note, this plugin will not transform higher-order components (HOCs) that wrap other components. If you have an HOC that uses signals, you can use the `@trackSignals` comment to transform the body of the higher-order component. | ||
|
||
## 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
{ | ||
"name": "@preact/signals-react-transform", | ||
"version": "0.0.1-alpha.0", | ||
"license": "MIT", | ||
"description": "Manage state with style in React", | ||
"keywords": [ | ||
"babel", | ||
"signals", | ||
"react" | ||
], | ||
"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" | ||
} | ||
} |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
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 comment
The 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.