@graphcommerce/docs 3.1.4

package/content/framework/static-generation.md

@@ -0,0 +1,221 @@
+---
+menu: Static Site Generation (SSG)
+metaTitle: Static Site Generation with Nextjs ecommerce framework GraphCommerce
+metaDescription:
+  'GraphCommerce is a nextjs Magento framework. GraphCommerce offers Static Site
+  Generation for Magento nextjs PWA out-of-the-box.'
+---
+
+> **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).
+
+# Static Site Generation (SSG) in GraphCommerce
+
+Pages that export a function called getStaticProps, will pre-render at
+build-time. `getStaticProps` generates HTML and JSON files, both of which can be
+cached by a CDN for performance.
+
+In the [magento-graphcms example](../getting-started/readme.md), getStaticProps
+is used to pre-render **all pages**. Client-side rendering is used to display
+user-specific content on pre-rendered pages at run-time.
+
+For example, client-side rendering is used to display customer data on the
+/account page:
+
+```tsx
+// Example from /pages/account/index.tsx
+
+function AccountIndexPage() {
+  const { data, loading, error } = useQuery(AccountDashboardDocument, {
+    fetchPolicy: 'cache-and-network',
+    ssr: false,
+  })
+  const { data: config } = useQuery(StoreConfigDocument)
+  ...
+
+  const customer = data?.customer
+  ...
+}
+```
+
+In the same file, `getStaticProps` runs the DefaultPageDocument query to fetch
+the data needed to render the layout (header, footer, menu etc.)
+
+```tsx
+// Example from /pages/account/index.tsx
+
+export const getStaticProps: GetPageStaticProps = async ({ locale }) => {
+ ...
+
+  const page = staticClient.query({
+    query: DefaultPageDocument,
+    variables: {
+      url: 'account',
+      rootCategory: (await conf).data.storeConfig?.root_category_uid ?? '',
+    },
+  })
+
+  return {
+    props: {
+      ...(await page).data,
+      up: { href: '/', title: 'Home' },
+      apolloState: await conf.then(() => client.cache.extract()),
+    },
+    revalidate: 60 * 20,
+  }
+}
+```
+
+## getStaticPaths
+
+Pages that have dynamic routes need a list of paths to be statically generated.
+All paths specified by a function called `getStaticPaths` will be statically
+pre-rendered at build-time.
+
+For example, `getStaticPaths` runs the ProductStaticPaths query to fetch a list
+of all configurable product paths:
+
+```tsx
+// Example from /pages/product/configurable/[url].tsx
+
+export const getStaticPaths: GetPageStaticPaths = async ({ locales = [] }) => {
+ ...
+  const path = (locale: string) =>
+    getProductStaticPaths(
+      graphqlSsrClient(locale),
+      locale,
+      'ConfigurableProduct',
+    )
+  const paths = (await Promise.all(locales.map(path))).flat(1)
+
+  return { paths, fallback: 'blocking' }
+}
+```
+
+```tsx
+// Example from /node_modules/@graphcommerce/magento-product/components/ProductStaticPaths/ProductStaticPaths.graphql
+
+query ProductStaticPaths($currentPage: Int!, $pageSize: Int!) {
+  products(filter: {}, pageSize: $pageSize, currentPage: $currentPage) {
+    page_info {
+      current_page
+      total_pages
+    }
+    total_count
+    items {
+      ...ProductLink
+    }
+  }
+}
+```
+
+## Build your local environment
+
+You can test the static build process by running it locally:
+
+- `cd /examples/magento-graphcms/` Navigate to the project directory
+- `yarn build` Start static build process
+
+The build proces locally will not pre-render product pages to reduce build time:
+
+```tsx
+// Example from /pages/product/configurable/[url].tsx
+
+export const getStaticPaths: GetPageStaticPaths = async ({ locales = [] }) => {
+
+  if (process.env.NODE_ENV === 'development') return { paths: [], fallback: 'blocking' }
+  ...
+}
+```
+
+<details open>
+    <summary>Disabling Static Generation on production</summary>
+
+To disable or limit the amount of pages that are statically pre-redered, slice
+the paths array. This will reduce build-time:
+
+```tsx
+// Example from /pages/product/configurable/[url].tsx
+
+export const getStaticPaths: GetPageStaticPaths = async ({ locales = [] }) => {
+  ...
+
+  return { paths: paths.slice(0, 10), fallback: 'blocking' }
+}
+```
+
+Pages that are not pre-rendered at build-time, will be rendered at run-time
+(on-demand).
+
+</details>
+
+## Incremental Static Regeneration
+
+Most pages have value for `revalidate` in the object that is returned by
+`getStaticProps`:
+
+```tsx
+// Example from /pages/product/configurable/[url].tsx
+
+return {
+  props: {
+    ...(await productPage).data,
+    ...(await typeProductPage).data,
+    apolloState: await conf.then(() => client.cache.extract()),
+    up,
+  },
+  revalidate: 60 * 20,
+}
+```
+
+When set, static pages will be regenerated at run-time (on-demand) every 20
+minutes.
+
+The initial request to the product page will show the cached page. After 20
+minutes, the regeneration of the page is triggered on the first following
+request. Once the page has been successfully generated, the cache will be
+invalidated and the updated product page is shown.
+
+## FAQ
+
+<div>
+<details>
+<summary>When is GraphCommerce a suitable Nextjs ecommerce solution?</summary>
+
+### When is GraphCommerce a suitable Nextjs ecommerce solution?
+
+GraphCommerce is a suitable Nextjs ecommerce solution if your e-commerce store
+is already running on Magento Open Source or Adobe Commerce. A Nextjs Magento
+stack offers interesting features like Static Site Generation (SSG), which will
+improve Magento catalog performance. Nextjs Magento is also a great combination
+if you are looking to migrate to Magento.
+
+</details>
+
+<details>
+<summary>What are the advantages of a Nextjs React Magento stack?</summary>
+
+### What are the advantages of a Nextjs React Magento stack?
+
+Nextjs React Magento is considered newer web technology, offering a modern
+approach to e-commerce development. React can be viewed as the industry standard
+for large-scale web apps. Next.js adds the ability for Static Site Generation (a
+form of Server-side Rendering), enabling indexing by search engines.
+GraphCommerce is a framework that combines Nextjs, React and Magento, and
+simplifies building Magento Nextjs PWA's.
+
+</details>
+</div>
+
+## Next steps
+
+- Learn more about [building pages](../getting-started/pages.md) in
+  GraphCommerce
+- Learn more about [Static File Serving](../framework/static-file-serving.md)
+- Learn more about
+  [getStaticProps ↗](https://nextjs.org/docs/basic-features/data-fetching/get-static-props)
+  or
+  [getStaticPaths ↗](https://nextjs.org/docs/basic-features/data-fetching/get-static-paths)
+  in the Next.js documentation

package/content/framework/theming.md

@@ -0,0 +1,258 @@
+# Theming
+
+The GraphCommerce [magento-graphcms](../getting-started/readme.md) example and
+GraphCommerce components are built with [MUI ↗](https://mui.com/). MUI provides
+a robust, customizable, and accessible library of foundational and advanced
+components, enabling you to build your design system and develop React
+applications faster.
+
+This guide covers how to customize the global look and feel of your application,
+as well as some common theming needs.
+
+## Changing the color palette
+
+The global styles or your GraphCommerce app are located in /components/theme.ts.
+To customize the app with your preferred colors, change the primary, secondary
+and text colors. Save the file to see your changes updated in real-time:
+
+```json
+  primary: {
+    main: '#FF4A55',
+    contrastText: '#FFFFFF',
+    dark: '#F33642',
+  },
+  secondary: {
+    main: '#006BFF',
+    light: '#D1E4FF',
+    contrastText: '#ffffff',
+  },
+  ...
+  text: {
+    primary: '#000000',
+    secondary: '#00000050',
+    disabled: '#00000030',
+  },
+```
+
+You can search through your codebase to discover which component will be
+affected by your changes. For example, search for occurrences of
+`theme.palette.primary.main`.
+
+### Best practices
+
+- Limit the number of global style overwrites in /components/theme.ts. to a
+  minimum if possible. In most cases, styling within the context of a component
+  is the better solution.
+
+## Styling component with props
+
+Most components have props that define their look and feel. Most common are the
+`color` and `variant` props:
+
+```tsx
+<Button
+  ...
+  color='primary'
+  variant='pill'
+  >
+</Button>
+```
+
+- Learn about a component's features in the MUI documentation:
+  [MUI Button documentation ↗](https://mui.com/components/buttons/)
+- To learn which options are accepted by a prop, refer to the component's API:
+  [MUI Button API ↗](https://mui.com/api/button/). You can also use your IDE's
+  suggestions functionality. For [VS Code's](../getting-started/vscode.md)
+  IntelliSense feature, type Ctrl+Space.
+- It can be helpful to learn how a component is styled, for example, to explore
+  how palette variables are used. Refer to the
+  [MUI Button source code ↗](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Button/Button.js)
+
+## Change a component's styling with the sx prop
+
+A simple way to style a component is by using the
+[sx prop ↗](https://mui.com/system/the-sx-prop/). To get started with the sx
+prop in your GraphCommerce storefront, refer to
+[start building a GraphCommerce custom storefront](../getting-started/start-building.md).
+
+### Accessing the theme
+
+To access the theme object, set an anonymous function as the value of the
+property:
+
+```tsx
+sx={{
+  borderRadius: 2,
+  backgroundColor: (theme) => theme.palette.primary.main,
+}}
+```
+
+To use the theme object for multiple property's:
+
+```tsx
+sx={(theme) => ({
+  borderRadius: `1px solid ${theme.palette.divider}`,
+  backgroundColor: theme.palette.primary.main,
+})}
+```
+
+## Creating styled components with the styled() utility
+
+A more advanced way is to use the
+[MUI styled() ↗](https://mui.com/system/styled/) utility for creating styled
+components:
+
+```tsx
+import { styled } from '@mui/material'
+
+const AnimatedButton = styled(Button, { name: 'animatedButton' })(
+  ({ theme }) => ({
+    '@keyframes pulse': {
+      '0%': {
+        boxShadow: `0 0 0 0 ${theme.palette.primary.main}`,
+      },
+      '100%': {
+        boxShadow: `0 0 0 15px ${theme.palette.background.default}`,
+      },
+    },
+    animation: 'pulse 1.5s infinite',
+  }),
+)
+```
+
+```tsx
+<AnimatedButton color='primary' variant='contained'>
+  <Trans>About Us</Trans>
+</AnimatedButton>
+```
+
+<figure>
+
+https://user-images.githubusercontent.com/1251986/155032870-ddecefe0-afb3-418c-af3d-91d8bc435dff.mp4
+
+<video width="100%" controls autoPlay loop muted>
+<source src="https://user-images.githubusercontent.com/1251986/155032870-ddecefe0-afb3-418c-af3d-91d8bc435dff.mp4" type="video/mp4"/>
+</video>
+
+ <figcaption>Example of a styled component</figcaption>
+</figure>
+
+## Overriding components state styling
+
+To overwrite a component's hover state, add the sx prop:
+
+```tsx
+<Button
+  color='primary'
+  variant='contained'
+  sx={{ '&&:hover': { background: 'green' } }}
+>
+  <Trans>Contact Us</Trans>
+</Button>
+```
+
+> Learn more about
+> [overriding styles with class names ↗](https://mui.com/customization/how-to-customize/#overriding-styles-with-class-names)
+> in the MUI documentation
+
+## Adding a background image
+
+- In /Layout/LayoutFull.tsx, add the sx prop to the `<LayoutDefault>` component:
+
+```tsx
+<LayoutDefault sx={{ backgroundImage: `url(/images/stripes.svg)` }} />
+```
+
+- Place your background image in the /public/images directory
+
+## Customizing default border-radius
+
+All components that render content with a border-radius, except for pill buttons
+and circular buttons, are dependent on the value of `shape`. A simple way to
+remove this effect is to set its value to 0:
+
+```tsx
+  shape: { borderRadius: 0 },
+  typography: {
+```
+
+## Adding an external CSS style sheet
+
+- In /pages/\_document.tsx, add your CSS `<link>` element as a child of the
+  `<Head>` component:
+
+```tsx
+<Head>
+  ...
+  <link
+    rel='stylesheet'
+    type='text/css'
+    media='all'
+    href='https://www.graphcommerce.org/pagebuilder.min.css'
+  />
+</Head>
+```
+
+- The external CSS file will affect the styling of all your app's pages
+
+## Styling a component with CSS from external style sheet
+
+- Add the fetch query to the `getStaticProps` function of a page
+
+```ts
+const stylesheet = await(
+  await fetch('https://www.graphcommerce.org/pagebuilder.min.css'),
+).text()
+```
+
+- Pass the data as prop:
+
+```ts
+return { props: { ...stylesheet } }
+```
+
+- Specify its type:
+
+```ts
+function CategoryPage(props: Props & { stylesheet: string }) {
+
+```
+
+- Add it to the default function's props:
+
+```ts
+
+const { categories, products, ..., stylesheet } = props
+
+```
+
+- Use the sx prop to apply the styles
+
+```tsx
+<CategoryDescription
+  description={category.description}
+  sx={{ stylesheet, minWidth: '100vw' }}
+/>
+```
+
+## Lineair scaling with responsiveVal
+
+The helper function `responsiveVal` offers lineair scaling based on the viewport
+width. For example: `responsiveVal(16, 22)` will render 16px at 320px window
+width, 22px at 1280px window width.
+
+`responsiveVal` can be used to linear scale almost all CSS properties, including
+width, borderRadius and margin. Performance-wise, font-size and line-height
+should not be scaled with responsiveVal. To learn more, look into
+[responsive font sizes](../framework/typography.md).
+
+## Next steps
+
+- Learn about [icons](../framework/icons.md) in GraphCommerce
+- Learn more about
+  [customizing components ↗](https://mui.com/customization/how-to-customize/#overriding-styles-with-class-names)
+  in the MUI documentation
+- Take a look at MUI's
+  [Default Theme object ↗](https://mui.com/customization/default-theme/)
+- Learn more about a component's default styles by looking them up in the
+  [MUI repository ↗](https://github.com/mui/material-ui/tree/master/packages/mui-material/src)

package/content/framework/translations.md

@@ -0,0 +1,112 @@
+# Translations
+
+GraphCommerces uses Linqui for interface translations. This guide provides an
+introduction to how translations work in your graphCommerce app and how to add
+support for a language of your choosing.
+
+## How translations work
+
+All available interface translations are stored as .po files in the /locales
+directory.
+
+```ts
+Example of /locales/es.po
+
+...
+
+msgid "Your cart is empty"
+msgstr "Su carrito está vacío"
+
+msgid "Your session is expired"
+msgstr "Su sesión ha caducado"
+
+msgid "canceled"
+msgstr "cancelado"
+```
+
+The msgid is the message being translated. In
+/node_modules/@graphcommerce/magento-cart/components/EmptyCart/EmptyCart.tsx,
+you can see a the first msgid is passed as a propped, wrapped in the `<Trans>`
+component:
+
+```ts
+<FullPageMessage
+  title={<Trans>Your cart is empty</Trans>}
+  ...
+>
+```
+
+## Customize translations
+
+In /locales/en.po, find the msgid `Your cart is empty` and change the msgstr:
+
+```ts
+msgid "Your cart is empty"
+msgstr "Empty cart!"
+```
+
+Refresh to see your changes updated
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/ipzm99" />
+ <figcaption>Make changes to translations. Refresh to see changes updated.</figcaption>
+</figure>
+
+## Adding translations to custom component
+
+If you're building a component, you can wrap the strings you want to translate
+in the `<Trans>` jsx macro:
+
+```ts
+<Typography variant='h3'>
+  <Trans>Call us now</Trans>
+</Typography>
+```
+
+Add Linqui to the component's imports:
+
+```ts
+import { t, Trans } from '@lingui/macro'
+```
+
+Add the msgid and translation to the translation files:
+
+```ts
+Example of /locales/es.po
+
+...
+
+msgid "Call us now"
+msgstr "Llámanos ahora"
+```
+
+## Passing `{values}` to translations
+
+You can pass values in msgid's:
+
+```tsx
+<PageMeta
+  title={t`Cart (${data?.cart?.total_quantity ?? 0})`}
+  ...
+/>
+```
+
+The syntax in the translation files:
+
+```ts
+Example of /locales/en.po
+
+...
+
+msgid "Cart"
+msgstr "Cart"
+
+msgid "Cart ({0})"
+msgstr "Cart ({0})"
+```
+
+## Next steps
+
+- Learn more about
+  [Linqui patterns in react ↗](https://lingui.js.org/tutorials/react-patterns.html)
+  in the Linqui docs

package/content/framework/troubleshooting.md

@@ -0,0 +1,67 @@
+> **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).
+
+# Troubleshouting
+
+## Common build errors
+
+If any errors are detected during the build phase, the console and browser will
+display an error message. Common causes for errors are:
+
+```bash
+[next] 🕸️ - m2: Failed to generate schema: request to [...] failed, reason: connect ETIMEDOUT
+```
+
+Missing MAGENTO_ENDPOINT environment variable in your .env file
+
+```bash
+🕸️ - m2: Failed to generate schema: invalid json response body at [...] reason: Unexpected '<'
+```
+
+MAGENTO_ENDPOINT environment variable is not pointing to a Magento graphql
+endpoint
+
+```bash
+[next] error - Error: Unexpected token < in JSON at position 0
+```
+
+The Magento version is outdated. Make sure you are running Magento 2.4.3 and up
+
+```bash
+Error: Invalid src prop ([...]) on 'next/image', hostname "[...]" is not configured under images in your 'next.config.js'
+```
+
+Add the image domain to IMAGE_DOMAINS in your .env file
+
+```bash
+File /[...]/node_modules/@graphcommerce/magento-payment-braint
+ree/hooks/UseBraintree.graphql caused error: Unable to find field "createBraintreeClientToken" on type "Mutation"!
+```
+
+Remove "@graphcommerce/magento-payment-braintree" from your dependencies in
+package.json. Run `yarn` to update dependencies, then run `yarn dev`.
+
+```bash
+File /[...]/node_modules/@graphcommerce/mollie-magento-payment
+/components/MolliePlaceOrder/MolliePlaceOrder.graphql caused error: Unable to
+find field "mollie_redirect_url" on type "Order"!
+```
+
+Remove "@graphcommerce/mollie-magento-payment" from your dependencies in
+package.json. Run `yarn` to update dependencies, then run `yarn dev`.
+
+```bash
+node_modules/@graphcommerce/graphql/generated/fragments.json
+Error: Interface field RoutableInterface.type expects type UrlRewriteEntityTypeEnum but BundleProduct.type is type String.
+```
+
+In the Magento store, a product attribute is configured with attribute_code
+'type'. Migrate the product information to a new attribute and remove the
+product attribute named 'type'.
+
+## Next steps
+
+- Learn how to [Set up Visual Studio Code](../getting-started/vscode.md) and
+  install usefull extensions for an optimal development experience