docs: adding concept doc for concepts #168
Conversation
| It uses `jsx` to define and orchestrate workflows with functional, reusable components: | ||
| Contexts are particularly useful for: | ||
|
|
||
| - Sharing configuration across multiple components |
There was a problem hiding this comment.
Might be worthwhile calling out examples such as client singletons.
There was a problem hiding this comment.
I guess this is mentioned in the providers section below.
| - Providing dependencies to deeply nested components without prop drilling | ||
| - Managing state that needs to be accessed by multiple components | ||
|
|
||
| GenSX also supports [Providers](../providers) which are a specialized use of contexts that focus on managing configuration and dependencies for your workflow. If you're managing external service configurations like API keys or client instances, you should use providers instead of raw contexts. |
There was a problem hiding this comment.
This gives the impression that Providers aren't tightly coupled with context, when they really are. You can't (usefully) use a context without a provider.
There was a problem hiding this comment.
Very good point. I'll revise this. I probably also need to clean up some of the verbiage in the providers doc
| async function main() { | ||
| // Provide a value to the context | ||
| const result = await gsx.execute( | ||
| <UserContext.Provider |
There was a problem hiding this comment.
Do you think its worth demonstrating nesting providers, or just leave that up to the docs?
There was a problem hiding this comment.
Agree we should probably show that you can nest providers and all values are available in the tree.
There was a problem hiding this comment.
added a short section in the docs
Deploying gensx with
|
| Latest commit: |
21ee570
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://d95a0d12.gensx.pages.dev |
| Branch Preview URL: | https://derek-concepts2.gensx.pages.dev |
There was a problem hiding this comment.
I think we need to clarify the difference between providers and context:
- Context: defines what can be shared (a type and a default value)
- Provider: sets the actual value for the context and takes care of passing it through the component tree to all children
gsx.useContext: how child components access context values from a provider
Is there a use case for using context without a provider?
Given all of this, I think it is worth asking ourselves whether it makes sense for there to be separate docs pages for these, or if we should just have a Context & Providers section.
|
I think combined pages would be better. You can't have one without the other, they aren't standalone. |
|
I was thinking something similar. I'll combine these into the same page. |
|
thanks for all of the feedback! Just pushed a combined version of the docs. Hopefully a decent improvement. |
There was a problem hiding this comment.
Overall, this looks good and I think we can ship it.
There are two things we didn't cover here:
- Mutating context
- When to use / not to use a context
For (1) I'm not sure how much there is to cover, and honestly we probably need to experiment a little bit more for ourselves to be certain. Thing could be tricky here as components are executed in parallel, so depending on the order of execution siblings may or may not see updates. I'm pretty sure that children will see updates.
For (2) it might be worth noting that using contexts makes components in your workflow less reusable since they depend on global state.
Honestly, I think we could leave both of these out for now until we have a little bit more experience ourselves, but thought I would mention.
Adds a conceptual doc on concepts and a simple example. Also makes minor tweaks to the basic concepts section on contexts.