@graphcommerce/docs 3.1.4

package/content/framework/deployment.md

@@ -0,0 +1,56 @@
+> **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/ho-nl/m2-pwa/releases).
+
+# Deploy a Graphcommerce app with Vercel
+
+Congratulations, you are ready to deploy your GraphCommerce storefront to
+production. The fastest way to deploy your GraphCommerce app is with
+[Vercel ↗](https://vercel.com/).
+
+Vercel allows for automatic deployments on every branch push and merges onto the
+Production Branch of your GitHub project:
+
+- Login to Vercel, click the "New Project" button
+- Import your Git Repository. Use the search to type your project's name. If
+  it's not showing up, click the 'Configure Github App' to grant Vercel
+  repository access
+
+  <figure>
+    <img src="https://cdn-std.droplr.net/files/acc_857465/e62La4"/>
+  </figure>
+
+- Set the Environment Variables from your .env file:
+
+  ```bash
+  GRAPHCMS_URL=""
+  MAGENTO_ENDPOINT=""
+  IMAGE_DOMAINS=""
+  NEXT_PUBLIC_LOCALE_STORES=""
+  NEXT_PUBLIC_DISPLAY_INCL_TAX=""
+  ```
+
+- Vercel will auto assign a domain to your project. In this example, the Github
+  project repository name is `graphcommerce-example`, so the domain will be
+  `https://graphcommerce-example.vercel.app`. Add this domain as the GraphQL and
+  Public site URL Environment Variables:
+
+  ```bash
+  NEXT_PUBLIC_GRAPHQL_ENDPOINT="https://graphcommerce-example.vercel.app/api/graphql"
+  NEXT_PUBLIC_SITE_URL="https://graphcommerce-example.vercel.app/"
+  ```
+
+  <figure>
+  <img src="https://cdn-std.droplr.net/files/acc_857465/gkuuby"/>
+  </figure>
+
+- Hit the "Deploy" button
+- A custom domain can be configured in the Vercel Project Settings. Update the
+  `NEXT_PUBLIC_GRAPHQL_ENDPOINT` and `NEXT_PUBLIC_SITE_URL` variables
+  afterwards.
+
+## Next steps
+
+- Learn about [Static Generation (SSG)](../framework/static-generation.md) in
+  GraphCommerce

package/content/framework/environment-variables.md

@@ -0,0 +1,61 @@
+> **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/ho-nl/m2-pwa/releases).
+
+# Environment Variables
+
+This guide describes how to store environment variables in your GraphCommerce
+project.
+
+## How environment variables work
+
+You can store environment variables in the .env file in your GraphCommerce root
+directory. Any variable from .env files that aren't prefixed with `NEXT_PUBLIC`
+is treated as a server runtime variable. These variables are not exposed to the
+browser.
+
+Environment variables will be loaded into `process.env`, allowing you to use
+them in Next.js data fetching methods and API routes:
+
+```ts
+// /lib/graphql/GraphQLProvider.tsx
+
+// ...
+new HttpLink({
+  uri: process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT,
+  credentials: 'same-origin',
+})
+// ...
+```
+
+## Public variables
+
+Expose environment variables to the browser by prefixing with `NEXT_PUBLIC`.
+These variables can be accessed in any component:
+
+```bash
+# Google TagManager ID
+NEXT_PUBLIC_GTM_ID="GTM-000000"
+```
+
+```tsx
+// /node_modules/@graphcommerce/googleanalytics/components/GoogleAnalyticsScript.tsx
+
+export default function GoogleAnalyticsScript() {
+  const id = process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS
+
+  ...
+}
+```
+
+## Deployment Environment Variables
+
+When [deploying your GraphCommerce storefront](./deployment.md) to Vercel,
+Environment Variables can be configured in the Project Settings.
+
+## Next steps
+
+- Learn how to [deploy your GraphCommerce storefront](./deployment.md) to Vercel
+- Read more about
+  [Environment Variables in Next.js ↗](https://nextjs.org/docs/basic-features/environment-variables#loading-environment-variables)

package/content/framework/favicon.md

@@ -0,0 +1,38 @@
+# Favicon
+
+GraphCommerce offers a [magento-graphcms example](../getting-started/readme.md)
+that provides an approachable path to building GraphCommerce custom e-commerce
+storefront.
+
+Included in the magento-graphcms example, is a
+[well-founded implementation ↗](https://medium.com/web-dev-survey-from-kyoto/favicon-nightmare-how-to-maintain-sanity-7628bfc39918)
+for a correct favicon and touch icon.
+
+Favicons can be found in the /public directory:
+
+```txt
+/public/favicon.ico
+/public/favicon.svg
+/public/apple-touch-icon.png
+/public/manifest/favicon-512.png
+/public/manifest/favicon-192.png
+```
+
+## Replacing the favicon
+
+To replace the favicon with your own, simply replace the image files located in
+the /public and /public/manifest directories. Pay attention to the standardized
+["minimum safe zone ↗"](https://web.dev/maskable-icon/?utm_source=devtools#are-my-current-icons-ready)
+
+You can use the GraphCommerce
+[favicon sketch template ↗](https://drive.google.com/file/d/1tKiU54TgLd_sbd0tArpaqYdD9VYiYwwt/view?usp=sharing)
+to simplify the process of making correct favicons.
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/8wbzEN" />
+ <figcaption>Favicon sketch template</figcaption>
+</figure>
+
+## Next steps
+
+- Lear more about [Static file serving](../framework/static-file-serving.md)

package/content/framework/graphcms.md

@@ -0,0 +1,66 @@
+---
+menu: GraphCMS
+---
+
+> **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/ho-nl/m2-pwa/releases).
+
+# GraphCMS
+
+GraphCMS is integrated as a Content Management System. It is used to store all
+static content and provides a user-friendly interface for managing it.
+
+The [magento-graphcms example](./../getting-started/readme.md) offers a number
+of components to render this content in different ways, for example in the form
+of a page-wide hero banner, a list of USPs or grid of text columns.
+
+This guide covers how to configure GraphCMS and how to build rich content pages
+by adding GraphCMS content to pages.
+
+## Configuration
+
+To connect your GraphCommerce app to your GraphCMS project, you'll need a
+GraphCMS project with the required schema.
+[Clone the demo GraphCMS project](https://app.graphcms.com/clone/caddaa93cfa9436a9e76ae9c0F34d257)
+as your starting point. Update the variable in the /.env file:
+
+`GRAPHCMS_URL=""`  
+GraphCMS API URL. Once logged in, copy it from Project Settings > Api Access >
+Content API
+
+## Adding content to pages
+
+GraphCommerce uses Next.js
+[file-based routing ↗](https://nextjs.org/docs/routing/introduction), built on
+the concept of pages. When a file is added to the /pages directory, it's
+automatically available as a route. Magento category routes are handled by the
+`/pages/[...url].tsx` page.
+
+To add GraphCMS content to, for example, a category page, create a Page entry in
+GraphCMS and match the value of the URL field with the route of the page you
+wish to add content to.
+
+For example, the content of the 'men' Page entry in GraphCMS:
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/qv7IAn"/>
+</figure>
+
+Is used to add a`RowProduct (variant:Grid)` and a
+`RowProduct (variant:Backstory` component to: http://localhost:3000/men
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/1aSErQ" />
+  <figcaption>Content of the RowProduct (variant:Backstory component)</figcaption>
+</figure>
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/5Pkv37" />
+</figure>
+
+## Next steps
+
+- Learn how to
+  [build a custom GraphCMS component](../getting-started/graphcms-component.md)

package/content/framework/icons.md

@@ -0,0 +1,255 @@
+> **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/ho-nl/m2-pwa/releases).
+
+# Icons
+
+The GraphCommerce UI looks clean and minimalistic due to the use of icons. This
+guide covers how to customize the look of icons, how to use different icons in
+components and how to add your own.
+
+## Customizing icon styling
+
+All icons strokeWidths are dependent of the value of `shape`. To change the
+default strokeWidth, modify the value `theme.shape.strokeWidth` in
+/components/theme.ts:
+
+```ts
+// Example from /components/theme.ts
+
+import { svgIconStrokeWidth } from '@graphcommerce/next-ui'
+
+const createOverrides = (theme: Theme): Components => ({
+  // ... other component styling
+
+  IconSvg: {
+    variants: [
+      {
+        props: {},
+        style: {
+          strokeWidth: svgIconStrokeWidth(28, 148, 0.9, 0.4),
+        },
+      },
+    ],
+  },
+})
+```
+
+To override the default color for all icons:
+
+```ts
+// Example from /components/theme.ts
+
+const createOverrides = (theme: Theme): Components => ({
+  //... other component styling
+
+  IconSvg: {
+    variants: [
+      {
+        props: {},
+        style: ({ theme }) => ({
+          color: theme.palette.primary.main,
+        }),
+      },
+    ],
+  },
+})
+```
+
+Use the sx prop to customise the styling of an icon in a component:
+
+```tsx
+<IconSvg src={iconCustomerService} size='large' sx={{ strokeWidth: '0.8px' }} />
+```
+
+## Using a different icon from the icon pack
+
+To replace an icon in a component, update the import and src prop of the
+`IconSvg` component.
+
+In /components/Layout/LayoutFull.tsx:
+
+```tsx
+...
+import iconCustomerService from '@graphcommerce/next-ui'
+
+...
+return (
+  <IconSvg src={iconCustomerService} size='large' />
+)
+```
+
+Replace iconCustomerService with an icon of your choosing:
+
+```tsx
+...
+import iconSupport from '@graphcommerce/next-ui/icons/support.svg'
+
+...
+return (
+  <IconSvg src={iconSupport} size='large' />
+)
+```
+
+> All [Ikonate ↗](https://ikonate.com/) icons are included with GraphCommerce:
+>
+> ```txt
+> // Sample of icons in the directory /node_modules/@graphcommerce/next-ui/icons
+>
+> ...
+> └── bike.svg
+> └── bin.svg
+> └── bluetooth.svg
+> └── bolt.svg
+> └── book-opened.svg
+> └── book.svg
+> └── bookmark.svg
+> └── box-alt.svg
+> └── box-alt2.svg
+> └── box.svg
+> └── brightness.svg
+> ```
+
+## Override with the icon prop
+
+Some components offer a prop to override the icon. In
+/components/Layout/LayoutFull.tsx, you can add the `icon` prop to the
+`CustomerFab` component to change the icon:
+
+```tsx
+import iconUser from '@graphcommerce/next-ui/icons/user.svg'
+
+...
+<CustomerFab
+  guestHref='/account/signin'
+  authHref='/account'
+  icon={<IconSvg src={iconUser} size='large' />}
+/>
+```
+
+## Icon SVG specifications
+
+To use a custom icon that you design yourself, the icon must consist of paths
+without fills. The path must be wrapped in a `<symbol>` that has an attribute
+`id='icon'`:
+
+```svg
+// Example from /node_modules/@graphcommerce/next-ui/icons/chat.svg:
+
+<svg
+  role='img'
+  xmlns='http://www.w3.org/2000/svg'
+  width='48px'
+  height='48px'
+  aria-labelledby='chatIconTitle'
+  stroke='#2329D6'
+  stroke-width='1'
+  stroke-linecap='square'
+  stroke-linejoin='miter'
+  fill='none'
+  color='#2329D6'
+>
+  <title id='chatIconTitle'>Chat</title>
+  <symbol id='icon' viewBox='0 0 24 24'>
+    <path d='M8.82388455,18.5880577 L4,21 L4.65322944,16.4273939 C3.00629211,15.0013 2,13.0946628 2,11 C2,6.581722 6.4771525,3 12,3 C17.5228475,3 22,6.581722 22,11 C22,15.418278 17.5228475,19 12,19 C10.8897425,19 9.82174472,18.8552518 8.82388455,18.5880577 Z' />
+  </symbol>
+</svg>
+```
+
+Icons can be placed in the same directory as a page or component and can be
+imported from there (the `<IconSvg>` component will convert the relative path to
+an absolute path)
+
+```tsx
+...
+import customIcon from './my-custom-icon.svg'
+
+...
+return (
+  <IconSvg src={iconSucustomIconpport} size='large' />
+)
+```
+
+To use a custom icon in your component, follow the same steps as described in
+the [previous paragraph](#using-a-different-icon-from-the-icon-pack).
+
+> As a starting point, it's advised to open one of the included icons in your
+> design tool (for example, Sketch or Figma).
+
+## Using a different icon pack
+
+To override all or multiple icons with your own, add an icon override array to
+/theme.ts:
+
+```tsx
+// /components/theme.ts
+import { iconCart, iconChat } from '@graphcommerce/next-ui'
+import customCartIcon from './my-custom-cart-icon.svg'
+import customChatIcon from './my-custom-chat-icon.svg'
+
+// ...
+const createOverrides = (theme: Theme): Components => ({
+  //... other component styling
+
+  IconSvg: {
+    overrides: [
+      [iconCart, customCartIcon],
+      [iconChat, customChatIcon],
+    ],
+  },
+})
+// ...
+```
+
+All icons must meet the svg specifications as described above
+
+<details>
+<summary>List of icons used</summary>
+
+iconSearch  
+iconPerson  
+iconChevronDown  
+iconChevronLeft  
+iconChevronRight  
+iconChevronUp  
+iconAddresses  
+iconHeart  
+iconLocation  
+iconInvoice  
+iconCustomerService  
+iconShoppingBag  
+iconFullscreenExit  
+iconChat  
+iconChevronBack  
+iconCancelAlt  
+iconEmail  
+iconCheckmark  
+iconArrowBack  
+iconArrowForward  
+iconMenu  
+iconMin  
+iconPhone  
+iconPlus  
+iconClose  
+iconFullscreen  
+iconOrderBefore  
+iconBox  
+iconHome  
+iconId  
+iconLock  
+iconNewspaper  
+iconSadFace  
+iconShutdown  
+iconParty  
+iconStar  
+iconEmailOutline  
+icon404  
+iconSun  
+iconMoon
+
+</details>
+
+## Next steps
+
+- Learn more about [theming](../framework/theming.md) a GraphCommerce storefront

package/content/framework/readme.md

@@ -0,0 +1,79 @@
+---
+menu: Overview
+---
+
+> **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/ho-nl/m2-pwa/releases).
+
+# GraphCommerce framework overview
+
+GraphCommerce is a front-end framework used for building headless Magento
+e-commerce storefronts in React. It includes the structure, components, and
+tooling you need to get started so you can spend your time styling and designing
+high-end e-commerce progressive web apps (PWA).
+
+### Framework concepts and components
+
+| Concepts                                                       | Customizing                              | Other                                              |
+| -------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------- |
+| [Static generation](../framework/static-generation.md)         | [Theming](../framework/theming.md)       | [Translations](../framework/translations.md)       |
+| [Environment Variables](../framework/environment-variables.md) | [Typography](../framework/typography.md) | [Troubleshooting](../framework/troubleshooting.md) |
+| [Deployment](../framework/deployment.md)                       | [Favicon](../framework/favicon.md)       | [SEO](../framework/seo.md)                         |
+| [GraphCMS](../framework/graphcms.md)                           | [Icons](../framework//icons.md)          |                                                    |
+
+## GraphCommerce project structure
+
+When you create a GraphCommerce app, the GraphCommerce
+[magento-graphcms example](../getting-started/readme.md) comes with a basic file
+structure of a GraphCommerce project that's integrated with Magento and
+GraphCMS. Most of the files that you'll work within your GraphCommerce project
+are located in the /components or /pages directories.
+
+- A minimal set of components you would most likely modify for your project
+- The main layout component, which renders header, navigation, and footer
+- A set of boilerplate pages, which handle URL routing
+- Basic global styles in theme.ts provided by
+  [Mui ↗](https://mui.com/customization/default-theme/)
+- Interface translation files
+
+```txt
+File structure of the graphcommerce-magento example
+
+├── components
+    └── Layout
+        └── Footer.tsx
+        └── LayoutFull.tsx
+    └── GraphCMS
+        └── Asset
+        └── RowHeroBanner
+        └── RowQuote
+    └── theme.ts
+    └── ...
+├── GraphQL
+    └── CategoryPage.graphql
+    └── PageLink.graphql
+    └── ...
+├── pages
+    └── product
+        └── [url].jsx
+        └── ...
+    └── page
+        └── [...url].jsx
+    └── [...url].tsx
+    └── [cart].tsx
+    └── _app.tsx
+    └── _document.tsx
+    └── ...
+├── locales
+    └── en.po
+    └── nl.po
+    └── ...
+```
+
+## Next steps
+
+- Learn about [theming](../framework/theming.md) a GraphCommerce storefront
+- Learn about [Static Generation (SSG)](../framework/static-generation.md) in
+  GraphCommerce

package/content/framework/seo.md

@@ -0,0 +1,64 @@
+---
+menu: SEO
+---
+
+# SEO
+
+## Page Meta data
+
+Page meta data is handled by the
+`import { PageMeta } from '@graphcommerce/next-ui'` component. Depending on the
+page, the props that are passed are static or dynamic (functional page titles
+are hardcoded).
+
+```tsx
+// Example from /cart.tsx
+
+<PageMeta
+  title={t`Cart (${data?.cart?.total_quantity ?? 0})`}
+  metaDescription={t`Cart Items`}
+  metaRobots={['noindex']}
+  // canonial={''}
+/>
+```
+
+Dynamic example
+
+```tsx
+// Example from /product/[url].tsx
+
+<PageMeta
+  title={page?.metaTitle ?? title ?? ''}
+  metaDescription={page?.metaDescription ?? ''}
+  metaRobots={metaRobots}
+  canonical={`/${page?.url}`}
+/>
+```
+
+## Generate the XML sitemap
+
+GraphCommerce uses
+[next-sitemap ↗](https://github.com/iamvishnusankar/next-sitemap) to generate
+the sitemap, which is located in the directory /public/sitemap.xml. For example,
+view the [demo sitemap.xml ↗](https://graphcommerce.vercel.app/sitemap.xml)
+
+Generating the sitemap.xml file is part of the static build process. Use
+`yarn build` to initiate the build process and to generate a new sitemap.xml
+file.
+
+Sitemap generation uses the `NEXT_PUBLIC_SITE_URL` variable in your .env fil.
+
+## Modify /robots.txt
+
+GraphCommerce creates a /robots.txt file on build time. Its contents can be
+modified by editing /next-sitemap.js. For example, view the
+[demo robots.txt ↗](https://graphcommerce.vercel.app/robots.txt)
+
+Generating the robot.txt file is part of the static build process. Use
+`yarn build` to initiate the build process and to generate a new robots.txt
+file.
+
+## Next steps
+
+- Learn about [Static Generation (SSG)](../framework/static-generation.md) in
+  GraphCommerce

package/content/framework/static-file-serving.md

@@ -0,0 +1,44 @@
+# Static File Serving
+
+When building your custom storefront, it can be useful to have access to static
+files not already hosted elsewhere, like images or text documents. This guide
+describes how to reference and serve static files in GraphCommerce.
+
+## How static file serving works
+
+Static files are files your app downloads from a server. Next.js serves static
+assets at the root path /. For example, you can create a file called
+public/icon.png and reference it in your code as /icon.png.
+
+Product images are served from the Magento database, so you don't need to place
+those images in the /public directory.
+
+### Best practices
+
+- Don't rename the /public directory as it's the only directory used to serve
+  static files. You can add subdirectories, like /public/docs
+
+## CSS background images
+
+CSS background images are common assets you would place in the /public
+directory. It's a good practice to limit these to .svg images.
+
+If you need to use a .jpg file as part of the design, place them in the /public
+directory but render them with the `'@graphcommerce/image'` [Image component]().
+This will benefit performance, due to the component's features such as
+CDN-caching, srcset, and viewport loading.
+
+## Images
+
+Images that are part of a page or component's content (for example, product
+images), should always be rendered with the `'@graphcommerce/image'`
+[Image component](). This will benefit performance, due to the component's
+features such as CDN-caching, srcset, and viewport loading.
+
+## Next steps
+
+- Learn more about
+  [Next.js static file serving ↗](https://nextjs.org/docs/basic-features/static-file-serving)
+  in the Next.js docs
+- Learn how to modify your GraphCommerce app's
+  [favicon](../framework/favicon.md)