diff --git a/packages/documentation/content/docs/schema-registry/app-deployments.mdx b/packages/documentation/content/docs/schema-registry/app-deployments.mdx index 299d37af..7644d33b 100644 --- a/packages/documentation/content/docs/schema-registry/app-deployments.mdx +++ b/packages/documentation/content/docs/schema-registry/app-deployments.mdx @@ -28,7 +28,10 @@ hive app:create \ The `--name` parameter is mandatory. The `--version` parameter is optional - if omitted, a random 7-character alphanumeric version is generated automatically. -Instead of a JSON manifest file, you can also pass a directory or a glob pattern. When a directory or glob is provided, `app:create` scans for `*.graphql` files, normalizes each operation, computes a SHA-256 hash per operation, and builds the manifest directly. +The JSON file can use the GraphQL Code Generator, Relay, or Apollo persisted query manifest format. +Instead of a manifest, you can also pass a directory or a glob pattern. When a directory or glob is +provided, `app:create` scans for `*.graphql` files, normalizes each operation, computes a SHA-256 +hash per operation, and builds the manifest directly. ```bash title="Create an App Deployment from a directory" # from a directory @@ -56,12 +59,12 @@ hive app:create \ persisted-documents.json ``` -| Parameter | Description | -| ------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `--name` | The name of the app deployment. | -| `--version` | The version of the app deployment. Optional - a random version is generated if omitted. | -| `--publish` | Publish the app deployment immediately after creation. Optional. | -| `` | Path to a JSON manifest file, a directory of `.graphql` files, or a glob pattern matching `.graphql` files. | +| Parameter | Description | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `--name` | The name of the app deployment. | +| `--version` | The version of the app deployment. Optional - a random version is generated if omitted. | +| `--publish` | Publish the app deployment immediately after creation. Optional. | +| `` | Path to a GraphQL Code Generator, Relay, or Apollo manifest file, a directory of `.graphql` files, or a glob pattern matching `.graphql` files. | An app deployment is uniquely identified by the combination of the `name` and `version` parameters for each target. @@ -153,8 +156,9 @@ flowchart LR We need to extract the persisted documents from within our app. The method for doing this may vary depending on the tools you are using. -The persisted documents must stored in a JSON file, which includes the documents along with their -corresponding hashes. This JSON file will be uploaded to the Hive Registry. +The persisted documents can be stored in a key-value JSON manifest generated by GraphQL Code +Generator or Relay, or in an Apollo persisted query manifest. The manifest includes each document +and its corresponding ID and is uploaded to the Hive Registry. ```json title="persisted-operations.json" { @@ -170,7 +174,7 @@ As long as the app deployment using these persisted documents is active, any cha API that alters the GraphQL schema as used by any of the persisted documents would break that specific app version and therefore be an unsafe/breaking change. - + @@ -194,8 +198,8 @@ const config: CodegenConfig = { }; ``` -After running the Relay Compiler, the file `persisted-documents.json` will be generated. This file -can be used for creating a new app deployment on Hive. +After running GraphQL Code Generator, the file `persisted-documents.json` will be generated. This +file can be used for creating a new app deployment on Hive. For more information, [please refer to the GraphQL Code Generator documentation](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#enable-persisted-documents). @@ -226,6 +230,34 @@ For more information, + + +If your tooling emits an Apollo persisted query manifest, you can pass that file directly to +`hive app:create` instead of converting it to a key-value manifest. Version 1 of the format looks +like this: + +```json title="persisted-query-manifest.json" +{ + "format": "apollo-persisted-query-manifest", + "version": 1, + "operations": [ + { + "id": "e0321f6b438bb42c022f633d38c19549dea9a2d55c908f64c5c6cb8403442fef", + "body": "query GetItem { thing { __typename } }", + "name": "GetItem", + "type": "query" + } + ] +} +``` + +Hive preserves each operation's `id` when creating the app deployment. + +For more information, +[refer to the Apollo Client persisted queries documentation](https://www.apollographql.com/docs/react/data/persisted-queries#1-generate-operation-manifests). + + + " \ + --target "//" \ + --name "my-app" \ + --version "1.0.0" \ + persisted-query-manifest.json +``` + +Hive reads each operation's `id` and `body` from version 1 of the +`apollo-persisted-query-manifest` format. Existing operation IDs are preserved, so no intermediate +conversion to the GraphQL Code Generator or Relay manifest format is required. + +```json title="persisted-query-manifest.json" +{ + "format": "apollo-persisted-query-manifest", + "version": 1, + "operations": [ + { + "id": "e50da5010bca3f3ea824008ff6d885e7a877936c5834705e55c7fd0f1e0be47b", + "body": "query GetProduct { product { id name } }", + "name": "GetProduct", + "type": "query" + } + ] +} +``` + +--- + +- [App Deployments documentation](/docs/schema-registry/app-deployments) +- [Hive CLI `0.62.0` Release Notes](https://github.com/graphql-hive/console/releases#release-@graphql-hive/cli@0.62.0) +- [Hive CLI documentation](/docs/api-reference/cli)