npm - @graphcommerce/docs - Versions diffs - 3.1.4 - Mend

@graphcommerce/docs 3.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/.babelrc +4 -0
package/CHANGELOG.md +160 -0
package/components/Layout/LayoutFull.tsx +85 -0
package/components/Layout/Logo.tsx +19 -0
package/components/Layout/graphcommerce.svg +34 -0
package/components/Search.tsx +37 -0
package/components/SearchForm.tsx +110 -0
package/components/SidebarMenu/index.tsx +101 -0
package/components/prism.css +274 -0
package/components/rehype-prism-plus.css +49 -0
package/components/theme.ts +410 -0
package/content/framework/deployment.md +56 -0
package/content/framework/environment-variables.md +61 -0
package/content/framework/favicon.md +38 -0
package/content/framework/graphcms.md +66 -0
package/content/framework/icons.md +255 -0
package/content/framework/readme.md +79 -0
package/content/framework/seo.md +64 -0
package/content/framework/static-file-serving.md +44 -0
package/content/framework/static-generation.md +221 -0
package/content/framework/theming.md +258 -0
package/content/framework/translations.md +112 -0
package/content/framework/troubleshooting.md +67 -0
package/content/framework/typography.md +143 -0
package/content/getting-started/create.md +152 -0
package/content/getting-started/graphcms-component.md +240 -0
package/content/getting-started/header.md +224 -0
package/content/getting-started/pages.md +290 -0
package/content/getting-started/readme.md +294 -0
package/content/getting-started/start-building.md +160 -0
package/content/getting-started/vscode.md +48 -0
package/content/readme.md +124 -0
package/content/roadmap.md +31 -0
package/lib/DocumentIndexer.ts +59 -0
package/lib/files.ts +168 -0
package/lib/instantSearch.ts +26 -0
package/lib/typesense/IndexerHandler.ts +47 -0
package/lib/typesense/Leaves.ts +37 -0
package/lib/typesense/SearchIndexer.ts +64 -0
package/lib/typesense/batchInterable.ts +13 -0
package/lib/typesense/createInstantSearchProps.ts +36 -0
package/lib/typesense/typesenseClientConf.ts +23 -0
package/lib/typesense/typesenseIndexerHandler.ts +23 -0
package/next-env.d.ts +5 -0
package/next.config.js +21 -0
package/package.json +56 -0
package/pages/[[...url]].tsx +391 -0
package/pages/_app.tsx +26 -0
package/pages/_document.tsx +22 -0
package/pages/api/reindex.ts +4 -0
package/pages/menu/[[...url]].tsx +69 -0
package/public/apple-touch-icon.png +0 -0
package/public/favicon.ico +0 -0
package/public/favicon.svg +12 -0
package/public/link.svg +4 -0
package/public/manifest/favicon-192.png +0 -0
package/public/manifest/favicon-512.png +0 -0
package/public/manifest.webmanifest +20 -0
package/tsconfig.json +5 -0

package/content/framework/typography.md ADDED Viewed

@@ -0,0 +1,143 @@
+# Typography
+This guide provides information about using the Typography component and
+customizing your GraphCommerce storefront's typography. If your looking to learn
+about the `<Trans>` macro, head over to
+[translations](../framework/translations.md).
+## Using the typography component
+The `<Typography>` component is used to render text on pages and in components:
+```tsx
+<Typography variant='h1' component='h4'>
+  <Trans>This is the homepage</Trans>
+</Typography>
+```
+Will output:
+```tsx
+<h4 class='MuiTypography-root MuiTypography-h1'>This is the homepage</h4>
+```
+It's important to realize that the style of a typography component is
+independent from the semantic underlying element. In the example above, the
+variant prop is used to render a `<h4>` semantic element with h1 styling.
+## Changing font styles and font sizes
+Font styles are part of the global styles in /components/index.ts. Changes to
+font-size and few other properties can be made here:
+```tsx
+  h1: {
+    ...fontSize(28, 64),
+    fontWeight: 700,
+    fontVariationSettings: "'wght' 660",
+    lineHeight: 1.22,
+  },
+  h2: {
+    ...fontSize(25, 40),
+    fontWeight: 700,
+    fontVariationSettings: "'wght' 630",
+    lineHeight: 1.35,
+  },
+  h3: {
+    ...fontSize(22, 30),
+    fontWeight: 700,
+    fontVariationSettings: "'wght' 680",
+    lineHeight: 1.55,
+  },
+  ...
+```
+In most other cases, styling within the context of a page or component is the
+better solution. The sx prop is used to overwrite the styling of a Typography
+component:
+```tsx
+<Typography
+  variant='h3'
+  component='div'
+  gutterBottom
+  sx={{
+    h3: (theme) => ({
+      color: theme.palette.primary.main,
+    }),
+  }}
+>
+  {product.name}
+</Typography>
+```
+## Responsive font sizes
+The fontSize 'property' accepts an object with a font size for each breakpoint:
+```tsx
+fontSize: {
+  lg: 50,
+  md: 40,
+  sm: 25,
+  xs: 15
+}
+```
+The GraphCommerce helper function `breakpointVal` does the same, but simplifies
+the syntax by calculating the intermediate values (`fontSize` is a
+simplification of `breakpointVal`):
+```tsx
+// Example from /components/theme.ts
+h1: {
+  ...fontSize(28, 64),
+  fontWeight: 700,
+  fontVariationSettings: "'wght' 660",
+  lineHeight: 1.22,
+},
+```
+To use breakpointVal in a component:
+```tsx
+sx={{
+  ...breakpointVal('fontSize', 36, 82, theme.breakpoints.values),
+}}
+```
+## Adding a custom font
+- In /pages/\_document.tsx, add your Google font `<link>` element as a child of
+  the `<Head>` component:
+```tsx
+<Head>
+  ...
+  <link rel='preconnect' href='https://fonts.googleapis.com' />
+  <link rel='preconnect' href='https://fonts.gstatic.com' crossOrigin='' />
+  <link
+    href='https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,700;1,400;1,600&display=swap'
+    rel='stylesheet'
+  />
+</Head>
+```
+- In /components/theme.ts, add the font to the global fontFamily, or to specific
+  font class like h1:
+```tsx
+typography: {
+  fontFamily:
+    'Open Sans,-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji',
+  // @see docs typography.md
+  h1: {
+    fontFamily: 'Open Sans',
+```
+## Next steps
+- Learn more about the
+  [Typography component ↗](https://mui.com/components/typography/) in the MUI
+  documentation

package/content/getting-started/create.md ADDED Viewed

@@ -0,0 +1,152 @@
+---
+menu: 1. Create a custom storefront
+metaTitle: Create a custom storefront
+---
+# Create a GraphCommerce storefront
+You're ready to create a GraphCommerce storefront. You want to set up your
+development environment so that you can begin development.
+In this tutorial, you'll create a GraphCommerce app locally to begin developing
+a full-featured storefront. GraphCommerce is a front-end framework used for
+building headless Magento e-commerce PWA's.
+### What you'll learn
+After you've finished this tutorial, you'll have accomplished the following:
+- Set up your local development environment
+- Generated a new project based on the magento-graphcms example
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/fk82kF" />
+ <figcaption>GraphCommerce magento-graphcms example category page</figcaption>
+</figure>
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/Fs7XWK" />
+ <figcaption>GraphCommerce magento-graphcms example product page</figcaption>
+</figure>
+### Requirements
+You've familiarized yourself with
+[React ↗](https://reactjs.org/docs/getting-started.html),
+[Next.js ↗](https://nextjs.org/docs/getting-started), and
+[Mui ↗](https://mui.com/getting-started/installation/). GraphCommerce is a
+front-end React framework that uses Next.js for server-side rendering.
+### Install dependencies
+If you want to test a GraphCommerce storefront using a pre-configured Magento
+demo store and a pre-configured GraphCMS project with demo content, then you
+need to only install the dependencies. This is the quickest approach.
+- Install and use node 14: `nvm install 14 && nvm use 14`
+- Install yarn: `npm install --global yarn`
+## Step 1: Create a new GraphCommerce app
+### Download the example
+1. `git clone ... graphcommerce`
+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`
+Edit /package.json. Delete `"scripts": {...}` and rename `scripts_local` to
+`scripts`:
+```json
+{
+  "name": "@my-company/my-project",
+  "scripts": {
+    ...
+  }
+}
+```
+## Step 2: Magento and GraphCMS API keys
+> By default, the .env file is configured with API keys from a demo Magento
+> store and a demo GraphCMS project. If you want to test your GraphCommerce app
+> using the demo store, then you can start the development environment. Only
+> proceed with the following steps if you want to develop a GraphCommerce
+> storefront using your own Magento store and/or GraphCMS project.
+### Requirements
+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
+- GraphCMS - A GraphCMS project with the required schema.
+  [Clone the demo GraphCMS project](https://app.graphcms.com/clone/caddaa93cfa9436a9e76ae9c0F34d257)
+  as your starting point.
+### Configuration
+To connect your GraphCommerce app to your Magento backend and/or GraphCMS
+project, you need to update variables in the /.env file. The .env file contains
+useful information about your storefront.
+`MAGENTO_ENDPOINT=""`
+Magento 2 API url, located at `http://<magento2-server>/graphql`.
+`IMAGE_DOMAINS=",media.graphcms.com"`
+Comma-separated list of image domains. Add media.graphcms.com as default.
+`GRAPHCMS_URL=""`
+GraphCMS API url. Once logged in, copy it from Project Settings > Api Access >
+Content API
+`NEXT_PUBLIC_LOCALE_STORES='{"en": "en_US", "nl": "default"}'`
+List of routes and store_codes. In the above example, adding URL suffix /nl/
+would result in the storeview 'default' is loaded. GraphCommerce uses the
+browser language to determine which storeview to load. A URL suffix will be
+added as a result, with the exception of the first option in the list.
+> If need to fetch a list of available store_codes, run `yarn dev` when you
+> entered your `MAGENTO_ENDPOINT`. The app won't build, but the GraphQL explorer
+> will start at `http://localhost:3000/api/graphql`. Enter the following query:
+>
+> ```graphql {3-4}
+> query {
+>   availableStores {
+>     store_code
+>     store_name
+>   }
+> }
+> ```
+### Remove unused PSP's
+The example has Payment Service Providers integrated (Mollie, Braintree). Remove
+the ones you don't want to use.
+- Remove `"@graphcommerce/[psp]"` from package.json
+- Remove all [psp] references from `pages/checkout/payment.tsx`
+## Step 3: Start the development environment
+- `yarn` Install the dependencies
+- `yarn codegen` Converts all .graphql files to typescript files
+- `yarn dev` Run the app
+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)
+## Next steps
+- Learn how to [Set up Visual Studio Code](../getting-started/vscode.md) and
+  install usefull extensions for an optimal development experience
+- [Start building a GraphCommerce custom storefront](../getting-started/start-building.md)
+  by customizing text and component styles, fetching data from server
+  components, and making changes to GraphQL queries.

package/content/getting-started/graphcms-component.md ADDED Viewed

@@ -0,0 +1,240 @@
+---
+menu: 5. Build a GraphCMS component
+metaTitle: Build a GraphCMS component
+---
+> **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).
+# Build a GraphCMS component
+Previously, you created a GraphCommerce app and started building a custom
+header. You're now ready to build a GraphCMS component.
+GraphCMS is the integrated Content Management System that is part of the
+[magento-graphcms example](../getting-started/readme.md).
+In this tutorial, you'll accomplish a series of tasks to add some specific
+functionality to your app. The final result will be relatively simple, but
+you'll learn where to find resources to build more complex features on your own.
+### After you've finished this tutorial, you'll have accomplished the following:
+- Create a Model in GraphCMS, called Banner
+- Configure the Model's copy and image field
+- Define the relationship between the Banner Model and Page Content field
+- Write a GraphQL query fragment and add it to the page query
+- Add the component to the page renderers
+### Requirements
+You've familiarized yourself with
+[React ↗](https://reactjs.org/docs/getting-started.html),
+[Next.js ↗](https://nextjs.org/docs/getting-started), and
+[Mui ↗](https://mui.com/getting-started/installation/). GraphCommerce is a
+frontend React framework that uses Next.js for server-side rendering.
+---
+### Create the GraphCMS model
+- Login to GraphCMS, navigate to the Schema and add a new Model called "Banner"
+- Add a single line text field called "Identity" and configure the following:
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/6UGrfK" />
+  <figcaption>Adding a Single line text field called "Identity"</figcaption>
+</figure>
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/TvNPoT" />
+   <figcaption>Configuring of the "Identity" field</figcaption>
+</figure>
+- Add an Asset field called "Image" and configure the following:
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/OdkckP" />
+   <figcaption>Adding an Asset field called "Image"</figcaption>
+</figure>
+- Add a Rich text field called "Copy" and configure the following:
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/C8nzzB" />
+   <figcaption>Adding a Rich text field called "Copy"</figcaption>
+</figure>
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/j9kydr" />
+   <figcaption>Configuring of the "Copy" field</figcaption>
+</figure>
+### Define relationship with Content field
+To be able to use the newly created model to add banners to pages, define the
+relationship between the Banner model and the Content field of the Page model.
+- Navigate to the Page Schema. Edit the field called "Content"
+- Click "Define relationship" (collapsed by default). Add the Banner model to
+  "Models to reference"
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/Dc4axA" />
+   <figcaption>Adding the newly created Banner Model to "Models to reference"</figcaption>
+</figure>
+- Navigate to Content, edit the Homepage entry and add a new banner instance to
+  the homepage:
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/lpa4x4" />
+   <figcaption>Adding a new banner to the Homepage content entry</figcaption>
+</figure>
+### Validate GraphQL Schema
+- To validate the addition of the Banner model and the relation with the Page
+  model Content field, try out the following GraphQL query in your local GraphQL
+  endpoint (running at http://localhost:3000/api/graphql):
+```graphql
+query {
+  pages(where: { url: "page/home" }) {
+    title
+    content {
+      __typename
+    }
+  }
+}
+```
+Should output the following. Make note that 'Banner' is listed as a typename.
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/G51mOD" />
+   <figcaption>Validation of the addition of "Banner" to the GraphQL Schema</figcaption>
+</figure>
+### Create the component query fragment
+- Add a new file, /components/GraphCMS/Banner/Banner.graphql:
+```graphql
+fragment Banner on Banner {
+  image {
+    ...Asset
+  }
+  copy {
+    raw
+  }
+}
+```
+- After saving the file, a new file Banner.gql.ts should be
+  [created automatically](../getting-started/readme.md#query-fragments). Take a
+  look at the file's contents. It should export the type `BannerFragment`.
+### Add the query fragment to the page query fragments
+- In /components/GraphCMS/RowRenderer.graphql, add the fragment:
+```graphql
+fragment RowRenderer on Page {
+  content {
+    __typename
+    ... on Node {
+      id
+    }
+    ...RowColumnOne
+    ...RowColumnTwo
+    ...RowColumnThree
+    ...RowBlogContent
+    ...RowHeroBanner
+    ...RowSpecialBanner
+    ...RowQuote
+    ...RowButtonLinkList
+    ...RowServiceOptions
+    ...RowContentLinks
+    ...RowProduct
+    ...Banner
+  }
+}
+```
+### Create the React component
+- Add a new file, /components/GraphCMS/Banner/index.tsx:
+```tsx
+import { RichText } from '@graphcommerce/graphcms-ui'
+import { BannerFragment } from './Banner.gql'
+export function Banner(props: BannerFragment) {
+  const { copy, image } = props
+  return (
+    <div>
+      {image?.url}
+      <RichText
+        {...copy}
+        sxRenderer={{
+          paragraph: {
+            textAlign: 'center' as const,
+          },
+          'heading-one': (theme) => ({
+            color: theme.palette.primary.main,
+          }),
+        }}
+      />
+    </div>
+  )
+}
+```
+### Add the component to page components
+- In /components/GraphCMS/RowRenderer.tsx, add to the imports:
+```tsx
+import { Banner } from './Banner'
+```
+- In the same file, add banner:
+```tsx
+const defaultRenderer: Partial<ContentTypeRenderer> = {
+  RowColumnOne,
+  RowColumnTwo,
+  RowColumnThree,
+  RowHeroBanner,
+  RowSpecialBanner,
+  RowQuote,
+  RowBlogContent,
+  RowButtonLinkList,
+  RowServiceOptions,
+  RowContentLinks,
+  RowProduct,
+  Banner,
+}
+```
+- If a Model entry had been added to the homepage content field, it should
+  render. Note that the order in which content of the content field is sorted,
+  matters:
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/ONwNJD" />
+   <figcaption>An instance of the banner component rendering with content from GraphCMS</figcaption>
+</figure>
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/bMsi6A" />
+   <figcaption>Sort order matters</figcaption>
+</figure>
+## Next steps
+- Explore the [GraphCommerce framework](../framework/readme.md)