graphql-schema-diff

🔍 Compare two GraphQL schemas (including Federation support) and generate Slack-ready payloads highlighting Breaking, Dangerous, and Safe changes.

Features

• Supports standard and Apollo Federation schemas
• Categorizes schema changes by criticality (Breaking, Dangerous, Non-breaking)
• Outputs a Slack-ready JSON payload
• Easy to integrate into GitHub Actions workflows
• Small, fast, zero-config

Installation

npm install graphql-schema-diff

usage

npx graphql-schema-diff --old schema.graphql --new schema-new.graphql

Or if installed globally:

graphql-schema-diff --old path/to/old-schema.graphql --new path/to/new-schema.graphql

Output The script outputs a Slack block payload formatted to:

• Group changes by criticality level (Breaking → Dangerous → Safe)
• Use Slack dividers, headers, and bullet points
• Optionally customize background colors or styling

Example snippet (truncated for clarity):

{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": ":bangbang:  Breaking changes:",
        "emoji": true
      }
    },
    { "type": "divider" },
    { /* breaking changes list */ },
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": ":warning:  Dangerous changes:",
        "emoji": true
      }
    },
    { "type": "divider" },
    { /* dangerous changes list */ }
  ]
}

Example usage in Github Actions

You can use it in your GitHub CI pipeline:

jobs:
  check-schema:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: npm install

      - name: Compare GraphQL schemas
        run: |
          npx graphql-schema-diff --old schema.graphql --new schema-new.graphql > slack-payload.json

      - name: Send to Slack
        uses: slackapi/[email protected]
        with:
          payload-file-path: ./slack-payload.json
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}