Absinthe.Plug

Plug support for Absinthe, the GraphQL toolkit for Elixir.

Please see the website at http://absinthe-graphql.org.

Installation

Install from Hex.pm:

def deps do
  [{:absinthe_plug, "~> 1.5"}]
end

Note: Absinthe.Plug requires Elixir 1.10 or higher.

Absinthe.Plug also requires a JSON codec. Jason and Poison work out of the box.

def deps do
  [
    ...,
    {:absinthe_plug, "~> 1.5"},
    {:jason, "~> 1.0"}
  ]
end

Upgrading

See CHANGELOG for upgrade steps between versions.

You may want to look for the specific upgrade guide in the Absinthe documentation.

Documentation

See "Usage," below, for basic usage information and links to specific resources.

• Absinthe.Plug hexdocs.
• For the tutorial, guides, and general information about Absinthe-related projects, see http://absinthe-graphql.org.

Related Projects

See the GitHub organization.

Usage

In your MyAppWeb.Router module add:

plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json, Absinthe.Plug.Parser],
  pass: ["*/*"],
  json_decoder: Jason

plug Absinthe.Plug,
  schema: MyAppWeb.Schema

If you want Absinthe.Plug to serve only a particular route, configure your MyAppWeb.Router like:

plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json, Absinthe.Plug.Parser],
  pass: ["*/*"],
  json_decoder: Jason

forward "/api",
  to: Absinthe.Plug,
  init_opts: [schema: MyAppWeb.Schema]

For more information, see the API documentation for Absinthe.Plug.

Phoenix.Router

If you are using Phoenix.Router, forward expects different arguments:

Plug.Router

forward "/graphiql",
  to: Absinthe.Plug.GraphiQL,
  init_opts: [
    schema: MyAppWeb.Schema,
    interface: :simple
  ]

Phoenix.Router

forward "/graphiql",
  Absinthe.Plug.GraphiQL,
  schema: MyAppWeb.Schema,
  interface: :simple

For more information see Phoenix.Router.forward/4.

GraphiQL

To add support for a GraphiQL interface, add a configuration for Absinthe.Plug.GraphiQL:

forward "/graphiql",
  to: Absinthe.Plug.GraphiQL,
  init_opts: [schema: MyAppWeb.Schema]

See the API documentation for Absinthe.Plug.GraphiQL for more information.

Incremental Delivery

Absinthe.Plug supports GraphQL @defer and @stream directives for incremental delivery over HTTP using Server-Sent Events (SSE). This enables real-time streaming of deferred fragments and list items while maintaining HTTP compatibility.

Key features:

• ✅ Server-Sent Events: Standards-compliant SSE implementation
• ✅ HTTP/2 Compatible: Efficient multiplexing support
• ✅ CORS Support: Cross-origin streaming capabilities
• ✅ Graceful Fallback: Automatic fallback to standard GraphQL responses

Installation with incremental delivery:

def deps do
  [
    {:absinthe, git: "https://github.com/gigsmart/absinthe.git", branch: "gigmart/defer-stream-incremental"},
    {:absinthe_plug, git: "https://github.com/gigsmart/absinthe_plug.git", branch: "gigmart/defer-stream-incremental"},
    {:plug, "~> 1.12"},
    {:jason, "~> 1.2"}
  ]
end

Example usage:

// Client-side SSE connection
const eventSource = new EventSource('/api/graphql/stream?' + new URLSearchParams({
  query: `
    query GetPosts {
      posts @stream(initialCount: 3, label: "posts") {
        id
        title
        ... @defer(label: "content") {
          content
        }
      }
    }
  `
}));

eventSource.addEventListener('initial', (event) => {
  const data = JSON.parse(event.data);
  console.log('Initial data:', data);
});

eventSource.addEventListener('incremental', (event) => {
  const increment = JSON.parse(event.data);
  console.log('Incremental data:', increment);
});

For comprehensive documentation on HTTP incremental delivery patterns, see Absinthe Incremental Delivery Guide.

Community

The project is under constant improvement by a growing list of contributors, and your feedback is important. Please join us in Slack (#absinthe-graphql under the Elixir Slack account) or the Elixir Forum (tagged absinthe).

Please remember that all interactions in our official spaces follow our Code of Conduct.

Contributing

Please follow contribution guide.

License

See LICENSE.md.