@graphcommerce/docs 4.4.3 → 4.5.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## 4.5.2
+
+### Patch Changes
+
+- [#1354](https://github.com/graphcommerce-org/graphcommerce/pull/1354) [`90fa8d8b9`](https://github.com/graphcommerce-org/graphcommerce/commit/90fa8d8b90e2a3b33cdbb178a87094888c7befdd) Thanks [@ErwinOtten](https://github.com/ErwinOtten)! - Small fixes to docs
+
+## 4.5.1
+
+### Patch Changes
+
+- [#1347](https://github.com/graphcommerce-org/graphcommerce/pull/1347) [`31f463d5c`](https://github.com/graphcommerce-org/graphcommerce/commit/31f463d5c2edff45911b63b1d89e5857244c1754) Thanks [@ErwinOtten](https://github.com/ErwinOtten)! - Upgrading
+
+## 4.5.0
+
+### Minor Changes
+
+- [#1341](https://github.com/graphcommerce-org/graphcommerce/pull/1341) [`a06c86706`](https://github.com/graphcommerce-org/graphcommerce/commit/a06c86706c8b76ce91cfa1e526fe16aa20c53991) Thanks [@paales](https://github.com/paales)! - Added upgrade instructions
+
+### Patch Changes
+
+- [#1338](https://github.com/graphcommerce-org/graphcommerce/pull/1338) [`a8886ce4c`](https://github.com/graphcommerce-org/graphcommerce/commit/a8886ce4c059e85b83158b4bc1d8e2f04626d49f) Thanks [@paales](https://github.com/paales)! - Docs improvements
+
 ## 4.4.3
 
 ### Patch Changes

package/framework/deployment.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Deploy a Graphcommerce app with Vercel
 
 Congratulations, you are ready to deploy your GraphCommerce storefront to

package/framework/environment-variables.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Environment Variables
 
 This guide describes how to store environment variables in your GraphCommerce

package/framework/graphcms.md

@@ -2,11 +2,15 @@
 menu: GraphCMS
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # GraphCMS
 
 GraphCMS is integrated as a Content Management System. It is used to store all

package/framework/icons.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Icons
 
 The GraphCommerce UI looks clean and minimalistic due to the use of icons. This

package/framework/readme.md

@@ -2,11 +2,15 @@
 menu: Overview
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # GraphCommerce framework overview
 
 GraphCommerce is a front-end framework used for building headless Magento

package/framework/static-generation.md

@@ -6,11 +6,15 @@ metaDescription:
   Generation for Magento nextjs PWA out-of-the-box.'
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Static Site Generation (SSG) in GraphCommerce
 
 Pages that export a function called getStaticProps, will pre-render at

package/framework/troubleshooting.md

@@ -1,8 +1,12 @@
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Troubleshouting
 
 ## Common build errors

package/getting-started/create.md

@@ -65,14 +65,13 @@ https://user-images.githubusercontent.com/1251986/158647122-dc57002f-a9c2-4661-a
 
 ### Download the example
 
-1. `git clone git@github.com:graphcommerce-org/graphcommerce.git graphcommerce`
+1. `git clone git@github.com:graphcommerce-org/graphcommerce.git`
 2. `mkdir my-project`
 3. `cp -R graphcommerce/examples/magento-graphcms/. my-project`
-4. `rm -rf graphcommerce`
-5. `cd my-project`
-6. `cp -R .env.example .env`
-7. `rm CHANGELOG.md && touch CHANGELOG.md`
-8. `rm -rf node_modules && rm -rf .next`
+4. `cd my-project`
+5. `cp -R .env.example .env`
+6. `rm CHANGELOG.md`
+7. `rm -rf node_modules && rm -rf .next`
 
 Edit /package.json. Delete `"scripts": {...}` and rename `scripts_local` to
 `scripts`:
@@ -99,7 +98,7 @@ Edit /package.json. Delete `"scripts": {...}` and rename `scripts_local` to
 To order to be able to connect your GraphCommerce app to your Magento backend
 and/or GraphCMS project, you'll need:
 
-- Magento 2.4.3 - Clean install, or a production or development environment
+- Magento 2.4.3 - Clean install, a production or a development environment
 - GraphCMS - A GraphCMS project with the required schema.
   [Clone the demo GraphCMS project ↗](https://app.graphcms.com/clone/caddaa93cfa9436a9e76ae9c0F34d257)
   as your starting point.
@@ -142,7 +141,7 @@ added as a result, with the exception of the first option in the list.
 ### Remove unused PSP's
 
 The example has Payment Service Providers integrated (Mollie, Braintree). Remove
-the ones you don't want to use.
+the ones your Magento backend doesn't support.
 
 - Remove `"@graphcommerce/[psp]"` from package.json
 - Remove all [psp] references from `pages/checkout/payment.tsx`
@@ -156,7 +155,10 @@ the ones you don't want to use.
 Visit the development environment running at http://localhost:3000  
 Visit the GraphQL Playground running at http://localhost:3000/api/graphql
 
-> No success? Refer to [common build errors](../framework/troubleshooting.md)
+> No success? Refer to [common build errors](../framework/troubleshooting.md) or
+> ask your question in the public
+> [Slack community ↗](https://join.slack.com/t/graphcommerce/shared_invite/zt-11rmgq1ad-F~0daNtKcSvtcC4eQRzjeQ)
+> chat
 
 ## Next steps
 

package/getting-started/graphcms-component.md

@@ -3,11 +3,15 @@ menu: 5. Build a GraphCMS component
 metaTitle: Build a GraphCMS component
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Build a GraphCMS component
 
 Previously, you created a GraphCommerce app and started building a custom
@@ -45,7 +49,7 @@ frontend React framework that uses Next.js for server-side rendering.
 
 <figure>
 
-![Adding a Single line text field]()
+![Adding a Single line text field](https://user-images.githubusercontent.com/1251986/159904004-cf774bd1-da01-4478-ac6e-b1567f9bafc7.png)
 
   <figcaption>Adding a Single line text field called "Identity"</figcaption>
 </figure>

package/getting-started/header.md

@@ -3,11 +3,15 @@ menu: 3. Build a custom header
 metaTitle: Build a custom header
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Build a custom header in GraphCommerce
 
 Previously, you created a GraphCommerce app and started building your custom
@@ -101,8 +105,8 @@ https://user-images.githubusercontent.com/1251986/154979091-89c72d68-c62f-451c-a
 
 ### Replace Search input with Search Fab
 
-- In /components/Layout/LayoutFull.tsx, replace
-  `<SearchButton onClick={onSearchStart} label=' ' />` with:
+- In /components/Layout/LayoutFull.tsx, replace `<SearchLink href='/search' />`
+  with:
 
 ```tsx
 <PageLink href='/search' passHref>
@@ -144,11 +148,6 @@ https://user-images.githubusercontent.com/1251986/154979091-89c72d68-c62f-451c-a
 
 - Make a copy of /node_modules/@graphcommerce/next-ui/LayoutParts/MenuFab.tsx
   and move it to the directory /components/Layout/MenuFab.tsx
-- In /components/Layout/MenuFab.tsx, change
-  `const MotionDiv = styled(m.div)({})` to:
-  ```ts
-  const MotionDiv = styled('div')({})
-  ```
 - Remove the `style={{...}}` prop from both the `<MotionDiv>` components to
   remove the Fab scroll animation
 - Remove `const { opacity, scale, shadowOpacity } = useFabAnimation()`

package/getting-started/pages.md

@@ -3,11 +3,15 @@ menu: 4. Build pages
 metaTitle: Build pages
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Build pages in GraphCommerce
 
 Previously, you created a custom storefront and started customizing your
@@ -102,7 +106,6 @@ export const getStaticProps: GetPageStaticProps = async (context) => {
       ...(await page).data,
       apolloState: await conf.then(() => client.cache.extract()),
     },
-    revalidate: 60 * 20,
   }
 }
 ```
@@ -209,7 +212,6 @@ export const getStaticProps: GetPageStaticProps = async (context) => {
       ...(await page).data,
       apolloState: await conf.then(() => client.cache.extract()),
     },
-    revalidate: 60 * 20,
   }
 }
 ```

package/getting-started/readme.md

@@ -9,11 +9,15 @@ metaDescription:
   template for Magento storefronts'
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # GraphCommerce magento-graphcms example overview
 
 GraphCommerce offers a magento-graphcms example that provides an approachable

package/getting-started/start-building.md

@@ -3,11 +3,15 @@ menu: 2. Customize a storefront
 metaTitle: Customize a storefront
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # Start building a GraphCommerce custom storefront
 
 Previously, you [created a new GraphCommerce app](../getting-started/create.md).

package/getting-started/vscode.md

@@ -13,7 +13,7 @@ as GraphCommerce. Visual Studio Code is free and available on all platforms.
 This guide covers which useful VS Code extensions to install for an optimal
 development experience.
 
-Recommended extensions
+Required extensions
 
 - [ESLint ↗](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) -
   Linter tool for identifying and reporting on patterns in JavaScript
@@ -22,24 +22,18 @@ Recommended extensions
 - [GraphQL ↗](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) -
   Adds syntax highlighting, validation, hover information and autocompletion for
   graphql files
+- [Yaml ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
+
+Recommended extensions:
+
 - [DotENV ↗](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) -
   Adds support for dotenv file syntax
-- [JavaScript Booster ↗](https://marketplace.visualstudio.com/items?itemName=sburg.vscode-javascript-booster) -
-  Advanced JavaScript/TypeScript refactorings and commands
 - [gettext ↗](https://marketplace.visualstudio.com/items?itemName=mrorz.language-gettext) -
   Adds syntax highlight to po translation files
-
-Optional extentions
-
-- [Color Highlight ↗](https://marketplace.visualstudio.com/items?itemName=naumovs.color-highlight)
-- [Material Theme ↗](https://marketplace.visualstudio.com/items?itemName=Equinusocio.vsc-material-theme)
-- [Material Theme Icons ↗](https://marketplace.visualstudio.com/items?itemName=Equinusocio.vsc-material-theme-icons)
-- [Output Colorizer ↗](https://marketplace.visualstudio.com/items?itemName=IBM.output-colorizer)
-- [Readability Check ↗](https://marketplace.visualstudio.com/items?itemName=jemcclin.readabilitycheck)
 - [Github Actions ↗](https://marketplace.visualstudio.com/items?itemName=me-dutour-mathieu.vscode-github-actions)
-- [MDX ↗](https://marketplace.visualstudio.com/items?itemName=silvenon.mdx)
-- [Markdown Preview Github Styling ↗](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles)
-- [Yaml ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
+- [JavaScript Booster ↗](https://marketplace.visualstudio.com/items?itemName=sburg.vscode-javascript-booster) -
+  Advanced JavaScript/TypeScript refactorings and commands
+- [Color Highlight ↗](https://marketplace.visualstudio.com/items?itemName=naumovs.color-highlight)
 
 ## Next steps
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "4.4.3",
+  "version": "4.5.2",
   "sideEffects": true,
   "devDependencies": {
     "@graphcommerce/prettier-config-pwa": "^4.0.2"

package/readme.md

@@ -1,6 +1,6 @@
 ---
 menu: Overview
-order: getting-started,framework, contributing, roadmap
+order: getting-started,framework, upgrading, contributing, roadmap
 metaTitle: Start React, Next.js Magento PWA development here - GraphCommerce
 metaDescription:
   'GraphCommerce is the open-source PWA Studio Magento 2 alternative.
@@ -8,11 +8,15 @@ metaDescription:
   extension.'
 ---
 
+<div data-nosnippet>
+
 > **Developer preview**  
 > This is a developer preview of GraphCommerce. The documentation will be
 > updated as GraphCommerce introduces
 > [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
 
+</div>
+
 # GraphCommerce
 
 GraphCommerce is a front-end framework used for building headless Magento
@@ -40,7 +44,7 @@ https://user-images.githubusercontent.com/1251986/154977573-4015e77c-43e7-481e-a
 - Nextjs
 - GraphQL
 - Mui
-- Apollo
+- Apollo Client
 - GraphQL Code Generator
 - Framer Motion
 

package/roadmap.md

@@ -11,7 +11,7 @@ The following overview contains the status of items on the GraphCommerce roadmap
 
 - [x] Framework updates (Mui5)
 - [x] Translation updates (DE, NL, ES, FR, IT)
-- [ ] Documentation and installation guide
+- [x] Documentation and installation guide
 - [ ] Quality improvements (Reduce components, naming)
 
 ## Planned

package/upgrading.md

@@ -0,0 +1,120 @@
+<div data-nosnippet>
+
+> **Developer preview**  
+> This is a developer preview of GraphCommerce. The documentation will be
+> updated as GraphCommerce introduces
+> [new features and refines existing functionality](https://github.com/graphcommerce-org/graphcommerce/releases).
+
+</div>
+
+# Upgrading
+
+This guide describes how to upgrade your GraphCommerce project files and its
+dependencies, while keeping your customizations.
+
+### After you've finished this upgrading guide, you'll have accomplished the following:
+
+- Created a changes.patch file and applied it to your project
+- Upgraded all dependencies to the latest version
+- Incorporated all the latest changes in your project, while keeping your
+  customizations
+
+## Step 1: Creating and applying a patch file
+
+1. In package.json, find your version:
+
+   ```json
+   // Example from package.json
+
+   {
+     "dependencies": {
+       //...
+       "@graphcommerce/next-ui": "^4.2.0"
+       //...
+     }
+   }
+   ```
+
+2. Download a fresh copy of the repository:
+
+   ```bash
+   git clone git@github.com:graphcommerce-org/graphcommerce.git upgrade
+   ```
+
+3. Navigate to the /upgrade directory you've just created. Run the following
+   command, but replace `OLD_VERSION` with your version of
+   `@graphcommerce/next-ui`:
+
+   ```bash
+   git diff --relative=examples/magento-graphcms "@graphcommerce/next-ui@OLD_VERSION" examples/magento-graphcms ':!examples/magento-graphcms/CHANGELOG.md' > changes.patch
+   ```
+
+4. Move the `changes.patch` file from the /upgrade directory to the root of your
+   project.
+
+5. Apply the patch to your project (It's recommended to apply changes on a new
+   branch):
+
+   ```bash
+   git apply --reject --ignore-whitespace --exclude=README.md changes.patch
+   ```
+
+## Step 2: Resolving issues
+
+### Resolving package.json issues
+
+If running the upgrade steps results in a `package.json.rej` file and the diff
+is large, it can be easier to manually update the `package.json` file.
+
+Compare your local /package.json with the example's
+`/upgrade/examples/magento-graphcms/package.json` you just downloaded and:
+
+1. Replace your local `dependencies` with the example's `dependencies`. Keep any
+   additional installed local dependencies and
+   [remove PSP's](./getting-started/create.md#remove-unused-psps) your backend
+   doesn't support.
+2. Replace your local `devDependencies` with the example's `devDependencies`
+3. Replace your local `scripts` with the example's `scripts_local`
+
+After updating the package.json file, run the following to install the latest
+packages:
+
+- `rm yarn.lock && yarn` Remove lock and install the dependencies
+- `yarn codegen` Converts all .graphql files to typescript files
+- `yarn dev` Run the app
+
+### Resolving diff issues
+
+When you run `git apply ...` (step 4), git will try and apply all the diffs from
+the patch file to your project files. When applying a diff fails, a
+[reject ↗](https://git-scm.com/docs/git-apply#Documentation/git-apply.txt---reject)
+`.rej` file will be created for _each_ file that could not be upgraded.
+
+It can very well be that some files can't be updated automatically, because of
+modifications you made. The CLI will show you the location of these files, as
+well as the number of hunks:
+
+```
+Applying patch pages/_app.tsx with 2 rejects...
+Rejected hunk #1.
+Rejected hunk #2.
+```
+
+The suggested changes have to be reviewed _manually_ (a diff tool can provide
+insight, but won't be able to apply diffs). Manually apply the suggested changes
+you want. Discard the .rej files of the suggested changes you don't want. Before
+you commit, make sure to delete all the .rej files:
+
+```bash
+find . -type f -name '*.rej' -delete
+```
+
+After resolving the diff issues, run and validate your local environment:
+
+- `yarn codegen` should run without errors
+- `yarn tsc:lint` should run without errors
+- `yarn dev` should run without errors
+
+## Next steps
+
+- Learn how to [contribute to GraphCommerce](./contributing.md)