chore(Coder plugin): Create guide for working with the Coder SDK #133
Conversation
|
@Kira-Pilot Updated the READMEs: there's two main files now:
There are a lot more files changed compared to before, but they're all basically file/property renames/reorganization to make things more clear Can you let me know if the new READMEs feel a bit more scrutible? |
| 1. If querying data, prefer `useCoderQuery`. It automatically wires up all auth logic to React Query (which includes pausing queries if the user is not authenticated). It also lets you access the Coder API via its query function. `useQuery` is also a good escape hatch if `useCoderQuery` doesn't meet your needs, but it requires more work to wire up correctly. | ||
| 2. If mutating data, you will need to call `useMutation`, `useQueryClient`, and `useCoderApi` in tandem\*. The plugin exposes a `CODER_QUERY_KEY_PREFIX` constant that you can use to group all Coder queries together. | ||
|
|
||
| We highly recommend **not** fetching with `useState` + `useEffect`, or with `useAsync`. Both face performance issues when trying to share state. See [ui.dev](https://www.ui.dev/)'s wonderful [_The Story of React Query_ video](https://www.youtube.com/watch?v=OrliU0e09io) for more info on some of the problems they face. |
There was a problem hiding this comment.
Any reason we have to include this disclaimer? Seems like general React knowledge, rather than Coder plugin specific knowledge.
There was a problem hiding this comment.
I agree in principle, but considering that part of the reason why I brought in RQ in the first place was to fight some of Backstage's design decisions, I'm not sure if infrastructure engineers who are trying to get their React UI working would be aware of the issues. Especially since it's going against Backstage's official recommendations
There was a problem hiding this comment.
That makes sense! Could we just move it after the meat of the examples then?
There was a problem hiding this comment.
Honestly, I would expect a good chunk of plugin users not to be super seasoned with React. So I'm not sure if we want to get rid of the disclaimer, or if it'd be better to reword it
| - `useQuery` - Query and cache data | ||
| - `useMutation` - Perform mutations on an API resource | ||
| - `useQueryClient` - Coordinate queries and mutations |
There was a problem hiding this comment.
Seems like basic use cases for fetching don't need these RQ hooks but they're the first thing we talk about.
WDYT about moving your example code snippets up to the top here alongside your hook explanations so users can immediately see how they might use what you've built?
This could look something like:
### Available hooks
We've exposed a few hooks to get you started building your own Coder components:
- `useCoderApi` - Exposes an object with all available Coder API methods. For the most part, there is no exposed state on this object; you can consider it a "function bucket".
- `useCoderAuth` - Provides methods and state values for interacting with your current Coder auth session from within Backstage.
- `useCoderQuery` - a convenience hook that simplifies wiring up `useQuery`, `useCoderApi`, and `useCoderAuth`.
// Query Example:
// Mutation Example:
Note that we use [React Query/TanStack Query v4](https://tanstack.com/query/v4/docs/framework/react/overview) in the above examples. When querying, RQ's `useQuery` hook is also a good escape hatch if `useCoderQuery` doesn't meet your needs, but it requires more work to wire up correctly.
The plugin exposes a `CODER_QUERY_KEY_PREFIX` constant that you can use to group all Coder queries together; read more here(link to your query constant section).
There was a problem hiding this comment.
Yeah, I see what you mean. I went ahead and reorganized the hooks section, and added some bite-sized examples
| </CoderProvider>; | ||
| ``` | ||
|
|
||
| ### Grouping queries with the Coder query key prefix |
There was a problem hiding this comment.
Should we move this up so its closer to the hook section
| @@ -1,11 +1,18 @@ | |||
| # Plugin API Reference – Coder for Backstage | |||
|
|
|||
| For users who need more information about how to extend and modify the Coder plugin. For general setup, please see our main [README](../README.md). | |||
| The Coder plugin for Backstage does follow semantic versioning. | |||
There was a problem hiding this comment.
I think this is an important sentence, but should not necessarily be the first sentence of this doc. Can we change it to something that explains what the reader will learn from reading this doc? e.g.
Learn how to build custom Backstage functions and components that use the Coder API
Closes #112
Changes made
Things left to do
Notes