Repository navigation
📚 Docs Wish List #552
Replies: 39 comments 23 replies
|
I'm becoming familiar with the Xstate Docs and really like their style and format. However... While the sections focus beautifully on implementation details there is virtually no mention of patterns and architecture (other than indicating a relationship with the Actor model). If there is one thing that (I believe) helps new learners (especially beginners) it is being able to understand implementation details clearly within the context of patterns and architecture - and in relation to other patterns and architecture. The Redux Docs are an excellent example of this presentation of detail in context. These two articles, by the same author of the Docs, provide even more context and opportunity for understanding the why's and how's: https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/ I know how hard it is to write good documentation but I think this kind of addition would be of significant benefit. I believe that it would dramatically improve comprehension. I would like to help if there were an opportunity. Even if it was to give feedback from a beginner's level. |
|
In my current thinking I see functional programming as a natural fit with both unidirectional data flow and reactivity to observed state changes. But because of my lack of experience I have attempted to find documentation that could help me understand how Xstate's Actor + FSM architecture might be understood in contrast with this view. I could not. I couldn't see if we were being asked to abandon a unidirectional data design and, if so, why. What also added to this question is that Xstate seems somewhat unique in its own implementation of the Actor model due to being also reactive and functional. Functional programming and reactivity did not seem to be native to the various Actor models I was reading about. Those Actor variants appear to promote messaging rather than reactive streams, and an object model over functional model. What I saw in Xstate's Actor was a many-to-many message passing model. But this does not appear to be reenforced and clarified in the implementation details throughout the rest of the Docs. While looking for insight into these questions (and many others) I have also attempted to understand how Xstate messaging might be wired up to Svelte's native reactivity. I had no ground on which to stand and orient myself amongst all of this. |
|
What I see as another natural fit for functional, reactive programming (and the basis of a unidirectional architecture) learning about the CQRS/event sourcing model influenced me significantly. In the absence of being able to read more in depth about Xstate's own patterns and architecture, I could not come to any understanding or relate it to what else I was learning about. However, this document seemed to indicate a natural fit between the Actor model and the CQRS/event sourcing model: |
|
The approach to developing an entire application whether in functional or actor model are entirely different paradigm. If choosing actor model, functional programming can still be implemented but within the context of an Actor as reusable business logics triggered in Xstate. This approach harness the best of functional and actor programming. Just my opinion. |
|
A few thoughts on tech writing in general that might be useful. Apologies if this is all blindingly obvious to you.
|
|
@avaragado I just randomly came across this discussion and noticed all of the thumbs up and hearts on your comment. After reading it, I must say that they have been earned and then some; I added a thumbs up and heart of my own, for whatever they're worth. I have a "cheat sheet" of random tips, tricks, and commands that I keep for my development work and these have all earned a spot on that list. As such, I thought I'd stop and say thank you for taking the time to write this. Documentation is so hard to write and each and every one of these bullet points is a worthy aspiration for any good piece of documentation. |
|
Thank you! |
|
I want to start by saying that I really love the documentation already. I would love to have more documentation or examples on TypeScript. Which types to use when passing an Another thing that could be useful is a In the docs, an example of this can be found for actions
A page with reserved xstate keywords like |
Each section in "guides" (when applicable) will have a TypeScript section. I'm also working on simplifying TypeScript types.
Great idea. I should make some sort of toggle between TS and JS for the code examples.
I'm making "Tutorials" that shows the best practices in practice, but afterwards I can compile a summary of the best practices. It's just weird (for the reader) to see best practices out of context (e.g., "always avoid this" without a reason why, or an exception).
Like a glossary? Good idea. |
|
Yes, a glossary of xstate reserved keywords in machines sounds good. |
|
It may be helpful to have guidance on how to implement the core of Xstate - its machines and charts - into existing state management patterns and architectures as well as having guidance on adopting the Actor model and Xstate's own state management paradigm. |
|
Pure state machines and actor model, sure. Statecharts are a complex algorithm. See for yourself: https://www.w3.org/TR/scxml/#AlgorithmforSCXMLInterpretation |
|
I've updated my above post to mean Xstate's machines and charts. |
|
I just found this library today and have gone read all the documentation. First thing I want to say is thank you so much for the quality of the documentation already. It is excellent. Some of the best I have seen. A couple things I would like to have seen:
|
|
I feel a bit silly posting this but one thing I struggled with was deciding whether something should be a state or a guard. My initial understanding was that you declare events in a specific state to "guard" them and transition to those states under correct conditions. However, we can also declare events inside a state that it shouldn't always be able to fire in and use an XState guard to validate the condition before firing. For example: const machine = Machine({
id: 'myMachine',
initial: 'form',
states: {
form: {
on: {
INPUT_THING: {
actions: ['setThing'],
target: 'valid'
},
}
},
valid: {
on: {
SUBMIT: ['handleSubmit'],
}
}
}
});versus: const machine = Machine({
id: 'myMachine',
initial: 'input',
states: {
form: {
on: {
INPUT_THING: {
actions: ['setThing'],
},
SUBMIT: {
cond: 'isValid',
actions: ['handleSubmit'],
}
}
},
}
});I ended up going with the latter for my particular implementation because the |
Aw man, this made me re-read some of my blog posts and I have a Thanks @abierbaum. Great write up and suggestions. I'd like to highlight your last point:
I've struggled with the "why" in particular from the XState docs. I'm a fully self taught dev so don't have a CS background or any previous experience with State Machines. Some of the concepts/terminologies are a bit hard to grasp and understand the "why" for me at the moment. Actors, for example, seem to provide pub/sub communication between machines but this appears to introduce a bidirectional data flow. With React, I'm used to data down, actions up so why would I choose Actors over what I'm used to? Also, is there any harm in just mapping machine actions to React component handlers for that communication? const Parent = () = {
const [machine, send] = useMachine(parentMachine);
return (
<Child
thing={machine.context.thing}
onChange={event => {
send({
type: 'INPUT_THING',
payload: event.target.value
});
}
/>
);
};
const Child = ({ onChange }) = {
const [machine, send] = useMachine(childMachine, {
actions: {
handleChange: onChange
}
});
// etc...
};It feels this would keep component concerns separate and appease my unidirectional flow preference, but it's not clear if that would make my machines brittle in some way and if we should stick to Actors for that reason. |
|
Thanks for this library, I'm having fun learning it and I plan on switching to it for my side projects. I would like to see documentation of all the options that can be passed to each state, service, etc. Right now I find myself looking through the docs for an example that does what I want, and often finding it as part of an unrelated example. Add a link to your React Conf 2017 talk, it's the one that sold me and my coworkers on state charts. The price of the book you mention in the talk has fallen to just over $100. Things I'm struggling with:
|
This was helpful in clearing up my Actors confusion. This was also a lovely simple explanation: |
|
Something that multiple people on my team have hit is trying to use the null transition instead of an entry/exit transition. Without making the null transition target a new state xstate gets into an infinite loop and the error message isn't very clear about what really went wrong. That feels like something that should either be prevented, or it should be documented clearly not to use the null state in that way. Maybe something as simple as a big warning in the docs on the null transition to point the user at the entry/exit transition as a better solution would work? |
|
I think it would be good to add a warning if an eventless transition can get into an infinite loop. Can you share some example code where this is happening, so we can better identify the patterns? |
|
The following sandbox demonstrates. Though in this case I used |
|
It should be fairly easy to extend this validator to identify this kind of a problem: I think for starters we'd have to check against unguarded, targetless & eventless transitions. This should cover most situations I think. |
|
@Andarist Want me to make an issue for tracking this? |
|
I would love to see in docs some summarization of what |
|
Sure, I can add that. In general, it cleans up all listeners and recursively stops all spawned/invoked actors. |
|
@FredyC even if it didn't clean those listeners the registered callbacks could be cleared up by the garbage collector - if you would dispose of a reference to the Much more interesting is the fact about stopping children etc. |
XState has quite a bit of the same API as FSM. I'd like to have some kind of marker or filter to the entries in the XState docs that are FSM compatible. In general, more simple examples help. Thanks so much! |
|
That's a good idea! |
|
Apologies if someone already mentioned this - it would be really helpful to have more verbose docs and possibly step-by-step examples on how to setup unit tests for machines - both with I've been attempting to read through the testing section of the docs as well as the discussions here and in the original Spectrum community but it gets a little overwhelming trying to locate examples and wrap my head around what to do. |
|
This was recently added re: unit testing machines: https://xstate.js.org/docs/guides/testing.html |
|
Thanks, David! I had reviewed those and they were helpful for how to test the machine itself but I'm still lost on what to do if I need to test a React component (or nested React components) and the machine it uses - if that makes any sense. |
|
On my project we just use jest mocks to mock out any services the machine has to call and everything else just works in general. You can even use a promise with no resolution to mock out loaded states if needed. EDIT: |
|
Adding this Twitter thread here: https://twitter.com/mpocock1/status/1345083512173555712 |
|
I wanted to share what I consider one of the best documentation system resources available: https://documentation.divio.com/ This image encapsulates the big picture ideas presented:
Each quadrant has a rather particular way that the documentation should be written and presented, because each accomplishes a different outcome and targets different types of users. I think XState's strong point right now is the reference quadrant. The documentation is mostly an API reference, and it does a good job covering the vast majority of the API and how it works. This is great for people who already have a decent understanding of XState and want to turn to the docs for a quick refresher on how exactly something is used. For the other three quadrants, I think there are bits and pieces of each scattered throughout the docs, but for the most part, they're nonexistent. This is especially hard on new users, as the learning curve can be quite drastic due to a lack of resources that hold your hand as they help you build something/teach you the high-level concepts, a lack of quality examples (though XState Catalog is SPECTACULAR at filling this gap), and how-to guides around how to take those concepts and produce something of value. Essentially, API reference gives us the what, but we're missing the why, when, and how. In my opinion, I think XState would be best served by considering each quadrant as a separate platform-within-a-platform. Keeping the content for each quadrant separate allows users to easily access the type of content that works best for them, while also allowing for easy linking between the sections (a tutorial linking to an explanation page for more detailed information than is relevant to the tutorial, an API reference page linking to a how-to guide that utilizes that part of the API, etc.). |
|
@mattpocock had linked to the Redux FAQ and I think it's a really great example of the "explanation" quadrant. It answers specific questions in order to provide a conceptual understanding of how Redux works under the hood. Combined with the "Understanding Redux" section of their docs, a user can get a significant amount of conceptual information about the framework. |
|
Agree with the idea. When I am looking for a quick start. just for a counter. But The In the document, the I have to search on google xstate counter... then link back to the document. |
|
Wanted to share some topics that were discussed in the Discord #documentation channel today:
|
|
I am just coming in for a few weeks now. I think most topics haven't yet 'clicked', but they will eventually. Then it hit me: we all probably have a few of those. Could we list them somewhere, I feel that this could be a valuable resource. And it can show the difference state machines can make. |
|
A pattern page for spawning machines and passing data between them? I know a lot of people especially in legal/social services need flows that collect and validate data in heavy ways. That was something I found hard when first getting started, but I feel like I settled on a really nice flow in re-writing upsolve.org's data collection questionnaires with XState, and would like to share to help others |
|
@davidkpiano an example of testing a react component with xstate by mocking invoked services would be very helpful. Thanks. |
|
|
In machine.md activities are mentioned, but when I checked the relevant section, I see that they are deprecated. It should probably be removed because it is confusing when reading the docs sequentially. |
|
PR here: #3100 |
|
+1 for a better TypeScript & best practices documentation. I'm currently upgrading an app from XState 4.16. So far, here is what bothered (or still bothers) me the most: When it comes to typing machines:
Regarding TypegenEven with a (very) basic understanding of the "why?", the whole "let's add one more plugin/CLI to the dev's tooling" feels like terrible DX imho. Even if it comes out great, it's still an extra pain to setup (plugins are a no-go since I want my team members to be free to use whatever IDE they see fit). I might have missed something, but I think some explanations (and maybe a setup guide) might be a great addition to the doc. Regarding testing
ExportsDefinitely not a big deal, but exports lack consistence, and the doc reflects it. Right now, there's 3 (!) ways to import actions for instance:
And that's all... for now 😄 |
IntroductionI apologize if I'm repeating some points that have been said here but here's my feedback from the perspective of a beginner that has read the current documenation and beta documentation for XState. PraiseFirst I need to praise the introduction to state machines and statecharts because it's an absolutely wonderful introduction even I could understand. The Docs Leave You StrandedAfter the introduction I'm excited and want to learn more. I continue reading about Machines which introduces a nice basic example that shows how to define a basic state machine but unfortunately here is how most examples end up being frustrating because it leaves things to the imagination. import { createMachine } from 'xstate'
const lightMachine = createMachine({
// machine identifier
id: 'light',
// initial state
initial: 'green',
// context
context: {
elapsed: 0,
direction: 'east'
},
// state definitions
states: {
green: {
// ?
},
yellow: {
// ?
},
red: {
// ?
}
}
})
// how do I even make this work?After that point the docs leave you stranded because to get a basic example working you have to piece the information together yourself from different sources — the examples are more for documenting the API instead of guiding you as the name of the section implies. I scour the docs and the internet to piece the information together which I don't mind honestly but I would prefer if you could level up step by step reading the docs and get that dopamine hit. After reading more of the docs I feel confident I can make something basic and I reach for the high IQ counter example of course. Sounds great but here is another example where I feel the docs fail you for the same reason having to piece the information together yourself which feels like work instead of being a fun learning experience. const counterMachine = createMachine(
{
initial: 'active',
context: { count: 0 },
states: {
active: {
on: {
INCREMENT: { actions: 'increment' },
DECREMENT: { actions: 'decrement' },
},
},
},
},
{
actions: {
increment: assign({ count: (ctx) => ctx.count + 1 }),
decrement: assign({ count: (ctx) => ctx.count - 1 }),
}
}
)If I'm feeling spicy I might even throw in a guarded transition but so far I'm pleased and I learned earlier I have to interpret the machine and start the service using regular JavaScript. const counter = interpret(counterMachine).start()Awesome! Now I just want to simply output const incrementEl = document.querySelector('.increment')
const decrementEl = document.querySelector('.decrement')
const countEl = document.querySelector('.count')
incrementEl.onclick = () => counter.send({ type: 'INCREMENT' })
decrementEl.onclick = () => counter.send({ type: 'DECREMENT' })
// ...I spend more time looking through the docs to find what I missed hoping there's a similar example at least which there is but it's also incomplete and I find the solution from a random post. counter.subscribe((state) => {
countEl.innerText = state.context.count
})No wonder this works like magic in Svelte. I don't remember reading or seeing anything about After I'm done I jump into some of the tutorials and I'm faced with the same problem because it also requires knowledge hunting and gathering from before and there's examples but it's using a framework when the docs aren't using it in the examples and introduces more mental overhead. I wish it wasn't that way because I can't imagine how it's for someone that's not even familiar with any of these concepts. Hope this is helpful! |
|
Extremely helpful, thank you very much for writing this! I agree that the docs could use more love, especially when guiding new devs to being productive with it quickly without having to reach out beyond the docs. |
|
|
|
I would appreciate better resources on how to integrate with react server components. |
|
What exactly would you like to know how to do here? |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Inspired by #255 (comment) and other conversations, both online and in person:
What would you like to see in the documentation? Let's keep a running list of things that would be beneficial to:
Some suggestions for things that can be included:
Current suggestions:
Please post your suggestions 👇 Thank you!
All reactions