GraphiQL Spark

Demo a GraphQL schema without a GraphQL endpoint.

What & Why?

GraphiQL Spark allows you to run queries or mutations completely client side! In addition the query/mutation response is rendered once GraphiQL is mounted, which makes it ideal for blog posts.

Note: Out of the box GraphiQL requires you to press the play button to run the query and see the results.

See the demo video below on how to use it:

How is it different to GraphiQL?

Not by much. GraphiQL Spark is thin convinience layer on top of GraphiQL.

Benefits

No Downtime (your static site might work, but the GraphQL endpoint might be down)
No Server Cost (why pay for demoing a GraphQL concept on your blog?)
Faster feedback loop (no network request)

Downsides

Requires the packages graphql & graphl-tool which adds ~64kb (minified + gzipped) to the bundle.

Install

# npm
npm install --save graphiql-spark
# yarn
yarn add graphiql-spark

Usage

import React from "react";
import GraphiQlSpark from "graphiql-spark";
import "graphiql/graphiql.css";

// Schema defined in the Schema Definition Language
const typeDefs = `
  type Post {
    title: String
  }

  type Query {
    posts: [Post]
  }
`;

// Client-side resolvers
const resolvers = {
  Query: {
    posts: () => [
      { title: "Advanced GraphQL Concepts" },
      { title: "Why I Write CSS in JavaScript" }
    ]
  }
};

// Example query
const query = `query {
  posts {
    title
  }
}
`;

export default function SimpleExample() {
  return (
    <div style={{ height: "25rem", border: "1px solid #e0e0e0" }}>
      <GraphiQLSpark query={query} resolvers={resolvers} typeDefs={typeDefs} />
    </div>
  );
}

More Examples

Please check out the docs at https://nikgraf.github.io/graphiql-spark/

FAQ

Are relations (mutually-recursive resolver) possible?

Yes

Are Mutations supported?

Yes

Are Subscriptions supported?

No, but I would welcome a proposal on how this could be done.

How does it work?

GraphiQL Spark builds a Schema locally in the browser and then directly can invoke the Schema instead of using a Transport Layer like HTTP.

Can I use it with GraphQL Nexus or other Code-First Schema Generators?

Not yet, but probably makes sense to publish such a version. Ping me if you are interested to help. Ideally it would be a named export, but we make sure non-used dependencies are tree-shaked.

Inspiration

Once upon a time I was giving a GraphQL beginner workshop using the The Star Wars API example. I wanted that in this example every GraphQL request is not more than a simple HTTP request. My attempt to demo this live failed since the example was built in a way that the production version would include a client side schema.

Once I started working on a new personal blog covering GraphQL concepts I was looking for a way to provide executable examples (instead of pasting text or images). And instead of finishing my blog post I procrastinated and built this tool 😄

Contributing

yarn start

This builds to /dist and runs the project in watch mode so any edits you save inside src causes a rebuild to /dist.

To do a one-off build for production, use yarn build.

Docs / Examples

To run the docs locally (the examples are helpful during development) inside another tab run:

cd example
yarn # install dependencies
yarn start

The build command yarn build inside the example directory is optimized for generating the docs.

nikgraf / graphiql-spark