Release: 3.x (#2214)

## What's the purpose of this pull request?

This PR holds the PRs that will be available in 3.x version:

- #2184 
- #2198 
- #2176

Preview PR
- vtex-sites/starter.store#360

---------

Co-authored-by: Fanny <[email protected]>
Co-authored-by: Ícaro Azevedo <[email protected]>
Co-authored-by: Mariana Caetano Pereira <[email protected]>

.gitignore

@@ -89,6 +89,10 @@ packages/gatsby-**/**/*.json
 !packages/gatsby-**/package.json
 !packages/gatsby-**/tsconfig.json
 
+# autogen graphql files
+packages/core/@generated/schema.graphql
+packages/core/@generated/persisted-documents.json
+
 # lighthouse CI autogen files
 .lighthouseci
 

apps/site/pages/docs/api-extensions/api-extensions-improvements.mdx

@@ -0,0 +1,142 @@
+# Improvements to API extensions - v3.0.0
+
+In this guide, learn how to migrate your store version to v3.0.0 to leverage the latest improvements in the API extension.
+
+Version 3.0.0 and above, introduces the following enhancements to API extension users:
+
+- Deprecation of the `@faststore/graphql-utils` package in favor of the [`client-preset`](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client) plugin.
+
+- Refinement `gql` helper usage for a smoother and more efficient GraphQL query handling.
+
+- Enhancement security measures to a more secure method for invoking queries and mutations to safeguard your store's data.
+
+- Optimization call processes for queries or mutations defined within `@faststore/core`.
+
+import { Callout } from 'nextra/components'
+
+<Callout type="info" emoji="ℹ️">
+  For more details about these changes, also refer to the [GitHub
+  releases](/tbd) related to this version.
+</Callout>
+
+The `@faststore/graphql-utils` has been replaced by open-source solutions maintained by the community that are now re-exported from `@faststore/core`. There are minor breaking changes on how developers should write GraphQL definitions and invoke queries and mutations, which were introduced in version 3.0.0.
+
+## Before you begin
+
+Make sure your store version is updated to v3.0.0 or above. If it’s not updated follow the instructions below:
+
+1. Open your store code and navigate to the `package.json` file.
+
+2. In `dependencies` > `@faststore/core`, change the version to the following:
+
+```json
+"@faststore/core": "^3.0.0",
+```
+
+3. Open the terminal and run `yarn` to update the version.
+
+## Updating the `gql` helper usage
+
+The `gql` helper serves as a function to define GraphQL operations such as queries, mutations, or fragments within the store code. Before, the function was imported directly from the `@faststore/graphql-utils` which was not recommended. See the example below:
+
+```tsx filename="src/fragments/ClientProduct.tsx"
+import { gql } from '@faststore/graphql-utils'
+
+export const fragment = gql`
+  fragment ClientProduct on Query {
+    product(locator: $locator) {
+      id: productID
+      breadcrumbList {
+        itemListElement {
+          item
+          name
+          position
+        }
+      }
+    }
+  }
+`
+```
+
+Now with the v3.0.0, you should import the `gql` helper from `@faststore/core/api`and be called as a function - with the argument between parenthesis. This also applies to query and mutation definitions inside the components. For example:
+
+```tsx filename="src/fragments/ClientProduct.tsx" {1}
+import { gql } from '@faststore/core/api'
+
+export const fragment = gql(`
+  fragment ClientProduct on Query {
+    product(locator: $locator) {
+      id: productID
+      breadcrumbList {
+        itemListElement {
+          item
+          name
+          position
+        }
+      }
+    }
+  }
+`)
+```
+
+## Using `useQuery` hook to call queries and mutations
+
+Previously, it was possible to invoke queries and mutations by using their names - such as `MyCustomQuery` by providing it to the `useQuery` hook. For example:
+
+```tsx
+import { useQuery_unstable as useQuery } from '@faststore/core/experimental'
+
+const query = gql(`
+  query MyCustomQuery {
+    customQuery() {
+      data
+    }
+  }
+`)
+
+// The useQuery call will now throw an error
+function CustomComponent() {
+  // ...
+  const result = useQuery(`MyCustomQuery`, variables)
+  // ...
+}
+```
+
+With v3.0.0, queries and mutations are now only invoked using more secure hashes, which are randomly generated and do to that you must pass the query or mutation object - result of the `gql` call - to `useQuery` directly. For example:
+
+```tsx
+import { gql } from '@faststore/core/api'
+import { useQuery_unstable as useQuery } from '@faststore/core/experimental'
+
+const query = gql(`
+  query MyCustomQuery {
+    customQuery() {
+      data
+    }
+  }
+`)
+
+// useQuery apropriately calls MyCustomQuery
+function CustomComponent() {
+  // ...
+  const result = useQuery(query, variables)
+  // ...
+}
+```
+
+### Calling queries or mutations defined by `@faststore/core`
+
+A custom component can call a query or mutation defined by `@faststore/core`, such as `ClientManyProductsQuery`. In these cases, you replace the `useQuery` hook call with a call to the specific hook for that query.
+
+<Callout type="warning" emoji="⚠️">
+  The availability of such hooks is limited.
+</Callout>
+```tsx
+import { useClientManyProducts_unstable as useClientManyProducts } from '@faststore/core/experimental'
+
+// ClientManyProductsQuery will be called with the variables passed by CustomComponent
+function CustomComponent() {
+// ...
+const result = useClientManyProducts(variables)
+// ...
+}

apps/site/pages/docs/api-extensions/extending-queries-using-fragments.mdx

@@ -62,13 +62,13 @@ In the `ServerProduct.ts` file, define the GraphQL fragment corresponding to the
 
 import { gql } from '@faststore/core/api'
 
-export const fragment = gql`
+export const fragment = gql(`
   fragment ServerProduct on Query {
     product(locator: $locator) {
       customData
     }
   }
-`
+`)
 ```
 Now, you can consume `customData` by following the [Consuming FastStore API extension with custom components](/docs/api-extensions/consuming-api-extensions) guide.
 

package.json

@@ -10,7 +10,7 @@
     "lint": "turbo run lint",
     "test": "turbo run test",
     "size": "turbo run size",
-    "release": "lerna version patch --yes && lerna publish from-git --yes",
+    "release": "lerna version major --yes && lerna publish from-git --yes",
     "clean": "turbo run clean && rm -rf node_modules",
     "format": "prettier --ignore-path .gitignore --write \"**/*.{js,jsx,ts,tsx,md}\""
   },

packages/api/src/typeDefs/index.ts

@@ -2,7 +2,6 @@ import { print } from 'graphql'
 
 import { loadFilesSync } from '@graphql-tools/load-files'
 
-// Empty string ('') is interpreted as the current dir. Referencing it as './' won't work.
-export const typeDefs = loadFilesSync('', { extensions: ['.graphql'] })
+export const typeDefs = loadFilesSync(__dirname, { extensions: ['.graphql'] })
   .map(print)
   .join('\n')

packages/cli/src/commands/generate-graphql.ts

@@ -2,7 +2,7 @@ import { Command, Flags } from '@oclif/core'
 import { existsSync } from 'fs-extra'
 import chalk from 'chalk'
 
-import { tmpDir } from '../utils/directory'
+import { coreDir, tmpDir } from '../utils/directory'
 import { runCommandSync } from '../utils/runCommandSync'
 
 export default class GenerateGraphql extends Command {
@@ -54,6 +54,16 @@ export default class GenerateGraphql extends Command {
       cwd: isCore ? undefined : tmpDir,
     })
 
+    // yarn generate:copy-back expects the DESTINATION var to be present so it can copy the files to the correct directory
+    runCommandSync({
+      cmd: `DESTINATION=${coreDir} yarn generate:copy-back`,
+      errorMessage:
+        "Failed to copy back typings files. 'yarn generate:copy-back' thrown errors",
+      throws: 'warning',
+      debug,
+      cwd: isCore ? undefined : tmpDir,
+    })
+
     console.log(
       `${chalk.green(
         'success'

packages/core/.babelrc.js

@@ -0,0 +1,12 @@
+const { babelOptimizerPlugin } = require('@graphql-codegen/client-preset')
+
+module.exports = {
+  presets: ['next/babel'],
+  /** Replaces gql function calls for imports to the document data */
+  plugins: [
+    [
+      babelOptimizerPlugin,
+      { artifactDirectory: './@generated', gqlTagName: 'gql' },
+    ],
+  ],
+}