apollo-playground-maker v0.2.8

What Is It?

apollo-playground-maker (APM) is a plugin for graphql-codegen that generates comprehensive tab content for apollo-server graphQL playgrounds.

apollo-server allows you to pass an array of tab configurations as part of the playground setup. This lets us supply pre-populated tab-content for the playground. This could be used in a number of ways, but on our team we've been using it to easy testing/exploring graphQL operations decoupled from the front end code. Note this only makes sense if your graphQL API and your front-end app are tightly coupled, as in the backend for frontend pattern.

How It Works

apollo-playground-maker with it's default settings, will aggregate graphQL operations and attempt to group them in sensible tabs.

Tab Grouping

APM determine tab names by trimming shared path information and using the first divergence as the depth the use for tab names. For example, give the following directory structure:

components/
├── users
│   ├── GetProfile.gql
│   └── UpdateProfile.gql
└── posts
    ├── GetPost.gql
    └── responses
        └── GetResponses.gql

Non GQL Files

In addition to aggregating graphQL operations, APM can aggregate query responses and query variable.

Query Variables

APM can attempt to hydrate query variables in two different ways. When APM encounters a named variable inside an operation, i.e. query Animal($species: String), it will look for a species variable and add that to the query variables for the tab where the query will appear. APM will attempt to hydrate query variables only when passed the varFilename option.

Shared Global Var File

If the varFilename contains directory information i.e. src/queryVars.ts, APM will attempt to hydrate all queries from that single file.

Per-Directory Var File

If the varFilename contains NO directory information i.e. queryVars.ts, APM will look for a queryVars.ts file in the same directory as the operation utilizing the argument.

Response Text

If passed a responsesFilename option, APM will look for a responses file whererever .gql files are encountered, aggregating those per tab.

Endpoints and Headers

APM provides a sensible default for the endpoint of each tab (http://localhost:4000/graphql), but this may not always be appropriate. In circumstances where you need to adjust this (for example dev/qa/stage/prod all have different urls), it may be necessary to map the appropriate endpoint url onto the generated tabs. You might use the same approach for any headers you'd like to provide. For example:

const apolloPlaygroundTabs = require('generated/tabs.json');
const endpoint = getEndpointForThisEnv();
const tabs = apolloPlaygroundTabs.map((tabInfo) => ({
          ...tabInfo,
          endpoint,
          headers: { Authorization: 'basic-auth header' },
        }));

Options and Defaults

Example codegen.yml

overwrite: true
schema: "src/gql/schema.gql"
generates:
  generated/playgroundTabs.json:
    documents: "./src/components/other_dir/**/*.gql"
    plugins:
      - "apollo-playground-maker"
    config:
      varFilename: "./src/gql/queryVars.ts"
      docSortType: "content"
      varWarningReport: 'all'
      varWarningDetail: 'high'
      tabNamePrefix: 'server'