@graphcommerce/docs 9.0.0-canary.107 → 9.0.0-canary.108

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## 9.0.0-canary.108
+
+### Patch Changes
+
+- [#2439](https://github.com/graphcommerce-org/graphcommerce/pull/2439) [`6061226`](https://github.com/graphcommerce-org/graphcommerce/commit/60612265466e4c508a2d3f478ff679251e7819de) - Moved to serwist for service workers ([@paales](https://github.com/paales))
+
 ## 9.0.0-canary.107
 
 ## 9.0.0-canary.106

package/framework/caching.md

@@ -152,22 +152,33 @@ cache.
 
 The service worker caches:
 
-- [static fonts](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L28)
-- [static images](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L39)
-- [\_next/image](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L50)
-- [js](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L85)
+- [static fonts](https://github.com/serwist/serwist/blob/main/packages/next/src/index.worker.ts#L27):
+  Google fonts and webfonts with StaleWhileRevalidate strategy
+- [static images](https://github.com/serwist/serwist/blob/main/packages/next/src/index.worker.ts#L64):
+  jpg, jpeg, gif, png, svg, ico, webp with StaleWhileRevalidate strategy
+- [\_next/image](https://github.com/graphcommerce-org/graphcommerce/blob/main/packages/service-worker/runtimeCaching.ts#L6):
+  Custom implementation with StaleWhileRevalidate and nextImagePlugin
+- js and css files: Only for files outside of `_next/static` with
+  StaleWhileRevalidate strategy
+
+Notable differences from previous implementation:
+
+- All `_next/static` files (js, css) are excluded from runtime caching as they
+  are handled by the precache mechanism
+- Cross-origin requests use NetworkOnly strategy instead of NetworkFirst
+- Image caching has been optimized with custom configuration for better
+  performance
 
 Note: When a new deployment is made, the service worker is updated. This means
 that all previous caches are cleared and new caches are created.
 
 It does not cache:
 
-- [\_next/data](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L107):
-  Although it looks like it does, the regex is actually wrong and it does not
-  cache anything.
-- [pages](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L152)
+- [\_next/data](https://github.com/ducanh-99/serwist/blob/main/packages/next/src/index.worker.ts#L137):
+  Uses NetworkFirst strategy to ensure fresh data
+- [pages](https://github.com/ducanh-99/serwist/blob/main/packages/next/src/index.worker.ts#L152):
   Uses NetworkFirst strategy, which means it will always try to fetch the
-  resource from the network first, and only if that fails it will use the cache.
+  resource from the network first, and only if that fails it will use the cache
 
 ## Cache invalidation limitations
 

package/getting-started/create.md

@@ -8,10 +8,10 @@ metaTitle: Getting started with GraphCommerce
 In this guide, you will set up a GraphCommerce app locally, allowing you to
 start building.
 
-### Requirements
+### Preparations
 
-- Lixux, MacOS or WSL2
-- Install and use node 16/18: `nvm install 16` or `nvm use 16`
+- MacOS, Windows with WSL2 or Linux
+- Install and use node 20: `nvm install 20` or `nvm use 20`
 - Install yarn: `corepack enable`
 
 ## Step 1: Create a GraphCommerce app
@@ -26,19 +26,34 @@ mkdir my-project
 # Create project folder
 ```
 
+There are a few starting points to choose from with or without Hygraph:
+
+Option 1: Only Magento Open Source:
+
 ```bash
-cp -R graphcommerce/examples/magento-graphcms/. my-project && rm -rf graphcommerce && cd my-project
-# Copy example, delete repo, navigate to project folder
+cp -R graphcommerce/examples/magento-magento-open-source/. my-project && cd my-project
 ```
 
+Option 2: Magento Open Source + Hygraph:
+
+```bash
+cp -R graphcommerce/examples/magento-graphcms/. my-project && cd my-project
+```
+
+Option 3: Adobe Commerce:
+
+Please contact us for more information to get access to the Adobe Commerce
+starting point.
+
 ## Step 2: Configure API keys (optional)
 
 Duplicate and rename the configuration example file to:
 `graphcommerce.config.js` and configure the following:
 
-- `magentoEndpoint` [?](../framework/config.md#magentoendpoint-string)
-- `hygraphEndpoint` [?](../framework/config.md#hygraphendpoint-string)
-- `magentoStoreCode` [?](../framework/config.md#magentostorecode-string)
+- `magentoEndpoint` [?](../framework/config.md#magentoendpoint-string-required)
+- `hygraphEndpoint` [?](../framework/config.md#hygraphendpoint-string-required)
+- `magentoStoreCode`
+  [?](../framework/config.md#magentostorecode-string-required)
 
 > magentoStoreCode
 >
@@ -55,11 +70,12 @@ Duplicate and rename the configuration example file to:
 
 ### Requirements
 
-- Magento version 2.4.3 or higher - Clean install, a production or a development
-  environment
+- Magento version 2.4.5 or higher - Clean install, a production or a development
+  environment (technically 2.4.3 and 2.4.4 also work, but in practice important
+  bugfixes have been made in the latest versions.)
 - Hygraph - A project with the required schema.
   [Clone ↗](https://app.hygraph.com/clone/caddaa93cfa9436a9e76ae9c0f34d257?name=GraphCommerce%20Demo)
-  the schema as your starting point.
+  the schema as your starwting point.
 
 ## Step 3: Start the app
 

package/getting-started/improving-core-web-vitals.md

@@ -88,7 +88,7 @@ persisted, except for pruned data (see
 
 Since this phase is late, do not use the result of non-session specific queries
 for the initial render. This also causes rerenders of the components causing all
-vitals to be affected.s
+vitals to be affected.
 
 Solution: Move data fetching to the `getStaticProps` or `getServerSideProps`
 functions. That can be a bit unergonomic, in that case move the data fetching
@@ -107,6 +107,74 @@ and it's
 and
 [mesh configuration plugin](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-graphql/plugins/meshConfigAttrValue.ts).
 
+## Prevent components outside of the viewport from unnecessarily hydrating
+
+To keep the Hydration phase as short as possible, it's a good idea to postpone
+the hydration of (heavy) components that are outside of the viewport until they
+are needed. By using `<LazyHydrate>`, the component can be hydrated either
+manually, by setting the `hydrated` prop to true or automatically by the
+IntersectionObserver inside `<LazyHydrate>` (as soon as the component comes into
+view). It is recommended to set an estimated height value on the `height` prop.
+This will reserver space for the component, when the page is loaded clientside.
+This is to prevent multiple `LazyHydrate` components below each other from
+intersecting all at once (as they do not have any HTML, and thus any height,
+when loaded clientside). This height does not need to be exact.
+
+The IntersectionObserver method of hydrating should never be used for components
+that are inside the viewport on pageload, as it requires JS and is asynchronous.
+When items are rendered in a loop and the first few items are inside the
+viewport, these should be set to `hydrated={true}` based on the index of the
+loop.
+
+Example 1:
+
+```tsx
+import { LazyHydrate } from '@graphcommerce/next-ui'
+
+function MyLayout() {
+  return (
+    <MyComponentAboveTheFold>
+      Immediately hydrated
+    </MyComponentAboveTheFold>
+
+    <LazyHydrate hydrated={true}>
+      <MyComponentAboveTheFold>
+        Immediately hydrated
+      </MyComponentAboveTheFold>
+    </<LazyHydrate>
+
+    <LazyHydrate height={500}>
+      <MyExpensiveComponentBelowTheFold>
+        Only hydrated when scrolled into view
+      </MyExpensiveComponentBelowTheFold>
+    </LazyHydrate>
+  )
+}
+```
+
+Example 2:
+
+```tsx
+export function MyItems(props) {
+  const { items, loadingEager = 2 } = props
+
+  return (
+    <>
+      {items.map((item, index) => (
+        // The first two items are hydrated immediately. Any items after that are hydrated on intersection
+        <LazyHydrate
+          key={item.id}
+          hydrated={index < loadingEager ? true : undefined}
+          height={500}
+        >
+          <MyComponent {...item} />
+        </LazyHydrate>
+      ))}
+    </>
+  )
+}
+```
+
 ## Conditionally render on mobile/desktop
 
 TLDR: Use the `<MediaQuery>` component instead of useMediaQuery or CSS
@@ -193,3 +261,95 @@ function MyLayout() {
   )
 }
 ```
+
+## Use Context + useState cautiously
+
+Contexts + useState should be used cautiously. When the state updates, it causes
+ALL components within the context provider to rerender, not just the components
+that use the context. When wrapping a lot of components inside a context, this
+can become very expensive.
+
+Solution for state that involves query data: Use Apollo Client cache, by using
+`useQuery` for data that is already fetched on the server and cached by Apollo.
+
+Solution for local state: use
+[Apollo Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)
+
+## Image resizing
+
+When using the Image component, the sizes prop should be set correctly so no
+unnecessarily large images are served. The prop accepts either a string (vw, px,
+calc(), etc) or an object with breakpoints and a string value. See the
+[prop type](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/image/components/Image.tsx#L176-L185)
+for all available options.
+
+Example:
+
+```tsx
+<Image
+  layout='fill'
+  alt={item.label}
+  src={item.url}
+  sizes={{
+    0: '100vw',
+    [theme.breakpoints.values.md]: '50vw',
+  }}
+/>
+```
+
+## Preventing a query waterfall
+
+When querying inside `getStaticProps`, only use `await` when the data is
+required for something else inside `getStaticProps`. Otherwise it should be
+awaited in the return statement. When a query is awaited immediately, it halts
+the code at that point until that query completes. Meaning any queries called
+after that will be called in serial. Awaiting all queries in the return
+statement allows the queries to be called in parallel.
+
+Example:
+
+```tsx
+// Bad, because each query needs to wait until the previous one is completed entirely before being fired
+export const getStaticProps: GetPageStaticProps = async (context) => {
+  // Query takes 100ms - code is halted until it finishes
+  const {data: queryOne} = await staticClient.query({ query: queryOneDocument })
+  // Query takes 100ms - code is halted until it finishes
+  const {data: queryTwo} = await staticClient.query({ query: queryTwoDocument })
+  // Query takes 100ms - code is halted until it finishes
+  const {data: queryThree} = await staticClient.query({ query: queryThreeDocument })
+
+
+  return {
+    props: {
+      ...queryOne
+      ...queryTwo
+      ...queryThree
+      // Total wait time 300ms
+    },
+  }
+}
+```
+
+```tsx
+// Good, because each query is fired in parallel and only awaited when each query is already running in the background
+export const getStaticProps: GetPageStaticProps = async (context) => {
+  // Query takes 100ms - but it runs in the background, code continues execution
+  const queryOne = staticClient.query({ query: queryOneDocument })
+  // Query takes 100ms - but it runs in the background, code continues execution
+  const queryTwo = staticClient.query({ query: queryTwoDocument })
+  // Query takes 100ms - but it runs in the background, code continues execution
+  const queryThree = staticClient.query({ query: queryThreeDocument })
+
+  return {
+    props: {
+      // Awaits query (100ms)
+      ...(await queryOne).data
+      // Awaits query, already finished in the background (0ms)
+      ...(await queryTwo).data
+      // Awaits query, already finished in the background (0ms)
+      ...(await queryThree).data
+      // Total wait time 100ms
+    },
+  }
+}
+```

package/package.json

@@ -2,10 +2,10 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "9.0.0-canary.107",
+  "version": "9.0.0-canary.108",
   "sideEffects": true,
   "peerDependencies": {
-    "@graphcommerce/prettier-config-pwa": "^9.0.0-canary.107"
+    "@graphcommerce/prettier-config-pwa": "^9.0.0-canary.108"
   },
   "prettier": "@graphcommerce/prettier-config-pwa"
 }

package/upgrading/graphcommerce-8-to-9.md

@@ -5,6 +5,9 @@ steps. Please follow the regular [upgrade steps first](./readme.md).
 
 1. ReactPlugin TypeScript definition is removed.
 2. Locales now require an explicit configuration.
+3. `@graphcommerce/graphcms-ui` is now `@graphcommerce/hygraph-ui`
+4. `@ducanh2912/next-pwa` replaced by `serwist`
+5. `next-sitemap` replaced by custom implementation
 
 ## 1. ReactPlugin TypeScript definition is removed
 
@@ -56,3 +59,14 @@ const config = {
 3. `@graphcommerce/graphcms-ui` is now `@graphcommerce/hygraph-ui`
 
 Replace all `@graphcommerce/graphcms-ui` with `@graphcommerce/hygraph-ui`.
+
+4. `@ducanh2912/next-pwa` replaced by `serwist`
+
+Any customizations made to the service worker should
+
+5. `next-sitemap` replaced by custom implementation.
+
+- pages/robots.txt.tsx
+- pages/sitemap/categories.xml.tsx
+- pages/sitemap/content.xml.tsx
+- pages/sitemap/products.xml.tsx