Imports in documentation for Signals

[mindplay-dk]

I noticed a possible minor issue with the documentation for Signals.

In some examples on the page, imports look like this:

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

In some later examples on the same page, instead imports look like this:

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

The switch from @preact/signals to @preact/signals-core doesn't seem to be explained in the text.

Presumably @preact/signals-core is the stuff that's generic and shared with the React implementation?

And @preact/signals is the Preact-specific implementation?

So I'm not grasping why you would switch between these in the examples.

(note also that @preact/signals-core was published without a README.)

[rschristian]

(note also that @preact/signals-core was published without a README.)

This at least has already been addressed in preactjs/signals#82, just haven't published since.

[mindplay-dk]

Cool, and I think I figured out my misunderstanding here.

It looks like @preact/signals is just re-exporting everything from @preact/signals-core - exports from two different packages, I just figured they would be different somehow.

And reading over the examples, I failed to even spot the fact that some places you're calling signal and other places it's useSignal - I think I've developed a kind of blindness for the word "use", React code being so full of them, I don't even see them anymore. 😅

So the hooks are provided by @preact/signals for local state, and the core reactive functions are provided by @preact/signals-core for global state.

Makes sense now, and I think you can close this issue.

Though I would suggest maybe adding an explanation near the top of the page to clarify the roles of the two packages, because it's really easy to confuse signal with useSignal if you suffer from "use blindness" like me - and it's also easy to miss the difference between imports from @preact/signals and @preact/signals-core because of the re-exports from @preact/signals. Might be better to explain right off the bat why there are two packages?

[mindplay-dk]

I guess you could also side step any confusion by avoiding imports from @preact/signals-core entirely?

Since the symbols from @preact/signals are just re-exports anyhow.

It's probably a larger package, but it looks like it's tree-shakeable - using @preact/signals-core in the context of a Preact project is probably a micro optimization anyhow?

[rschristian]

(I see this is old, but figured I'd answer some of this anyways)

It looks like @preact/signals is just re-exporting everything from @preact/signals-core - exports from two different packages, I just figured they would be different somehow.

Yup.

They are sorta different, as wiith @preact/signals you get renderer tie-in, so there is a difference in behavior there.

Though I would suggest maybe adding an explanation near the top of the page to clarify the roles of the two packages, because it's really easy to confuse signal with useSignal if you suffer from "use blindness" like me - and it's also easy to miss the difference between imports from @preact/signals and @preact/signals-core because of the re-exports from @preact/signals. Might be better to explain right off the bat why there are two packages?

Agree, that's probably something we want to draw attention to.

using @preact/signals-core in the context of a Preact project is probably a micro optimization anyhow?

No, using @preact/signals-core would sacrifice the rendering optimizations baked into @preact/signals.

[mindplay-dk]

using @preact/signals-core in the context of a Preact project is probably a micro optimization anyhow?

No, using @preact/signals-core would sacrifice the rendering optimizations baked into @preact/signals.

In that case, they definitely shouldn't be used in Preact examples, should they?

[rschristian]

Indeed.

But as far as I can tell they're not, at least not anymore. Might've gotten fixed at some point if you were seeing that in the past.

(Let me know if you are seeing them somewhere though, possible I'm being an idiot and reading over an example)

[mindplay-dk]

Currently 3 in-page search-results for signals-core in https://preactjs.com/guide/v10/signals/

[rschristian]

None of those 3 are using signals in Preact. Those are standalone examples, so using the core lib there is correct.

[mindplay-dk]

Okay, that's a bit confusing. But yes, I understand now that these examples are not in fact about Preact - they're about using Signals independently of Preact.

Perhaps this section should be migrated to a separate page under "Advanced"? With a link from where it is now.

The title "Advanced signals usage" does make it seem out of place in the "Essentials" section, I think.

[rschristian]

Perhaps that's some poor naming, indeed. I'm not a huge fan of splitting up the content (we don't really do that for any other topic) but maybe that's what we need to do.

There's also the question of whether signals-core should be covered in Preact's docs at all (from the Preact team, but not necessarily relevant to someone looking to use Preact + its addons) but I don't have a great answer for that at the moment either.

Will definitely be thinking about this though, maybe there's a way to restructure some of our content that'll fit this sort of situation better. I think our current set up does make it a bit difficult to differentiate what's from the team and what's meant to be used with Preact itself.