Evangelism ideas

[sesam]

To capture the interest of developers, it would be beneficial if:

1. Understanding is easy. Ideally the "above the fold" view of the repo (and npm / ... flutter pub page) is enough to be able to make use of the library.
2. Dipping your toes is easy. Ideally an easy to remember import line, and "one line" changes in the actual code to use this library instead of whatever was in use before.
3. Swapping is easy. Ideally some compatibility layer that would make it easy to just replace all usage of, say, React.useState with a klyva-based
4. Switching over is easy - have something like a codemod approach for cleaning up after having started doing the above steps and decided to go all-in.

(We discussed this on Discord, and I plan to update this more a bit later)

[merisbahti]

Hey Sesam, thanks for your time.

Understanding is easy. Ideally the "above the fold" view of the repo (and npm / ... flutter pub page) is enough to be able to make use of the library.

Hmm do you have an example of this?

Dipping your toes is easy. Ideally an easy to remember import line, and "one line" changes in the actual code to use this library instead of whatever was in use before. Swapping is easy. Ideally some compatibility layer that would make it easy to just replace all usage of, say, React.useState with a klyva-based

What would this replace do you mean? redux or recoil? Either way there's quite big differences, klyva might even have more in common with redux than it has with recoil in some aspects. So it's important for us to discuss what this would mean, how would we accomplish somebody changing just one line and swapping to klyva? Do we even want this?

I remember the redux burnout the community faced in 2015-2016, where everyone would put state their redux stores, even if it didn't belong there (server cache, hover state, etc). I think we need to be precise about the objective of klyva, and rather not see people using it as a server cache or similar. (react-query solves this better).

Switching over is easy - have something like a codemod approach for cleaning up after having started doing the above steps and decided to go all-in.

That's interesting, I'd gladly try this out. A new version of useAtom could be constructed that looks like the one in recoil and jotai. Definately interesting.

[msakrejda]

@merisbahti @sesam along these same lines, I think it would be really helpful to have a comparison with other React state-management tools. Jotai has this page -- it's not super thorough but it's something. You have a brief blurb at the end of the README right now, but given how critical state management is to an app, more guidance as to where klyva is a good fit would be great (whether in terms of front-end architecture, performance, or other criteria).

[merisbahti]

Hmm ok; I see. What would be nice to see in such a page? I was thinking maybe a small todo-application?

[msakrejda]

Sure, I think a small sample app would be great. But even just having a brief discussion of pros and cons vis-à-vis other similar state management libraries would be very useful.

[merisbahti]

Ok so I've been thinking about this and you're definitely right, I started with atleast making a codesandbox here: https://github.com/merisbahti/klyva (scroll down to the useAtomSlice example). Do you think this is too much? I wanted to be sure to show usage of useAtomSlice and useAtom, which are the two most important hooks for klyva.

[msakrejda]

Nice, I think the examples are great. Though I was thinking more high-level conceptual explanations, and how to approach state management with klyva in terms of front-end architecture in a real app. For example, right now, the README gives a brief description and then jumps right into "How to create an atom" without describing what atoms are or why you might want to use them for state management.

It's also billed as state management for React, but React is not mentioned again until two pages down. Maybe "How to" should be titled "Basics" or "Building Blocks" or something like that, to indicate this is about the core concepts? Then I think the React section itself hits one of the biggest challenges in explaining state management: finding the right balance between realistic examples and something that will fit in a README. Right now, the useAtom example is clear, but it only hints at how myAtom can be accessed from other components and other places in the app--typically you would not just define it unexported in the same file, since you could just useState instead (or do you feel useAtom should be a replacement for useState in some cases?). But then if you do want to share it, what's a good way to organize that in code? Export it from some component that "owns" that piece of state? Have a separate atoms folder that exports atoms? Have a state folder where you write custom hooks wrapping useAtom? I think describing some best practices around this would really help potential users understand how klyva could solve their state management problems.

Also, if the atoms are essentially global state, how do you handle testing--specifically avoiding components stomping over each other's state during unit tests? Zustand has some discussion in https://github.com/pmndrs/zustand/issues/242 but it feels like an afterthought. Are there best practices for that with klyva?

Maybe this is too much for a README, but I think clarifying some of these high-level concepts would be very useful.

[sesam]

Nice! One possibility for a code example could be something like https://github.com/getify/A-Tale-Of-Three-Lists if the middle list would be composed of the list-atoms of the left and the right. Change right atom, and right and "merged" list updates. Or maybe you can extract some simplified example from the codebase where you've already used klyva?

[sesam]

Also, for clarity it might be good to split up some ideas here into their own tickets. Testing seems very important and probably has to be "well baked" before klyva can see wider adoption, so let's gather testing dream-scenarios in https://github.com/merisbahti/klyva/issues/12 and then figure out if those dreams can come true. Just keeping track of the next smallest step in the right direction.

[sesam]

One part of evangelising could be to format the landing page of klyva to be the dream-version of how you'd want this to look for a state library. Most future visitors will come in on their mobile, through a link they got on twitter, I suspect.

A start:

[merisbahti]

Nice, I think the examples are great. Though I was thinking more high-level conceptual explanations, and how to approach state management with klyva in terms of front-end architecture in a real app. For example, right now, the README gives a brief description and then jumps right into "How to create an atom" without describing what atoms are or why you might want to use them for state management.

It's also billed as state management for React, but React is not mentioned again until two pages down. Maybe "How to" should be titled "Basics" or "Building Blocks" or something like that, to indicate this is about the core concepts? Then I think the React section itself hits one of the biggest challenges in explaining state management: finding the right balance between realistic examples and something that will fit in a README. Right now, the useAtom example is clear, but it only hints at how myAtom can be accessed from other components and other places in the app--typically you would not just define it unexported in the same file, since you could just useState instead (or do you feel useAtom should be a replacement for useState in some cases?). But then if you do want to share it, what's a good way to organize that in code? Export it from some component that "owns" that piece of state? Have a separate atoms folder that exports atoms? Have a state folder where you write custom hooks wrapping useAtom? I think describing some best practices around this would really help potential users understand how klyva could solve their state management problems.

Also, if the atoms are essentially global state, how do you handle testing--specifically avoiding components stomping over each other's state during unit tests? Zustand has some discussion in pmndrs/zustand#242 but it feels like an afterthought. Are there best practices for that with klyva?

Maybe this is too much for a README, but I think clarifying some of these high-level concepts would be very useful.

Great ideas!

Regarding testing simon has created an issue here where I answer: https://github.com/merisbahti/klyva/issues/12

I've reordered the README now to focus on react.

But we'll definitely have to make a dedicated docs folder for more advanced discussions, like architecture, which really is what klyva wants to solve. I might even make a video tutorial if I get the courage!

One part of evangelising could be to format the landing page of klyva to be the dream-version of how you'd want this to look for a state library. Most future visitors will come in on their mobile, through a link they got on twitter, I suspect.

A start:

Ooh really cool start, I'm not super visual like that, but I'll try to make the README a bit prettier, and like you say, mobile friendly.