docs: add friendly docs #38
Conversation
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @XiNiHa, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly enhances the solid-relay documentation by introducing a comprehensive set of guides. These new documents aim to provide a much friendlier and more detailed onboarding experience for users, covering fundamental concepts from initial setup to advanced data fetching patterns like fragments, mutations, and real-time subscriptions.
Highlights
- Getting Started Guide: Replaced the previous placeholder with a comprehensive "Getting Started" guide, covering installation, Relay Environment setup, and basic query usage.
- Fragments Documentation: Added a new guide detailing the usage of
createFragment,createRefetchableFragment, andcreatePaginationFragmentfor managing reusable query logic. - Queries Documentation: Introduced a new guide explaining
createLazyLoadQueryfor simple data fetching andcreatePreloadedQueryfor performance optimization through preloading. - Mutations Documentation: Added a dedicated guide for
createMutation, demonstrating how to perform data modifications on the server. - Subscriptions Documentation: Included a new guide on setting up the network for real-time updates and using
createSubscriptionto listen for live data changes.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
commit: |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #38 +/- ##
=======================================
Coverage 27.77% 27.77%
=======================================
Files 21 21
Lines 1422 1422
Branches 73 73
=======================================
Hits 395 395
Misses 1027 1027 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
solid-relay | d84d9a8 | Commit Preview URL Branch Preview URL |
Jul 24 2025, 01:28 PM |
There was a problem hiding this comment.
Code Review
This PR introduces valuable documentation for solid-relay. I've identified several inaccuracies in the examples related to createRefetchableFragment, createPaginationFragment, createPreloadedQuery, and createSubscription. The provided feedback aims to correct these examples for a better user experience.
| ## `createPreloadedQuery` | ||
|
|
||
| `createPreloadedQuery` allows you to start loading data before the component is rendered. This can improve performance by reducing the time it takes to display the data. | ||
|
|
||
| To use `createPreloadedQuery`, you first need to create a query loader. | ||
|
|
||
| ```typescript | ||
| // loaders.ts | ||
| import { createQueryLoader } from "solid-relay"; | ||
| import { graphql } from "relay-runtime"; | ||
| import type { UserQuery } from "./__generated__/UserQuery.graphql"; | ||
|
|
||
| export const userQuery = createQueryLoader<UserQuery>( | ||
| graphql` | ||
| query UserQuery($id: ID!) { | ||
| user(id: $id) { | ||
| name | ||
| } | ||
| } | ||
| ` | ||
| ); | ||
| ``` | ||
|
|
||
| Then you can use the `load` method of the query loader to start loading the data. | ||
|
|
||
| ```typescript | ||
| // index.tsx | ||
| import { userQuery } from "./loaders"; | ||
|
|
||
| userQuery.load({ id: "1" }); | ||
| ``` | ||
|
|
||
| Finally, you can use `createPreloadedQuery` to get the data in your component. | ||
|
|
||
| ```tsx | ||
| // User.tsx | ||
| import { Show } from "solid-js"; | ||
| import { createPreloadedQuery } from "solid-relay"; | ||
| import { userQuery } from "./loaders"; | ||
|
|
||
| const User = () => { | ||
| const query = createPreloadedQuery(userQuery); | ||
|
|
||
| return ( | ||
| <Show when={query()}> | ||
| {(data) => <p>{data().user.name}</p>} | ||
| </Show> | ||
| ); | ||
| }; | ||
| ``` | ||
|
|
||
| This will render the component with the preloaded data. If the data is not yet available, the component will suspend. |
There was a problem hiding this comment.
The createPreloadedQuery documentation is inaccurate and doesn't reflect the correct API usage of createQueryLoader and createPreloadedQuery.
createQueryLoaderreturns a tuple[queryReference, loadQuery, disposeQuery], not an object with a.loadmethod.createPreloadedQueryrequires two arguments: the GraphQL query node and the preloaded query reference. The example only passes one.
Corrected documentation:
## `createPreloadedQuery`
`createPreloadedQuery` allows loading data before component rendering, improving performance.
First, create a query loader:
```typescript
// loaders.ts
import { createQueryLoader } from "solid-relay";
import { graphql } from "relay-runtime";
import type { UserQuery } from "./__generated__/UserQuery.graphql";
export const UserQueryNode = graphql`
query UserQuery($id: ID!) {
user(id: $id) {
name
}
}
`;
export const [userQueryRef, loadUserQuery] =
createQueryLoader<UserQuery>(UserQueryNode);Use loadUserQuery to load data (e.g., in a router):
// index.tsx
import { loadUserQuery } from "./loaders";
loadUserQuery({ id: "1" });Then, use createPreloadedQuery in your component, passing both the query node and the query reference:
// User.tsx
import { Show } from "solid-js";
import { createPreloadedQuery } from "solid-relay";
import { UserQueryNode, userQueryRef } from "./loaders";
const User = () => {
const query = createPreloadedQuery(UserQueryNode, userQueryRef);
return (
<Show when={query()}>
{(data) => <p>{data().user.name}</p>}
</Show>
);
};| const CommentNotification = () => { | ||
| createSubscription<CommentNotificationSubscription>( | ||
| graphql` | ||
| subscription CommentNotificationSubscription($postId: ID!) { | ||
| commentAdded(postId: $postId) { | ||
| id | ||
| body | ||
| } | ||
| } | ||
| `, | ||
| { | ||
| variables: { | ||
| postId: "1", | ||
| }, | ||
| } | ||
| ); | ||
|
|
There was a problem hiding this comment.
The createSubscription function expects a single configuration object. The current example passes the GraphQL subscription and variables as separate arguments, which is incorrect.
createSubscription<CommentNotificationSubscription>({
subscription: graphql`
subscription CommentNotificationSubscription($postId: ID!) {
commentAdded(postId: $postId) {
id
body
}
}
`,
variables: {
postId: "1",
},
});
| graphql` | ||
| fragment Post_post on Post @refetchable(queryName: "PostRefetchQuery") { | ||
| title | ||
| body | ||
| } | ||
| `, | ||
| () => props.post | ||
| ); | ||
|
|
||
| return ( | ||
| <div> | ||
| <h2>{post().title}</h2> | ||
| <p>{post().body}</p> | ||
| <button onClick={() => refetch({ id: props.post.id })}>Refetch</button> | ||
| </div> | ||
| ); | ||
| }; |
There was a problem hiding this comment.
The example for createRefetchableFragment is missing the id field in the Post_post fragment. This field is necessary for Relay to identify the entity to refetch. Additionally, props.post is an opaque fragment reference and doesn't directly expose properties like id. Including id in the fragment allows solid-relay to automatically handle refetching with refetch({}).
fragment Post_post on Post @refetchable(queryName: "PostRefetchQuery") {
id
title
body
}
`,
() => props.post
);
return (
<div>
<h2>{post().title}</h2>
<p>{post().body}</p>
<button onClick={() => refetch({})}>Refetch</button>
</div>
| graphql` | ||
| fragment Comments_post on Post @refetchable(queryName: "CommentsPaginationQuery") { | ||
| comments(first: 10) @connection(key: "Comments_comments") { | ||
| edges { | ||
| node { | ||
| id | ||
| body | ||
| } | ||
| } | ||
| } | ||
| } | ||
| `, | ||
| () => props.post |
There was a problem hiding this comment.
The Comments_post fragment should include the id field on the Post type. This id is crucial for solid-relay to manage pagination and refetching correctly, as it's used to identify the connection.
fragment Comments_post on Post @refetchable(queryName: "CommentsPaginationQuery") {
id
comments(first: 10) @connection(key: "Comments_comments") {
edges {
node {
id
body
}
}
}
}
No description provided.