Registry /
aws / graphql-transformer-core
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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();
Debug
Known issues
breakingThe 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.fixRefer 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.
affects: >=7.0.0 (Amplify CLI / Transformer V2 release)
gotchaWhen 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.fixCheck the `peerDependencies` or `dependencies` of `@aws-amplify/graphql-transformer-core` for the required `graphql` version and install a compatible version in your project.
affects: All versions
breakingThe 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.fixReview 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.
affects: >=7.0.0 (Amplify CLI / Transformer V2 release)
gotchaRepeated 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.fixMonitor 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.
affects: All versions, more prominent with V2 migration
Errors
Common errors & fixes
Data source with name NONE_DS is now preventing amplify push from succeeding.
During GraphQL Transformer V1 to V2 migration, or after schema changes, sometimes a 'NONE_DS' (none data source) can remain or be incorrectly referenced.
fixManually 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.
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.
fixVerify 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.
Your Amplify project's GraphQL API is still using the V1 GraphQL Transformer, and a new version (V2) is available and recommended.
fixExecute `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.
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.
fixThis 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.
Audit
Dependencies
graphqlrequiredRuntime peer dependency for GraphQL AST manipulation. Ensure its version matches the transformer's internal dependency for compatibility.