Split your AWS AppSync schema across multiple files

#api #automation #aws #node

If you’re working with AWS AppSync or any modular GraphQL API, you’ve probably want to split your schema across multiple files. This is great for developer sanity—but AppSync prefers a single .graphql file.

Let’s automate that.

This post walks through a simple Node.js script that uses the @graphql-tools ecosystem to:

✅ Load and merge your GraphQL schemas
✅ Resolve conflicts
✅ Write the final result to a single .graphql file
✅ load schema into your AppSync deployment flow

🛠 Setup

Install the necessary dependencies:

npm install @graphql-tools/load-files @graphql-tools/merge graphql

📦 Your Project Structure

Assume your project is organized like this:

project-root/
├── appsync/
│   ├── mutations/
│   │   └── addCustomer.graphql
│   ├── queries/
│   │   └── getCustomer.graphql
│   └── schema_chatbot_quicksight_merged.graphql (output)
├── mergeSchemas.js

🧩 The Merge Script

Here’s the full script to merge your GraphQL schema files:

import { loadFilesSync } from "@graphql-tools/load-files";
import { mergeTypeDefs } from "@graphql-tools/merge";
import { print } from "graphql";
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

try {
    const __filename = fileURLToPath(import.meta.url);
    const __dirname = path.dirname(__filename);
    const mergedFileName = "schema_chatbot_quicksight_merged.graphql";
    const outputPath = path.join(__dirname, "./appsync", mergedFileName);

    const typesArray = loadFilesSync(path.join(__dirname, "./appsync/**/*.graphql"), {
        extensions: [".graphql"],
        ignore: [mergedFileName],
    });

    if (!typesArray || typesArray.length === 0) {
        throw new Error("No GraphQL schema files found");
    }

    console.log(
        "Loaded files:",
        typesArray.map((t) => t?.loc?.source?.name || typeof t),
    );

    const mergedTypeDefs = mergeTypeDefs(typesArray, {
        all: true,
        throwOnConflict: true,
    });

    const sdl = print(mergedTypeDefs);

    const outputDir = path.dirname(outputPath);
    if (!fs.existsSync(outputDir)) {
        fs.mkdirSync(outputDir, { recursive: true });
    }

    fs.writeFileSync(outputPath, sdl);
    console.log(`✅ Merged schema written to appsync/${mergedFileName}`);
} catch (error) {
    console.error("❌ Error merging GraphQL schemas:", error.message);
    process.exit(1);
}

🚀 Using It in AWS CDK

Once your merged schema is generated, you can use it directly in your CDK stack with aws-cdk-lib/aws-appsync.

Here’s an example:

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import * as appsync from "aws-cdk-lib/aws-appsync";
import * as path from "path";

export class AppsyncStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const api = new appsync.GraphqlApi(this, "graphql-api", {
      name: "ChatbotQuickSightApi",
      schema: appsync.SchemaFile.fromAsset(
        path.join(__dirname, "../appsync/schema_chatbot_quicksight_merged.graphql")
      ),
      authorizationConfig: {
        defaultAuthorization: {
          authorizationType: appsync.AuthorizationType.API_KEY,
        },
      },
      xrayEnabled: true,
    });

    new cdk.CfnOutput(this, "GraphQLAPIURL", {
      value: api.graphqlUrl,
    });
  }
}

🧠 Tip

You can run your mergeSchemas.js script as part of your CDK build pipeline. For example:

"scripts": {
  "prepare-schema": "node mergeSchemas.js",
  "build": "npm run prepare-schema && cdk synth"
}

🧼 Why This Matters

Keep your schema modular for readability and reuse
Deliver a single file AppSync expects without error-prone copy/paste
Enable CI/CD integration with schema validation and bundling in one step

DEV Community