Home

Awesome

graphql-sunset

Easily add support for the Sunset header to your GraphQL server to better communicate upcoming breaking changes.

Usage

  1. Add a sunset directive to your schema.

    directive @sunset(
  url: String!
  when: String!
) on FIELD_DEFINITION

# ...

    💡 If you prefer more specific types (e.g. Instant! / URL!), then you can use them. If your GraphQL server parses these fields to something other than a string, you will need to specify a custom parseDirectiveArgs function when instantiating the plugin.

  2. Apply it to a field:

    type Query {
  greeting: String @sunset(
    url: "https://docs.your-app.com/removal-of-greeting"
    when: "2025-01-01T00:00:00.000Z"
  )
}

  3. Add the plugin to your Apollo server.

    import { ApolloSunsetPlugin } from 'graphql-sunset';

// ...

const server = new ApolloServer({
  // ...
  plugins: [
    new ApolloSunsetPlugin({
      directiveName: 'sunset',
      // parseDirectiveArgs
    }),
  ],
});

  4. Run a GraphQL operation, and see the Link and Sunset headers get populated:

    $ curl --include --request POST \
    --header 'content-type: application/json' \
    --url http://localhost:4000/ \
    --data '{"query":"query ExampleQuery {\n  greeting\n}"}'
HTTP/1.1 200 OK
...
sunset: Wed, 01 Jan 2025 00:00:00 GMT
link: <https://docs.your-app.com/removal-of-greeting>; rel="sunset"
...

{"data":{"greeting":"Bar"}}

Roadmap