Add package `@preact/signals-react-transform` #375

andrewiggins · 2023-06-23T22:28:16Z

This PR adds a new package @preact/signals-react-transform that provides a Babel plugin to transform functions to observer/track what signals are used when the function runs. This plugin is the start to an alternate React integration for signals that does not hook into React internals. Once our approach here is finalized and published, I'll update the @preact/signals-react package to reference this and provide various options for using signals in React.

Check the test file for examples of what the transformation looks like.

I'm currently exploring two different kinds of transformations in this implementation to see which one works better. One just adds a call to useSignals() to the top of the component and relies on the next invocation of useSignals or a microtick to stop tracking signals. The other wraps the component body in a try/finally to start and stop tracking signals. I'm currently leaning towards making the try/finally the default cuz it leaves less room for tricky edge cases that may lead to non-obvious behavior and rerenders.

However, the implementation of useSignals is the same either way. We'll always setup the microtick to clean up any outstanding effects to prevent any loose ends regardless of which transformation is used. So users can manually drop useSignals into a component and get basic functionality.

…be signal access

…n requirements

changeset-bot · 2023-06-23T22:28:19Z

🦋 Changeset detected

Latest commit: 255208a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@preact/signals-react	Patch
@preact/signals-react-transform	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2023-06-23T22:28:26Z

✅ Deploy Preview for preact-signals-demo ready!

Name	Link
🔨 Latest commit	`255208a`
🔍 Latest deploy log	https://app.netlify.com/sites/preact-signals-demo/deploys/64cad3e1ec66ea00087a05d6
😎 Deploy Preview	https://deploy-preview-375--preact-signals-demo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2023-06-23T22:29:57Z

Size Change: +267 B (0%)

Total Size: 78 kB

Filename	Size	Change
`docs/dist/assets/client.********.js`	46.7 kB	+95 B (0%)
`docs/dist/react-********.js`	238 B	-1 B (0%)
`packages/react/dist/signals.js`	1.35 kB	+89 B (+7%)	🔍
`packages/react/dist/signals.mjs`	1.29 kB	+84 B (+7%)	🔍

ℹ️ View Unchanged

Filename	Size
`docs/dist/assets/index.********.js`	835 B
`docs/dist/assets/jsxRuntime.module.********.js`	281 B
`docs/dist/assets/preact.module.********.js`	4.02 kB
`docs/dist/assets/signals-core.module.********.js`	1.43 kB
`docs/dist/assets/signals.module.********.js`	2.02 kB
`docs/dist/assets/style.********.js`	21 B
`docs/dist/assets/style.********.css`	1.21 kB
`docs/dist/basic-********.js`	244 B
`docs/dist/demos-********.js`	3.35 kB
`docs/dist/nesting-********.js`	1.13 kB
`packages/core/dist/signals-core.js`	1.5 kB
`packages/core/dist/signals-core.mjs`	1.53 kB
`packages/preact/dist/signals.js`	1.27 kB
`packages/preact/dist/signals.mjs`	1.22 kB
`packages/react-transform/dist/signals-*********.js`	2.79 kB
`packages/react-transform/dist/signals-transform.mjs`	2.66 kB
`packages/react-transform/dist/signals-transform.umd.js`	2.91 kB

_{compressed-size-action}

andrewiggins · 2023-06-23T22:29:08Z

karma.conf.js

@@ -283,7 +287,7 @@ module.exports = function (config) {
 			jsx: "preserve",

 			// esbuild options
-			target: downlevel ? "es5" : "es2015",
+			target: downlevel ? "es5" : "es2019",


Whoops - will undo this. Did this to not downlevel async/await while debugging tests

andrewiggins · 2023-06-23T22:29:33Z

packages/react-transform/README.md

@@ -0,0 +1,119 @@
+# Signals React Transform


Unsure what's the right level of detail here. Would love other's thoughts.

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.

andrewiggins · 2023-06-23T22:30:35Z

packages/react-transform/src/index.ts

+// TODO:
+// - how to trigger rerenders on attributes change if transform never sees
+//   `.value`?


I still need to build the signal attribute handling in our jsx handler

Will do this in a follow up PR. this one is big enough 😅

andrewiggins · 2023-06-23T22:33:02Z

packages/react-transform/src/index.ts

+				// TODO: Consider alternate implementation, where on enter of a function
+				// expression, we run our own manual scan the AST to determine if the
+				// function uses signals and is a component. This manual scan once upon
+				// seeing a function would probably be faster than running an entire
+				// babel pass with plugins on components twice.


For anyone with more experience with babel transforms - if I want to know if a function body contains JSX to know whether to perform my transformation, is it better to do a local visitor pass inside this ArrowFunctionExpression handler to observe that (only running my local visitor), and then transform? Or to do the observation in the larger babel visitor pass and then transform after, which triggers and additional visitor pass with all plugins?

That's a good question. I've never thought about this.

You can use something like this on a VariableDeclaration to see whether they are used as JSX

Oh interesting. IIUC, this code looks to see if a particular identifier is used as JSX somewhere in the same file?

andrewiggins · 2023-06-29T23:33:03Z

~~TODO for myself: Add some E2E babel transform tests, i.e. transform code and run it.~~ Done

XantreDev · 2023-07-04T12:22:24Z

What if someone calls useSignals twice? Or babel will add additional one?

…to make nested hook and component signal usage work

…m hook

andrewiggins · 2023-07-12T21:58:27Z

What if someone calls useSignals twice? Or babel will add additional one?

useSignals can be called multiple times in a component. It'll recreate the effect and other relevant tracking machinery but that's okay. The previous effect will be cleaned up and any signals used after the additional calls to useSignals will still trigger rerenders properly.

What about cases when signals used inside hooks that component uses? How to handle this case?

Hooks that use signals are transformed to call useSignals at the top of the function. In this situation, we are relying on the fact that calling useSignals multiple times is safe to do.

andrewiggins

Okay! I believe this is now ready for review 🎉

andrewiggins · 2023-07-12T22:00:35Z

packages/react-transform/src/index.ts

+// TODO:
+// - how to trigger rerenders on attributes change if transform never sees
+//   `.value`?


Will do this in a follow up PR. this one is big enough 😅

andrewiggins · 2023-07-12T22:04:41Z

packages/react-transform/src/index.ts

+	return hasLeadingComment(path, optOutCommentIdentifier);
+}
+
+function isOptedIntoSignalTracking(path: NodePath | null): boolean {


Here and in isOptedOutOfSignalTracking, I'm climbing up the AST to find the most logical place for a comment to live. For example supporting a use case such as:

/** @trackSignals */ export default function useCustomHook() {}

XantreDev · 2023-07-13T06:18:21Z

packages/react-transform/src/index.ts

+	return (
+		fnNameStartsWithCapital(path) && // Function name indicates it's a component
+		getData(path.scope, containsJSX) === true && // Function contains JSX
+		path.scope.parent === path.scope.getProgramParent() // Function is top-level


What about high order components? This type of components can use signals too

Yea, it's true. I'm thinking HoC will need to manually opt-in using /** @trackSignals */ or by calling useSignals() directly in their wrapper function.

It is harder to detect HoCs and know where to put the useSignals call so for now I'm explicitly skipping them. I should add a note to the Readme calling this out for people who want to use signals in higher order components.

I think it a good idea to mention edge cases in readme

andrewiggins · 2023-07-14T20:52:03Z

packages/react-transform/test/node/index.test.tsx

+						signal.value;
+						return <div>Hello World</div>;
+					} finally {
+						_effect.f();


Any opinions on the name of this method f? It's short for finishEffect to stop the current effect.

I've changed the return of useSignals from an method to an object that can hang other stuff of like the dispose symbol for using with using which this PR also includes support for.

…unctions

JoviDeCroock

This looks amazing

JoviDeCroock · 2023-07-19T07:47:20Z

packages/react-transform/src/index.ts

+				// TODO: Consider alternate implementation, where on enter of a function
+				// expression, we run our own manual scan the AST to determine if the
+				// function uses signals and is a component. This manual scan once upon
+				// seeing a function would probably be faster than running an entire
+				// babel pass with plugins on components twice.


You can use something like this on a VariableDeclaration to see whether they are used as JSX

andrewiggins added 20 commits June 21, 2023 14:41

Add hello world babel plugin

cb1b618

Fix browser tests to only run browser and shared test files

476b216

Lazily add import statement and add hook to template

b0d846f

Detect value member expressions and only transform functions with may…

76014fa

…be signal access

Use replaceWith to change function body

e8c583d

Improve types and clean up comments

594593a

Add manual mode support using @trackSignals comment

528f190

Add support for function expressions

f7863bc

Add notes for future work

df40e32

Add ability to opt-out of transform using comment

4ad28ab

Fix: Add missing exports declaration for runtime package

c46c7cd

Have useSignals clear the current updater after a microtick

eb838c4

Add tests for calling useSignals directly

15e83de

Move try/finally wrapping logic into a function

73fb6f4

Add option to not use try/finally to wrap stop tracking signals

c705084

Update comments

b2f8b9d

Use regex to match opt-in/opt-out comments

73da9dc

Update component detection logic to include JSX and top-level functio…

be03ccf

…n requirements

Share implementation of function-like visitors

ff17284

Initial write of react-transform readme

e4a8ce8

andrewiggins commented Jun 23, 2023

View reviewed changes

Merge branch 'main' into react-babel-plugin

b0bcd75

andrewiggins requested review from developit and marvinhagemeister June 26, 2023 21:29

Add missing build scripts to package.json

74696f3

andrewiggins added 4 commits July 12, 2023 14:30

Manually track if the babel transform is used to end signal tracking …

d5527a6

…to make nested hook and component signal usage work

Simplify render tracking by never stopping signal tracking in a custo…

fe7f7f2

…m hook

Re-organize transform file a bit

a76706b

Fix test:prod tests

ed01656

andrewiggins commented Jul 12, 2023

View reviewed changes

andrewiggins marked this pull request as ready for review July 12, 2023 22:09

Merge branch 'main' into react-babel-plugin

a122e59

XantreDev reviewed Jul 13, 2023

View reviewed changes

andrewiggins added 2 commits July 13, 2023 14:52

Reorganize tests

50bc4ee

Add importSource plugin option

1ace900

andrewiggins force-pushed the react-babel-plugin branch from 62c0fbd to 190d543 Compare July 14, 2023 20:44

Add support for using using

dd070c9

andrewiggins force-pushed the react-babel-plugin branch from 190d543 to dd070c9 Compare July 14, 2023 20:47

andrewiggins commented Jul 14, 2023

View reviewed changes

andrewiggins added 3 commits July 14, 2023 13:54

Add note about higher order components

1bab05b

Add changesets

59115d9

Cleanup effect store reference after using it

cd3a22d

andrewiggins force-pushed the react-babel-plugin branch from a29b9e3 to cd3a22d Compare July 14, 2023 21:01

andrewiggins added 3 commits July 14, 2023 15:43

Add test for not transforming hook callbacks

b90a938

Add support for trackSignals comments on object properties that are f…

f01b413

…unctions

Add support for trackSignals comments on object property assignment

033224a

JoviDeCroock approved these changes Jul 19, 2023

View reviewed changes

andrewiggins mentioned this pull request Jul 20, 2023

Upgrade to pnpm v8 #391

Merged

marvinhagemeister approved these changes Jul 28, 2023

View reviewed changes

andrewiggins added 2 commits August 2, 2023 13:44

Merge branch 'main' into react-babel-plugin

1099b7b

Final PR tweaks

255208a

andrewiggins merged commit fe44f6e into main Aug 2, 2023
7 checks passed

andrewiggins deleted the react-babel-plugin branch August 2, 2023 22:23

github-actions bot mentioned this pull request Jul 31, 2023

Version Packages #393

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add package `@preact/signals-react-transform` #375

Add package `@preact/signals-react-transform` #375

andrewiggins commented Jun 23, 2023 •

edited

Loading

changeset-bot bot commented Jun 23, 2023 •

edited

Loading

netlify bot commented Jun 23, 2023 •

edited

Loading

github-actions bot commented Jun 23, 2023 •

edited

Loading

andrewiggins Jun 23, 2023

andrewiggins Jun 23, 2023

marvinhagemeister Jun 27, 2023

andrewiggins Jun 23, 2023

andrewiggins Jul 12, 2023

andrewiggins Jun 23, 2023

marvinhagemeister Jun 27, 2023

JoviDeCroock Jul 19, 2023

andrewiggins Jul 19, 2023

andrewiggins commented Jun 29, 2023 •

edited

Loading

XantreDev commented Jul 4, 2023

andrewiggins commented Jul 12, 2023 •

edited by rschristian

Loading

andrewiggins left a comment

andrewiggins Jul 12, 2023

andrewiggins Jul 12, 2023

XantreDev Jul 13, 2023

andrewiggins Jul 13, 2023

XantreDev Jul 14, 2023

andrewiggins Jul 14, 2023

JoviDeCroock left a comment

JoviDeCroock Jul 19, 2023

Add package @preact/signals-react-transform #375

Add package @preact/signals-react-transform #375

Conversation

andrewiggins commented Jun 23, 2023 • edited Loading

changeset-bot bot commented Jun 23, 2023 • edited Loading

🦋 Changeset detected

netlify bot commented Jun 23, 2023 • edited Loading

✅ Deploy Preview for preact-signals-demo ready!

github-actions bot commented Jun 23, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrewiggins commented Jun 29, 2023 • edited Loading

XantreDev commented Jul 4, 2023

andrewiggins commented Jul 12, 2023 • edited by rschristian Loading

andrewiggins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JoviDeCroock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Add package `@preact/signals-react-transform` #375

Add package `@preact/signals-react-transform` #375

andrewiggins commented Jun 23, 2023 •

edited

Loading

changeset-bot bot commented Jun 23, 2023 •

edited

Loading

netlify bot commented Jun 23, 2023 •

edited

Loading

github-actions bot commented Jun 23, 2023 •

edited

Loading

andrewiggins commented Jun 29, 2023 •

edited

Loading

andrewiggins commented Jul 12, 2023 •

edited by rschristian

Loading