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

• Output fields
• Field arguments
• Input object fields
• Enum values
• Envelop server plugin