State of this library, no pun intended

[reintroducing]

Hello, I'm taking some time to evaluate Legend State for an application I work on because I think it has a good use case to help us out in some areas of our codebase. I'm new to observables, so take this with a grain of salt, but I'm wondering what the state of this library is? In looking through the docs and examples, there seem to be a mix of v3 and v2 throughout, and it's not immediately clear which is correct. I realize that v3 is on the horizon and in beta (which is what I'm using as the docs suggest) and so maybe we're in a bit of a state of flux here, but just wanted clarity around this.

Additionally, I've been trying the examples out (would be REALLY helpful to have some copy/pasteable code, or direct links to StackBlitz working examples rather than the in-line doc examples) and a few of them seem to not be working correctly (or have what looks like React Native code even though I'm looking at React examples). Here is one such example: https://stackblitz.com/edit/vitejs-vite-d5k39rkv?file=src%2FApp.tsx&terminal=dev

If you click on the Add button, it adds the Todo, and when you click the Clear button, it clears them, but then if you click Add again it errors in the console and the screen goes white.

This whole process has soured me a bit on making a recommendation to my peers about using Legend State in our app and I've stopped short of trying to implement a POC with our app because I'm not quite sure that I'm going to get very far. Can you give a quick update on what I'm seeing and if this is expected, and are these issues currently being fixed for the new version?

I appreciate your work on this but just wanted to put my mind at ease a bit.

[jmeistrich]

Hi @reintroducing! We did a revamp of the v3 docs recently, to change the suggested patterns to use$ instead of observer (see https://www.legendapp.com/open-source/state/v3/other/migrating/). It's possible that while doing that, some things got incorrect or we may have broken the React / React Native selector?

The Getting Started page has a selector at the top to switch between React and React Native. That replaces the text in some of the examples from the React Native version to the React version. I just looked it over and it seems like it's still working correctly? Is it not correct in some part I'm missing? Or are there examples on other pages that are wrong?

It is certainly a weird in-flux time right now with v3 having been in development and then beta for a long time. It's been a very big and complex project - sync engines are even harder to get right than state libraries 😅. And we recently had a delay from needing to rethink some things to be more compatible with Compiler before going to stable. Plus, I got distracted by making Legend List. But we're in the final stretch now I think - no more big changes, just fixing bugs/issues towards a stable release.

Understood about wanting StackBlitz links! We originally had CodeSandbox links, but it was harder to keep track of those as we were making changes so they quickly went out of date. And I personally get annoyed by waiting for examples to build before I can see them, so I much prefer our inline examples. But it's certainly valuable to have both! As v3 stabilizes, I think it would be great to add StackBlitz or CodeSandbox links under the examples.

The problem if your example on StackBlitz is that todos is an array, but addTodos sets by id as if it's an object: store$.todos[todo.id].set(todo);. Change that to an array push and it should work: store$.todos.push(todo);

[reintroducing]

Hey @jmeistrich, thank you for taking the time to write up a detailed reply, much appreciated.

Hi @reintroducing! We did a revamp of the v3 docs recently, to change the suggested patterns to use$ instead of observer (see https://www.legendapp.com/open-source/state/v3/other/migrating/). It's possible that while doing that, some things got incorrect or we may have broken the React / React Native selector?

On the getting started page in the Observables in React section, I have React selected and I see components like Box and Button in the example. I do see that they also exist in the React Native example (along with Text and View which I know are RN components) but its hard to know if they are RN components or not because the imports are not fully shown in the example code (which is another reason why I had mentioned full examples on StackBlitz so you can see all files and where everything is coming from). I assumed those were RN components and I could not just copy/paste the example code into my POC Vite project locally and see it all working (i typically do this when learning new libraries so i can play with them along with other code I've written for the POC to understand how it all would work together).

Another such example is in the useObservable docs, where its not clear where Input comes from (i don't actually use RN so not sure if thats a RN component or not), but again, there is no way to see where the import came from or whats in that file, so to a new user its very confusing because you can't look at the files on SB or elsewhere to know where they are. Perhaps even adding a link, in each code block (top right maybe?) to the GH code for that example would be useful?

It is certainly a weird in-flux time right now with v3 having been in development and then beta for a long time. It's been a very big and complex project - sync engines are even harder to get right than state libraries 😅. And we recently had a delay from needing to rethink some things to be more compatible with Compiler before going to stable. Plus, I got distracted by making Legend List. But we're in the final stretch now I think - no more big changes, just fixing bugs/issues towards a stable release.

This is totally understandable, React 19 made some pretty big changes and I imagine its not easy to update everything for a library like this when that happens. Happy to hear that its in the final stretch, though.

Understood about wanting StackBlitz links! We originally had CodeSandbox links, but it was harder to keep track of those as we were making changes so they quickly went out of date. And I personally get annoyed by waiting for examples to build before I can see them, so I much prefer our inline examples. But it's certainly valuable to have both! As v3 stabilizes, I think it would be great to add StackBlitz or CodeSandbox links under the examples.

This is also understandable, I'm sure its pretty annoying to have to remember to keep everything updated across internal examples as well as at an external source. I'm not sure how TanStack does it but they do a good job with their examples of providing SB embeds and then linking out to the GH source as well (as I mentioned above). I wonder if it stays in sync somehow so they don't have to manage it separately, although of course as I write this, it seems like the SB examples are broken :) But at least you can see the links on that page at the top linking out to both to demonstrate kind of what I mean. I don't know enough about SB to know if its possible to just create them off of a repo URL or similar, but would be great to see something like this and lessen the burden of maintenance on you if possible.

(side note: i actually just tried to go to my SB example link and its also not working, so maybe generally speaking SB is wonky right now).

The problem if your example on StackBlitz is that todos is an array, but addTodos sets by id as if it's an object: store$.todos[todo.id].set(todo);. Change that to an array push and it should work: store$.todos.push(todo);

My example took the code directly from the example here which is apparently incorrect. Interestingly enough if you scroll further down to the Full Example which seems to mimic this and look at the store$ variable, the addTodo does indeed use a push instead, so it's probably just a matter of getting the examples lined up correctly as new users won't know this and assume, like i did, that it is broken.

I know maintaining public libraries and documentation is not an easy thing to do, and again, I do appreciate all the work that you put into this as well as your other open source libraries. As a first time user of the library and the docs, it just gave me a feeling of hesitation to see these issues because it gives the perception that things aren't buttoned up and its hard to find answers in the moment. I'm a long time Zustand user and really like its API, but I happen to be working on a project right now that I think would really benefit from Legend State so that I don't have to refactor thousands of lines of code with how the global store is set up. Its not a secret that Zustand has a wealth of information in their docs as well as a pretty large community where you can usually hop on stack overflow or somewhere online and get answers to the many problems people have faced while using it, so when you go to a library that has a smaller following and see it is much harder to find those answers, it makes it imperative that the docs be as bulletproof as possible and not give a new user pause. I only say all of this not to criticize, just to help you understand where my mind went when I started working on this yesterday and ran up against some of these issues.

[yairhaimo]

+1 for the "Getting Started" example not being complete and thus not working.

Also, if the Reactive Components are not mandatory, I wouldn't put them in the Getting Started example. It really confuses and might push people away from starting playing with the framework as it puts a very steep learning curve upfront.

Edit: Im super excited to use this framework. So take this comment as something positive :)