ruru

A Grafast-enhanced distribution of GraphiQL.

PRERELEASE: this is pre-release software; use at your own risk and do not embed into public-facing projects. This will likely change a lot before it's ultimately released. The pre-release nature also explains the shocking lack of documentation.

Usage - Instant!

If you have Node installed, you can instantly run ruru without permanently installing it using the npx command. Here's an example command to explore @trevorblades's countries API:

npx ruru@beta -SPe https://countries.trevorblades.com/graphql

(-S enables subscriptions, -P proxies GraphQL requests; neither of these are needed for Trevor's API, but you might want them for your API.)

Usage - CLI

Install Ruru:

yarn add ruru@beta

Then you can run something like the following to automatically proxy requests (bypassing CORS issues):

yarn ruru -SPe http://localhost:5678/graphql

Usage:

ruru

Run a Ruru server

Options:
      --help                   Show help                                                                      [boolean]
      --version                Show version number                                                            [boolean]
  -e, --endpoint               endpoint for query and mutation operations
                                                                    [string] [default: "http://localhost:5678/graphql"]
  -p, --port                   port number to run the server on                                [number] [default: 1337]
  -P, --proxy                  Proxy requests to work around CORS issues                                      [boolean]
  -S, --subscriptions          enable subscriptions, converting --endpoint to a ws:// URL    [boolean] [default: false]
  -s, --subscription-endpoint  endpoint for subscription operations (overrides -S)                             [string]

Usage - bundle

<!-- optionally import Prettier for query formatting -->
<script src="https://unpkg.com/[email protected]/standalone.js"></script>
<script src="https://unpkg.com/[email protected]/parser-graphql.js"></script>
<!-- Required below here -->
<div id="ruru-root"></div>
<link href="https://unpkg.com/graphiql/graphiql.min.css" rel="stylesheet" />
<script crossorigin src="https://unpkg.com/ruru/bundle/ruru.min.js"></script>
<script>
  const { React, createRoot, Ruru } = RuruBundle;
  const tree = React.createElement(Ruru, {
    endpoint: "/graphql",
  });
  const container = document.getElementById("ruru-root");
  const root = createRoot(container);
  root.render(tree);
</script>

Usage - library

import { Ruru } from "ruru-components";
import "graphiql/graphiql.css";
import "@graphiql/plugin-explorer/dist/style.css";
import "ruru-components/ruru.css";

React.render(<Ruru endpoint="/graphql" />);

Usage - middleware

import { ruruHTML } from "ruru/server";

// ...

app.get("/", (req, res, next) => {
  res.writeHead(200, { "Content-Type": "text/html" });
  return res.end(
    ruruHTML({
      endpoint: "/graphql",
    }),
  );
});

Why "ruru"?

Jem and I are big fans of the late Terry Pratchett's Discworld universe. The city at the centre of many a Discworld tale is the twin-city city-state of Ankh-Morpork. A "morepork" is a type of New Zealand owl, known in Māori as "ruru." Owls have excellent sight, and Ruru helps you to get an insight into not just the inputs and outputs of your API, but also what it does internally.

RURU is also an abbreviation for checks to use when gathering information: "is it Reliable, Up-to-date, Relevant, and Useful?" We hope that you'll find Ruru to be all those things!

... in the Quechua languages, the term "ruru" may refer to, among other things, "testicle." So when your GraphQL operation isn't doing what you expect and you're thinking to yourself "this is b*ll*cks," then you'll know this is a job for Ruru!

GNU Terry Pratchett