{"id":15119,"library":"graphql-transformer-core","title":"AWS Amplify GraphQL Transformer Core","description":"This package, `@aws-amplify/graphql-transformer-core`, serves as the foundational framework within AWS Amplify for converting GraphQL Schema Definition Language (SDL) into AWS CloudFormation templates. It is integral to how Amplify provisions serverless GraphQL APIs on AWS AppSync, DynamoDB, Lambda, and OpenSearch. Currently at version 9.0.7, it is actively maintained as part of the broader AWS Amplify monorepo, with releases tied to the Amplify CLI and API category updates. Its key differentiators include simplifying complex cloud infrastructure setup through GraphQL directives like `@model`, `@auth`, `@connection`, and `@searchable`, abstracting away much of the underlying AWS service configuration. A significant architectural shift from Transformer V1 to V2 introduced deny-by-default authorization, explicit data modeling directives (`@primaryKey`, `@index`, `@hasOne`, `@hasMany`), and a new AppSync Pipeline Resolver architecture.","status":"active","version":"9.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-category-api","tags":["javascript","graphql","cloudformation","aws","amplify","typescript"],"install":[{"cmd":"npm install graphql-transformer-core","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-transformer-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-transformer-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for GraphQL AST manipulation. Ensure its version matches the transformer's internal dependency for compatibility.","package":"graphql","optional":false}],"imports":[{"note":"The primary class for schema transformation. This is the entry point for programmatic schema transformation.","symbol":"GraphQLTransform","correct":"import { GraphQLTransform } from '@aws-amplify/graphql-transformer-core'"},{"note":"Type definition for the configuration object passed to `GraphQLTransform`, specifying the schema and transformers to apply.","symbol":"TransformConfig","correct":"import { TransformConfig } from '@aws-amplify/graphql-transformer-core'"},{"note":"Interface representing the context available during schema transformation, primarily used when developing custom GraphQL transformers.","symbol":"TransformerContext","correct":"import { TransformerContext } from '@aws-amplify/graphql-transformer-core'"},{"note":"An example of a specialized transformer (from a separate package) that extends the core functionality to handle the `@model` directive.","symbol":"ModelTransformer","correct":"import { ModelTransformer } from '@aws-amplify/graphql-model-transformer'"}],"quickstart":{"code":"import { GraphQLTransform } from '@aws-amplify/graphql-transformer-core';\nimport { ModelTransformer } from '@aws-amplify/graphql-model-transformer';\nimport { AuthTransformer } from '@aws-amplify/graphql-auth-transformer';\nimport { print, parse } from 'graphql';\n\nasync function generateCloudFormation() {\n  const schema = `\n    type Post @model @auth(rules: [{ allow: public, operations: [read] }, { allow: owner, ownerField: \"owner\" }]) {\n      id: ID!\n      title: String!\n      content: String\n      owner: String\n    }\n\n    type Comment @model {\n      id: ID!\n      post: Post @hasOne\n      text: String!\n    }\n  `;\n\n  const transformers = [\n    new ModelTransformer(),\n    new AuthTransformer(),\n    // You would include other transformers (e.g., ConnectionTransformer) here\n  ];\n\n  const transform = new GraphQLTransform({\n    schema,\n    transformers,\n  });\n\n  try {\n    const output = await transform.transform();\n    console.log('Generated CloudFormation template (truncated):');\n    // In a real scenario, you'd save `output.stacks.Root.json` to a file.\n    const cfnTemplate = JSON.stringify(output.stacks.Root.json, null, 2);\n    console.log(cfnTemplate.substring(0, 500) + '\\n...(truncated for brevity)');\n\n    console.log('\\nGenerated GraphQL Schema (truncated):');\n    // The transformed schema with additional types and directives can also be accessed.\n    const transformedSchemaSDL = print(parse(output.schema));\n    console.log(transformedSchemaSDL.substring(0, 500) + '\\n...(truncated for brevity)');\n\n  } catch (e) {\n    console.error('Error during transformation:', e);\n  }\n}\n\ngenerateCloudFormation();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0 (Amplify CLI / Transformer V2 release)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0 (Amplify CLI / Transformer V2 release)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, more prominent with V2 migration"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Data source with name NONE_DS is now preventing amplify push from succeeding."},{"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`.","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.","error":"Expected type AuthStrategy, found private."},{"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.","cause":"Your Amplify project's GraphQL API is still using the V1 GraphQL Transformer, and a new version (V2) is available and recommended.","error":"GraphQL API has a new version. Run 'amplify migrate api' to migrate your schema to the new version."},{"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.","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.","error":"ValidationError: Only one resolver is allowed per field."}],"ecosystem":"npm"}