Skip to content

Commit

Permalink
[Hydrogen docs]: Improve wayfinding between framework, components, ho…
Browse files Browse the repository at this point in the history
…oks, and utilities docs (#1156)

* improve wayfinding from framework to components docs

* improve wayfinding from components to framework docs
  • Loading branch information
mcvinci authored Apr 29, 2022
1 parent c31623f commit f461d27
Show file tree
Hide file tree
Showing 32 changed files with 152 additions and 22 deletions.
4 changes: 4 additions & 0 deletions docs/components/framework/cookie.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,7 @@ The `Cookie` component is a server component. For more information about compone
## Related hooks

- [`useSession`](https://shopify.dev/api/hydrogen/hooks/framework/usesession)

## Related framework topics

- [Sessions](https://shopify.dev/custom-storefronts/hydrogen/framework/sessions)
4 changes: 4 additions & 0 deletions docs/components/framework/cookiesessionstorage.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,3 +51,7 @@ Don't use `CookieSessionStorage` if you expect to have more than 4kb of data wit
## Related hooks

- [`useSession`](https://shopify.dev/api/hydrogen/hooks/framework/usesession)

## Related framework topics

- [Sessions](https://shopify.dev/custom-storefronts/hydrogen/framework/sessions)
4 changes: 4 additions & 0 deletions docs/components/framework/fileroutes.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,7 @@ The `FileRoutes` component is a server component that renders inside `App.server

- [`Router`](https://shopify.dev/api/hydrogen/components/framework/router)
- [`Route`](https://shopify.dev/api/hydrogen/components/framework/route)

## Related framework topics

- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
4 changes: 4 additions & 0 deletions docs/components/framework/filesessionstorage.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,7 @@ Because `FileSessionStorage` relies on the file system, it shouldn't be used in
## Related hooks

- [`useSession`](https://shopify.dev/api/hydrogen/hooks/framework/usesession)

## Related framework topics

- [Sessions](https://shopify.dev/custom-storefronts/hydrogen/framework/sessions)
4 changes: 4 additions & 0 deletions docs/components/framework/link.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,7 @@ The `Link` component is a client component, which means that it renders on the c
## Related hooks

- [`useNavigate`](https://shopify.dev/api/hydrogen/hooks/framework/usenavigate)

## Related framework topics

- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
4 changes: 4 additions & 0 deletions docs/components/framework/memorysessionstorage.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,7 @@ The `MemorySessionStorage` component is a server component that renders inside `
## Related hooks

- [`useSession`](https://shopify.dev/api/hydrogen/hooks/framework/usesession)

## Related framework topics

- [Sessions](https://shopify.dev/custom-storefronts/hydrogen/framework/sessions)
4 changes: 4 additions & 0 deletions docs/components/framework/route.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,7 @@ The `Route` component is a server component that renders inside `App.server.jsx`

- [`FileRoutes`](https://shopify.dev/api/hydrogen/components/framework/fileroutes)
- [`Router`](https://shopify.dev/api/hydrogen/components/framework/router)

## Related framework topics

- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
4 changes: 4 additions & 0 deletions docs/components/framework/router.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,7 @@ The `Router` component is a server component that renders inside `App.server.jsx

- [`FileRoutes`](https://shopify.dev/api/hydrogen/components/framework/fileroutes)
- [`Route`](https://shopify.dev/api/hydrogen/components/framework/route)

## Related framework topics

- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
4 changes: 4 additions & 0 deletions docs/components/localization/localizationprovider.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,7 @@ The `LocalizationProvider` component is a server component, which means that it
## Related hooks

- [`useCountry`](https://shopify.dev/api/hydrogen/hooks/localization/usecountry)

## Related framework topics

- [Preloaded queries](https://shopify.dev/custom-storefronts/hydrogen/framework/preloaded-queries)
4 changes: 4 additions & 0 deletions docs/components/primitive/seo.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,3 +156,7 @@ The `page` type is an object with fields that correspond to the Storefront API's
}
}
```

## Related framework topics

- [SEO](https://shopify.dev/custom-storefronts/hydrogen/framework/seo)
2 changes: 1 addition & 1 deletion docs/framework/analytics.md
Original file line number Diff line number Diff line change
Expand Up @@ -442,5 +442,5 @@ describe('Google Analytics 4', () => {

## Next steps

- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Learn how to [configure queries to preload](https://shopify.dev/custom-storefronts/hydrogen/framework/preloaded-queries) in your Hydrogen app.
- Learn how to customize the output of [SEO-related tags](https://shopify.dev/custom-storefronts/hydrogen/framework/seo) in your Hydrogen client and server components.
12 changes: 9 additions & 3 deletions docs/framework/cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ export interface AllCacheOptions {

While rendering a page in your Hydrogen app, it’s common to make one or more sub-requests to Shopify or other third-party data sources within server components. You should use sub-request caching to keep pages loading quickly for end-users. All sub-request have the default `CacheSeconds` strategy.

The following example shows how to implement [`useShopQuery` for Shopify Storefront API queries](https://shopify.dev/api/hydrogen/hooks/global/useshopquery):
The following example shows how to implement [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery) for Shopify Storefront API queries:

{% codeblock file, filename: '/routes/my-products.server.jsx' %}

Expand All @@ -95,7 +95,7 @@ const {data} = useShopQuery({

{% endcodeblock %}

The following example shows how to implement [`fetchSync` for third-party requests](https://shopify.dev/api/hydrogen/hooks/global/fetchsync):
The following example shows how to implement [`fetchSync`](https://shopify.dev/api/hydrogen/hooks/global/fetchsync) for third-party requests:

{% codeblock file, filename: '/routes/my-products.server.jsx' %}

Expand Down Expand Up @@ -273,6 +273,12 @@ Full-page caching is powered completely by [`cache-control` headers on the Hydro
> Note:
> Oxygen caches HTML responses from Hydrogen at the network edge. However, your hosting provider or CDN might not cache HTML responses by default. Make sure to consult with your individual provider to enable HTML caching for your Hydrogen app.
## Related hooks

- [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery)
- [`fetchSync`](https://shopify.dev/api/hydrogen/hooks/global/fetchsync)
- [`useQuery`](https://shopify.dev/api/hydrogen/hooks/global/usequery)

## Next steps

- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Improve your app's loading performance with [streaming SSR and Suspense](https://shopify.dev/custom-storefronts/hydrogen/framework/streaming-ssr).
5 changes: 1 addition & 4 deletions docs/framework/css-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,6 @@ export default MyComponent() {

{% endcodeblock %}

> Tip:
> Explore an [example implementation of CSS Modules in GitHub](https://github.com/Shopify/hydrogen/tree/main/examples/css-modules).
## Next steps

- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Explore an [example implementation of CSS Modules in GitHub](https://github.com/Shopify/hydrogen/tree/main/examples/css-modules).
2 changes: 1 addition & 1 deletion docs/framework/environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,4 +98,4 @@ app.use(hydrogenMiddleware({/* ... */}))
## Next steps

- Get familiar with the [file-based routing system](https://shopify.dev/custom-storefronts/hydrogen/framework/routes) that Hydrogen uses.
- Learn how to [deploy your Hydrogen app](https://shopify.dev/custom-storefronts/hydrogen/deployment) to Oxygen and other runtimes.
4 changes: 4 additions & 0 deletions docs/framework/eslint.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,7 @@ To enable the Hydrogen configuration, add the `extends` property in your `.eslin
## Contributing to Hydrogen's ESLint plugin

Hydrogen's ESLint plugin is open source. Learn how to [contribute to the project on GitHub](https://github.com/Shopify/hydrogen/blob/main/packages/eslint-plugin/.github/CONTRIBUTING.md).

## Next steps

- Explore the [ESLint plugin](https://github.com/Shopify/hydrogen/tree/main/packages/eslint-plugin).
2 changes: 2 additions & 0 deletions docs/framework/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,4 +119,6 @@ If you need to change the server entry point, then make the following updates in

## Next steps

- Get familiar with the different [templates](https://shopify.dev/custom-storefronts/hydrogen/templates) that help you get started with Hydrogen.
- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Learn how to [deploy your Hydrogen app](https://shopify.dev/custom-storefronts/hydrogen/deployment) to Oxygen and other runtimes.
9 changes: 8 additions & 1 deletion docs/framework/preloaded-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,13 @@ If a query is being double loaded, then a warning displays in the server log. Th

![Shows a screenshot of query being double loaded](/assets/custom-storefronts/hydrogen/double-loaded-query.png)

## Related components and hooks

- [`localizationProvider`](https://shopify.dev/api/hydrogen/components/localization/localizationprovider)
- [`fetchSync`](https://shopify.dev/api/hydrogen/hooks/global/fetchsync)
- [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery)
- [`useQuery`](https://shopify.dev/api/hydrogen/hooks/global/usequery)

## Next steps

- Get familiar with the [file-based routing system](https://shopify.dev/custom-storefronts/hydrogen/framework/routes) that Hydrogen uses.
- Learn about the [analytics support](https://shopify.dev/custom-storefronts/hydrogen/framework/analytics) build into Hydrogen apps.
1 change: 0 additions & 1 deletion docs/framework/react-server-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,4 +147,3 @@ Although shared components have the most constraints, many components already ob

- Learn how to [work with React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/work-with-rsc).
- Improve your app's loading performance with [streaming SSR and Suspense](https://shopify.dev/custom-storefronts/hydrogen/framework/streaming-ssr).
- Get familiar with the [file-based routing system](https://shopify.dev/custom-storefronts/hydrogen/framework/routes) that Hydrogen uses.
23 changes: 19 additions & 4 deletions docs/framework/routes.md
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,7 @@ export default function MyProducts({response}) {

#### `response.doNotStream()`

By default, Hydrogen [streams SSR responses](https://github.com/reactwg/react-18/discussions/37). To customize a response, you need to tell Hydrogen that your server component plans to modify it in some way by calling `response.doNotStream()`:
By default, Hydrogen [streams SSR responses](https://shopify.dev/custom-storefronts/hydrogen/framework/streaming-ssr). To customize a response, you need to tell Hydrogen that your server component plans to modify it in some way by calling `response.doNotStream()`:

{% codeblock file %}

Expand Down Expand Up @@ -379,11 +379,11 @@ export default function CustomPage({response}) {

{% endcodeblock %}

Since this code lives inside a server component, you can use [`useShopQuery`](/api/hydrogen/hooks/global/useshopquery) to populate your [custom responses](#custom-responses) with Shopify data.
Since this code lives inside a server component, you can use [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery) to populate your [custom responses](#custom-responses) with Shopify data.

### Server props

In addition to `request` and `response` props, any props you manage with [`setServerProps`](/custom-storefronts/hydrogen/framework/server-props) is passed to each of your server components as props:
In addition to `request` and `response` props, any props you manage with [`setServerProps`](https://shopify.dev/custom-storefronts/hydrogen/framework/server-props) is passed to each of your server components as props:

{% codeblock file %}

Expand Down Expand Up @@ -664,6 +664,21 @@ await fetch('/api/views', {
{% endcodeblock %}
## Related components and hooks
- [`Link`](https://shopify.dev/api/hydrogen/components/framework/link)
- [`Router`](https://shopify.dev/api/hydrogen/components/framework/router)
- [`FileRoutes`](https://shopify.dev/api/hydrogen/components/framework/fileroutes)
- [`Route`](https://shopify.dev/api/hydrogen/components/framework/route)
- [`useNavigate`](https://shopify.dev/api/hydrogen/hooks/framework/usenavigate)
- [`useRouteParams`](https://shopify.dev/api/hydrogen/hooks/framework/userouteparams)
- [`useQuery`](https://shopify.dev/api/hydrogen/hooks/global/usequery)
- [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery)
- [`fetchSync`](https://shopify.dev/api/hydrogen/hooks/global/fetchsync)
## Next steps
- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Learn about how Hydrogen consumes data from different [sources](https://shopify.dev/custom-storefronts/hydrogen/data-sources).
- Learn how to manage [cache options](https://shopify.dev/custom-storefronts/hydrogen/framework/cache) for Hydrogen apps.
- Improve your app's loading performance with [streaming SSR and Suspense](https://shopify.dev/custom-storefronts/hydrogen/framework/streaming-ssr).
- Learn how to [manage your server props](https://shopify.dev/custom-storefronts/hydrogen/framework/server-props) during your development process.
6 changes: 5 additions & 1 deletion docs/framework/seo.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,10 @@ The following limitations and considerations apply to the [XML sitemap](https://

- By default, the sitemap uses the [`onlineStoreUrl`](https://shopify.dev/api/storefront/latest/objects/Product) field from the Storefront API as the URL. It falls back to the Demo Store template URL structure, which is based on resource's handle.

## Related components

- [`Seo`](https://shopify.dev/api/hydrogen/components/primitive/seo)

## Next steps

- Get familiar with the [file-based routing system](https://shopify.dev/custom-storefronts/hydrogen/framework/routes) that Hydrogen uses.
- Learn about the [analytics support](https://shopify.dev/custom-storefronts/hydrogen/framework/analytics) build into Hydrogen apps.
8 changes: 6 additions & 2 deletions docs/framework/server-props.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Server props
description: Learn how to manage your server props during your development process.
---

As you build your Hydrogen app with [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), you'll likely need to update `props` on the server. Sharing data between the client and server is important for common tasks, like [page routing](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components/work-with-rsc#sharing-data-between-client-and-server).
As you build your Hydrogen app with [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), you'll likely need to update `props` on the server. Sharing data between the client and server is important for common tasks, like [page routing](https://shopify.dev/custom-storefronts/hydrogen/framework/routes).

This guide describes how to manage server props during your development process.

Expand Down Expand Up @@ -85,7 +85,11 @@ export default function ProductSelector({selectedProductId}) {

When the user navigates to a new page in your app, the server props will reset. This is important because if the user navigates to another product, then the selected variant of the previous product shouldn't apply to the new product page.

## Related hooks

- [`useServerProps`](https://shopify.dev/api/hydrogen/hooks/global/useserverprops)

## Next steps

- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Learn how to interact with the [`useServerProps`](https://shopify.dev/api/hydrogen/hooks/global/useserverprops) hook.
- Learn how to [work with React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/work-with-rsc).
9 changes: 8 additions & 1 deletion docs/framework/sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,14 @@ export async function api(request, {session}) {

Hydrogen provides a [`Cookie`](https://shopify.dev/api/hydrogen/components/framework/cookie) component for building your own custom cookie and session implementations. All [Hydrogen session storage mechanisms](https://shopify.dev/custom-storefronts/hydrogen/framework/sessions#types-of-session-storage) use the same configuration options as `Cookie`.

## Related components and hooks

- [`Cookie`](https://shopify.dev/api/hydrogen/components/framework/cookie)
- [`CookieSessionStorage`](https://shopify.dev/api/hydrogen/components/framework/cookiesessionstorage)
- [`MemorySessionStorage`](https://shopify.dev/api/hydrogen/components/framework/memorysessionstorage)
- [`FileSessionStorage`](https://shopify.dev/api/hydrogen/components/framework/filesessionstorage)
- [`useSession`](https://shopify.dev/api/hydrogen/hooks/framework/usesession)

## Next steps

- Learn how to manage your [server props](https://shopify.dev/custom-storefronts/hydrogen/framework/server-props) during your development process.
- Get familiar with the [file-based routing system](https://shopify.dev/custom-storefronts/hydrogen/framework/routes) that Hydrogen uses.
1 change: 1 addition & 0 deletions docs/framework/static-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,4 @@ You should only import assets, such as styles or images, from [client components
## Next steps

- Learn about [React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/react-server-components), an opinionated data-fetching and rendering workflow for React apps.
- Learn how to [deploy your Hydrogen app](https://shopify.dev/custom-storefronts/hydrogen/deployment) to Oxygen and other runtimes.
3 changes: 1 addition & 2 deletions docs/framework/third-party-dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,7 @@ export default defineConfig({
> Tip:
> If you find that a dependency is being optimized when it shouldn't, then you can try adding the dependency to `optimizeDeps.exclude` to see if it fixes the issue.
## More help
## Next steps

- Learn more about dependency pre-bundling and optimization in [Vite](https://vitejs.dev/guide/dep-pre-bundling.html#dependency-pre-bundling).

- [Check this GitHub discussion](https://github.com/Shopify/hydrogen/discussions/93) to see if another developer has the same issue or report a new issue to Hydrogen maintainers.
9 changes: 8 additions & 1 deletion docs/framework/work-with-rsc.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,14 @@ export default function App() {
{% endcodeblock %}
## Related hooks
- [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery)
- [`fetchSync`](https://shopify.dev/api/hydrogen/hooks/global/fetchsync)
- [`useQuery`](https://shopify.dev/api/hydrogen/hooks/global/usequery)
- [`useServerProps`](https://shopify.dev/api/hydrogen/hooks/global/useserverprops)
## Next steps
- Improve your app's loading performance with [streaming SSR and Suspense](https://shopify.dev/custom-storefronts/hydrogen/framework/streaming-ssr).
- Get familiar with the [file-based routing system](https://shopify.dev/custom-storefronts/hydrogen/framework/routes) that Hydrogen uses.
- Learn about how Hydrogen consumes data from different [sources](https://shopify.dev/custom-storefronts/hydrogen/data-sources).
4 changes: 4 additions & 0 deletions docs/hooks/framework/usenavigate.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,7 @@ The `useNavigate` hook returns the following values:
## Related components

- [`Link`](https://shopify.dev/api/hydrogen/components/framework/link)

## Related framework topics

- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
4 changes: 4 additions & 0 deletions docs/hooks/framework/userouteparams.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,7 @@ The `useRouteParams` hook returns an object with key values for each matching ro
## Related hooks

- [`useNavigate`](https://shopify.dev/api/hydrogen/hooks/framework/usenavigate)

## Related framework topics

- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
4 changes: 4 additions & 0 deletions docs/hooks/framework/usesession.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,7 @@ The `useSession` hook returns all data within the current session. The return ty
- [`FileSessionStorage`](https://shopify.dev/api/hydrogen/components/framework/filesessionstorage)
- [`CookieSessionStorage`](https://shopify.dev/api/hydrogen/components/framework/cookiesessionstorage)
- [`MemorySessionStorage`](https://shopify.dev/api/hydrogen/components/framework/memorysessionstorage)

## Related framework topics

- [Sessions](https://shopify.dev/custom-storefronts/hydrogen/framework/sessions)
7 changes: 7 additions & 0 deletions docs/hooks/global/fetchsync.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,3 +151,10 @@ The following considerations apply to `fetchSync` in server and client component

- [`useShopQuery`](https://shopify.dev/api/hydrogen/hooks/global/useshopquery)
- [`useQuery`](https://shopify.dev/api/hydrogen/hooks/global/usequery)

## Related framework topics

- [Caching](https://shopify.dev/custom-storefronts/hydrogen/framework/cache)
- [Preloaded queries](https://shopify.dev/custom-storefronts/hydrogen/framework/preloaded-queries)
- [Routes](https://shopify.dev/custom-storefronts/hydrogen/framework/routes)
- [Working with React Server Components](https://shopify.dev/custom-storefronts/hydrogen/framework/work-with-rsc)
Loading

0 comments on commit f461d27

Please sign in to comment.