AWS Amplify GraphQL Transformer Core

Common errors

• Data source with name NONE_DS is now preventing amplify push from succeeding.

  cause During GraphQL Transformer V1 to V2 migration, or after schema changes, sometimes a 'NONE_DS' (none data source) can remain or be incorrectly referenced.
  fix Manually delete the 'NONE_DS' data source in the AWS AppSync console for your API. You might need to temporarily revert to a V1 schema, push, delete the data source, and then re-apply the V2 schema and push again.

• Expected type AuthStrategy, found private.

  cause This error typically indicates an issue with the `@auth` directive syntax or an incompatibility with the GraphQL Transformer's expected `AuthStrategy` enum values, particularly when using custom or outdated `@auth` rules.
  fix Verify that your `@auth` rules adhere to the correct syntax for your Transformer version (V1 vs. V2). Ensure `allow` strategies like `owner`, `groups`, `public`, `private` (if supported) are correctly configured. In V2, `private` generally implies `allow: private, provider: userPools` or `iam`.

• GraphQL API has a new version. Run 'amplify migrate api' to migrate your schema to the new version.

  cause Your Amplify project's GraphQL API is still using the V1 GraphQL Transformer, and a new version (V2) is available and recommended.
  fix Execute `amplify migrate api` in your CLI to initiate the migration process. Carefully review the migration guide and output for manual steps required after the automated migration.

• ValidationError: Only one resolver is allowed per field.

  cause This error can occur during or after a GraphQL Transformer migration (e.g., V1 to V2), indicating that multiple resolver configurations are being generated or detected for a single field, which is not allowed by AppSync.
  fix This can sometimes be resolved by simply running `amplify push` again. If it persists, review your schema for conflicting directives or custom resolver files. Ensure that custom VTL resolvers adhere to the V2 pipeline resolver slotting mechanism, avoiding direct overrides where pipeline integration is expected.

Warnings

• breaking The migration from GraphQL Transformer V1 to V2 introduced significant breaking changes. Key directives like `@key` were replaced by `@primaryKey` and `@index`. The `@auth` directive shifted to a deny-by-default model, requiring explicit authorization rules. OpenSearch integration was updated to OpenSearch version 7.10, potentially causing data loss during migration if not handled with snapshots and re-indexing.
  Fix: Refer to the official AWS Amplify GraphQL Transformer v1 to v2 migration guide. Use `amplify migrate api` for auto-migration where possible, and manually adjust schema and resolvers for complex cases. For OpenSearch, ensure data snapshots are taken and restored if necessary. Explicitly define all `@auth` rules.
• gotcha When using custom transformers or integrating with other GraphQL tooling, ensure that the version of the `graphql` package installed in your project matches the version that `graphql-transformer-core` depends on. Mismatched versions can lead to unexpected parsing errors or runtime issues.
  Fix: Check the `peerDependencies` or `dependencies` of `@aws-amplify/graphql-transformer-core` for the required `graphql` version and install a compatible version in your project.
• breaking The architecture of generated resolvers changed significantly with Transformer V2, moving to AppSync Pipeline Resolvers. This impacts custom resolver logic and overrides. If you had custom VTL resolvers in V1, they need to be re-evaluated and potentially refactored to fit the V2 pipeline resolver model.
  Fix: Review the documentation on extending Amplify-generated pipeline resolvers for V2. Custom VTL files need to follow new naming conventions and may slot into specific positions within the pipeline.
• gotcha Repeated deployments or complex schemas can sometimes lead to AWS CloudFormation stack limits, such as exceeding the maximum number of IAM policies per role. This is more common during the V1 to V2 migration due to the generated resource changes.
  Fix: Monitor CloudFormation stack sizes. Request limit increases for relevant AWS services (e.g., IAM, AppSync) if necessary. Consider breaking down large schemas or using custom override capabilities to optimize resource generation.

Install

• npm install graphql-transformer-core npm
• yarn add graphql-transformer-core yarn
• pnpm add graphql-transformer-core pnpm

Imports

• GraphQLTransform

  import { GraphQLTransform } from '@aws-amplify/graphql-transformer-core'

  The primary class for schema transformation. This is the entry point for programmatic schema transformation.
• TransformConfig

  import { TransformConfig } from '@aws-amplify/graphql-transformer-core'

  Type definition for the configuration object passed to `GraphQLTransform`, specifying the schema and transformers to apply.
• TransformerContext

  import { TransformerContext } from '@aws-amplify/graphql-transformer-core'

  Interface representing the context available during schema transformation, primarily used when developing custom GraphQL transformers.
• ModelTransformer

  import { ModelTransformer } from '@aws-amplify/graphql-model-transformer'

  An example of a specialized transformer (from a separate package) that extends the core functionality to handle the `@model` directive.

Quickstart

This quickstart demonstrates how to programmatically use `graphql-transformer-core` to take a GraphQL schema with Amplify directives and generate corresponding AWS CloudFormation templates and an expanded GraphQL schema. It shows instantiation of `GraphQLTransform` with a set of specialized transformers, typically imported from other `@aws-amplify/graphql-*` packages, and then executing the `transform()` method to produce infrastructure code.

import { GraphQLTransform } from '@aws-amplify/graphql-transformer-core';
import { ModelTransformer } from '@aws-amplify/graphql-model-transformer';
import { AuthTransformer } from '@aws-amplify/graphql-auth-transformer';
import { print, parse } from 'graphql';

async function generateCloudFormation() {
  const schema = `
    type Post @model @auth(rules: [{ allow: public, operations: [read] }, { allow: owner, ownerField: "owner" }]) {
      id: ID!
      title: String!
      content: String
      owner: String
    }

    type Comment @model {
      id: ID!
      post: Post @hasOne
      text: String!
    }
  `;

  const transformers = [
    new ModelTransformer(),
    new AuthTransformer(),
    // You would include other transformers (e.g., ConnectionTransformer) here
  ];

  const transform = new GraphQLTransform({
    schema,
    transformers,
  });

  try {
    const output = await transform.transform();
    console.log('Generated CloudFormation template (truncated):');
    // In a real scenario, you'd save `output.stacks.Root.json` to a file.
    const cfnTemplate = JSON.stringify(output.stacks.Root.json, null, 2);
    console.log(cfnTemplate.substring(0, 500) + '\n...(truncated for brevity)');

    console.log('\nGenerated GraphQL Schema (truncated):');
    // The transformed schema with additional types and directives can also be accessed.
    const transformedSchemaSDL = print(parse(output.schema));
    console.log(transformedSchemaSDL.substring(0, 500) + '\n...(truncated for brevity)');

  } catch (e) {
    console.error('Error during transformation:', e);
  }
}

generateCloudFormation();