GraphQL Configuration Protocol

[asiandrummer]

GraphQL Configuration protocol

In a nutshell, the simplest format is:

export type GraphQLConfiguration = {
  schemaPath?: FilePath,  // may be .json or .graphql
  schemaUrl?: URL,
  schemaJS?: ModulePath | ModuleName,
  // If env is specified, use one of the app configs in here
  env?: GraphQLConfigurationEnvs

  // For multiple applications with overlapping files, bottom configuration options may be helpful
  includeDirs?: Array<DirPath>,
  excludeDirs?: Array<DirPath>,

  // If you have customized validation rules to run
  customValidationRules?: FilePath | Array<FilePath>,

  // If you'd like to specify any other configurations, we provide a reserved namespace for it
  extensions?: GraphQLConfigurationExtension
};

export type GraphQLConfigurationEnvs = {
  production: GraphQLConfiguration,
  development: GraphQLConfiguration,
  // but really just the below
  [envVarName: string]: GraphQLConfiguration
};

export type GraphQLConfigurationExtension = {
  [toolName: string]: any,
};

Note that I'd like to discourage the recursive pattern in using the EnvironmentalVariable - for example:

{
  "schemaPath": "...",
  "env": {
    "production": {
      "appProd": {
        // BEWARE OF THE BELOW PATTERN!
        "env": { ... }
      }
    }
  }
}

Now the reasoning for it: let's start with a most simple use case - one app/one schema.

Single-app/single-schema

Usually a single app requires a schema path/url and an env variable to facilitate the build and deployment:

export type GraphQLAppConfig = {
  schemaPath: FilePath,
  schemaUrl: URL,
  env: EnvironmentVariable
};

export type EnvironmentVariable = {
  [envVarName: string]: GraphQLAppConfig
};

Multiple-apps/isolated directories

For multiple apps with isolated directories, I like @wincent's idea about a common-default GraphQL configurations, but in spirit of keeping things simple at first, I'd like to propose an one-config-per-directory approach as our first draft. I think there's an edge case where we'd have multiple parent GraphQL configurations to consider:

./repo/.graphqlrc
./repo/appFamily/.graphqlrc
./repo/appFamily/app1/.graphqlrc

This can become a discussion of its own, which we can have separately ;)

Custom validation rules

You may want to run custom validation rules before building GraphQL apps/codegen/etc - customValidationRules is useful for that.

Reserved namespaces

@wincent made a suggestion to provide a way to include any other configurations if you desire. This namespace will contain an app/prod/organization/team-specific GraphQL configurations, and it will be treated as optional settings you'd like to use for your purpose.

{
  "schemaPath": "path/to/schema",
  "extensions": {
    "my-tool": {
      "here": "This is a tool-specific extension"
    }
  }
}

What is this repo, then?

I think this repo should serve two roles in a broader sense:

1. Maintain this protocol and become a town hall for discussions/improvements for this protocol.
2. Provide reference implementations of helper methods to lubricate adoption for this protocol.

An example of the reference implementation of the helper method: we mentioned a way to find this GraphQL configuration is to walk up a directory until it finds one. This basically can be implemented as such:

/**
 * (From `graphql-language-service` repo:
 * Finds a .graphqlrc configuration file, and returns null if not found.
 * If the file isn't present in the provided directory path, walk up the
 * directory tree until the file is found or it reaches the root directory.
 */
export function findGraphQLConfigDir(dirPath: string): ?string {
  let currentPath = path.resolve(dirPath);
  while (true) {
    const filePath = path.join(currentPath, '.graphqlrc');
    if (fs.existsSync(filePath)) {
      break;
    }
    if (isRootDir(currentPath)) {
      break;
    }
    currentPath = path.dirname(currentPath);
  }
  return !isRootDir(currentPath) ? currentPath : null;
}

function isRootDIr(path: string): boolean {
  return path.dirname(path) === path;
}

As there are several use cases, we can tackle each of them and present a way to use this configuration programmatically. I can begin by identifying/suggesting some of them below:

• A generalized module bundler configurations, using GraphQL configurations
  • webpack, yeoman, babel, and etc...
• How to include custom validation rules in your application
• How to generate schema with provided schema path(s)
  • Sending introspection query to the endpoint
  • Parsing/building the schema using a local file path
  • Compiling GraphQLSchema object using schema definitions in .js
  • How to cache the schema
    • local files, indexedDB, and etc...

Action items

There are many things to do! But when we successfully deliver this, I believe we can get to the point where we have a shared GraphQL configuration that everyone agrees on, with commonly-used techniques and best practices to configure your GraphQL environment.

• Write a draft for this protocol
• Populate this repository with those helper methods
  • Discuss what the superset of those helper methods would be
  • Prioritize by the most impactful and common ones and implement them
  • Generalize existing implementations and move them here
• Update other remaining documentations, including this repo's README
• Suggest GraphQL configuration as a best-practice at graphql.org

Lastly, although we've begun this proposal and made a bunch of suggestions, I'd love to have a collaborative effort in pushing this forward. It'll be amazing to see us working together to improve and deliver this proposal to the GraphQL community.

Please post your thoughts/concerns/questions! Also if you'd like to be responsible for one of the actions items above, don't be hesitate to do so :D

[nodkz]

@asiandrummer very clean! I'd like it.

1. Small fixes by schema definition:

- env?: EnvironmentVariable,
+ env?: GraphQLConfigurationEnvs, 
- extension?: Any,
+ extension?: GraphQLConfigurationExtension,   

+ export type GraphQLConfigurationExtension = {
+  [toolName: string]: any,
+ };

2. And where I should add schemaEntrypoint path to the schema js file which exports GraphQLSchema (in the root or under extension key)? Of course, I would like to see this common config key along with schemaPath and schemaUrl.

[asiandrummer]

@nodkz edited with suggestions! For 2., I added schemaJS to specify the schema constructed with graphql-js.

[nodkz]

@asiandrummer schemaJS is not a better name if we want to keep .graphqlrc agnostic to programming language. I agree that schemaEntrypoint also not so good as wanted.

[asiandrummer]

@nodkz I'm also terrible at naming things ;) I'm open to other suggestions please!
Also, I propose .graphqlconfig instead of .graphqlrc.

[asiandrummer]

Another addition that may come later is a glob pattern for locating directories:

{
  "inputDirs": [ "**/apps" ],
}

[asiandrummer]

@nodkz @schickling I'm going to write something up to be included in graphql.org page soon - I'll cc both of you to the PR/issue in that repo when I create one!

[asiandrummer]

Progress update: I haven't spent much time to work on this until today - but I still wanted to communicate how I thought the further process should be.

1. Write up the best practices proposal to graphql.org (@asiandrummer)
2. Implement/move over the wrapper/GraphQLConfig code to this repo (up for grabs)
3. Open pull requests to the major GraphQL libraries to integrate the proposed GraphQL configuration (continuous effort from everyone!)

I'm in progress of completing (1), and will open a PR once done and include stakeholders. The whole progress has been somewhat stagnant and I apologize for the delay, and I'll make sure to spend time to work on this consistently.

For that, I have some sort of deadline in my mind (by the end of March) to finish this project.

[schickling]

Thanks a lot for that great progress update. We're happy to tackle (2). Should be feasible within the next week. I'll ping you in Slack to coordinate on this.

[mjmahone]

I'm trying to wrap my head around what the inputs/outputs of something utilizing this config is supposed to be.

I think it's

• input: some schema file + files containing GraphQL definitions
• output: a validated base schema, parsed GraphQL AST, and maybe a schema that includes any extensions from the definitions files.

One of the problems I've run into, is that I need to parse graphql from a lot of different sources: JS files, .graphql files, schema files, etc., and the AST coming out of each individual source is often not able to be validated until combined with all the other AST sources. As such, I think GraphQLConfiguration should support combining files that need to be parsed in entirely different ways, apply a schema to the parsed result, so you can get a validated schema + definitions.

Some tweaks I'd propose making:

• Split the internals of GraphQLConfiguration into a ParsingConfiguration and SchemaConfiguration.
• A GraphQLConfiguration is then a union of a list of ParsingConfigurations, a SchemaConfiguration, and validation rules.

Additionally, it seems like env should always live outside, not inside, the configuration. Each configuration describes a single environment (whether that's production or development or separate apps). When parsing raw files, you can choose to use multiple configurations, and switch to the relevant configuration (you might have a map of map of configurations, if you have 3 different apps to configure, each with their own environments. But that should be fine).

[asiandrummer]

@mjmahone

As such, I think GraphQLConfiguration should support combining files that need to be parsed in entirely different ways, apply a schema to the parsed result, so you can get a validated schema + definitions.

Wouldn't we be still able to use extensions and includeDirs (I renamed it from inputDirs) to do this? The different file types could be determined with the extension name, and then it'll be a matter of differentiating the parsing method after consuming the configuration file.

re: env variables

The env variables could certainly be used in that way, but I could see how this could be useful if, during the build/compile time, the tool used wants to choose a different environment. I prefer to separate those using app configs though

[asiandrummer]

cc @nodkz @schickling @mjmahone @wincent @martijnwalraven - including everyone who participated in the discussions for a final review.

I've taken some time to get more feedbacks internally from Facebook, iterate on the writing a few times, and drafted up a final version of what I'll create an issue with Monday to graphql.org. I'd appreciate if you could take a look - we can also continue the discussion in the issue I'll be creating.

The most notable changes are the addition of projects property and introducing the "experimental
configuration options" field. The previous draft was comprehensive in supporting various use cases, but 1) it included a possible recursive pattern in properties like env that made the configuration more complex than it should be, and 2) it included properties that aren't supported in different codebases, and I think adoption will be easier if we started with minimal configurations and iterate on it to support more use cases.

For the reason above, I've moved env property to "experimental configuration options" - @nodkz I'd love to chat with you periodically to be able to include this as one of the "official recommendations". Until then, I propose we keep testing env property by having it in the extensions property, and with some more use cases I hope we can include in the official recommendation.

Lastly, for the starters, I'll be submitting a few PRs to make graphql-config a place for util functions and/or the reference implementations of them. They won't be as comprehensive as we'd like them to be, but hopefully with the additions for those util functions we'd be able to claim this repository the place for them.

GraphQL Configuration

There are many ways to configure your application to use GraphQL, and while it is often enough to specify configuration options directly in your application code, maintaining and understanding the hard-coded configuration options may become a challenge as the scale grows. We recommend configuring your application with a .graphqlconfig file that contains commonly needed GraphQL-related artifacts.

GraphQL Configuration Format

After inspecting many GraphQL applications for use cases and communicating with many external contributors, we recommend configuring your GraphQL application with a below format:

// For the ease of understanding/formatting, we're using a
// Flow-like type to define the configuration format.

type GraphQLConfiguration =
  GraphQLProjectConfiguration & {
    projects?: {
      [projectName: string]: GraphQLProjectConfiguration
    }
  };

type GraphQLProjectConfiguration = {
  schemaPath?: string, // a file with schema IDL
  schemaUrl?: URL,

  // For multiple applications with overlapping files,
  // these configuration options may be helpful
  includeDirs?: Array<DirPath>,
  excludeDirs?: Array<DirPath>,

  // If you'd like to specify any other configurations,
  // we provide a reserved namespace for it
  extensions?: {[name: string]: GraphQLConfigurationExtension}
};

type GraphQLConfigurationExtension = {
  [name: string]: mixed
};

Use Cases

Usually, for a simple GraphQL applications, the only required configuration is a way to fetch a GraphQL schema:

{
  "schemaPath": "./schema.graphql"
}

Although it is possible for the configuration file to have more than one way to fetch the schema, a GraphQL application consuming this configuration should determine how to work with provided configuration properties. For example, while one application may arbitrarily choose to have schemaPath take precedence over schemaUrl, another may choose to throw and error when both are provided. The behavior in this case is explicitly undefined.

{
  // How to resolve this is up to the application
  "schemaPath": "./schema.graphql",
  "schemaUrl": "http://my-app.com/schema"
}

For multiple apps with isolated directories, there are mainly two ways to set up the configuration. Each app can either use the projects property to specify each application's configuration, or have a separate .graphqlconfig file for each project root.

{
  "projects": {
    "appA": {
      "schemaPath": "./appA/appASchema.graphql"
    },
    "appB": {
      "schemaPath": "./appB/resources/appBSchema.graphql"
    }
  }
}

Or each can app have a separate .graphqlconfig file per each application and/or directories:

./appA/.graphqlconfig
./appB/.graphqlconfig

Default Configuration Properties

Treat the top-level configuration properties as default values to use if a project configuration scope omits them.

Consider the below GraphQL configuration:

{
  {
    "projects": {
      "projectA": {
        "schemaPath": "./resources/schema.graphql",
        "includeDirs": "./projectA/graphql"
      },
      "projectB": {
        "schemaPath": "../resources/schema.graphql",
        "includeDirs": "./projectB/graphql"
      },
      "projectC": {
        "schemaPath": "./schema-for-projectC.graphql"      }
    }
  }
}

Since projectA and projectB share the same schema file, we can push the schemaPath property to the top level, and treat it as a default value for a schema path. In this case, the application using this configuration should treat each project config as a more specific scope, and look at the top level scope with default properties as a fallback.

{
  "schemaPath": "./resources/schema.graphql",
  {
    "projects": {
      "projectA": {
        "includeDirs": "./projectA/graphql"
      },
      "projectB": {
        "includeDirs": "./projectB/graphql"
      },
      "projectC": {
        // "schemaPath" in this scope should take precedence
        "schemaPath": "./schema-for-projectC.graphql"
      }
    }
  }
}

Extensions as Namespaces

If your application requires a unique configuration option, use the extensions attribute to customize your own configuration option.

Additionally, we'd like to treat the extensions property as a sandbox for improving the overall GraphQL configuration. If there is a configuration option that you think will be useful for general purposes, please let us know! Meanwhile, take advantage of this 'extensions' for testing purposes.

For example, some application may choose to build using Webpack and need to specify Webpack-related configurations in GraphQL configuration. Also, they may need to process additional file types other than .graphql. Below suggests one way to configure these options using 'extensions':

{
  "schemaPath": "...",
  "extensions": {
    "webpack": {
      // Webpack-specific options here!
    },
    // additional file types that you want to process
    "additionalFileTypes": [ '.js' ]
  }
}

Experimental Configuration Options

Below are what we're experimenting with for additional fields. Before including in the official recommendation, we would like to iterate on a few different codebases first.

'Env' Variable

An env property is useful to facilitate the build and deployment if your application needs to introduce a GraphQL-specific environment variable and run build steps with it:

// run a development build with a production GraphQL database 
GRAPHQL_ENV=production && NODE_ENV=development && babel-node ./server.js

Also, an env property allows an easier adoption of this GraphQL configuration format for non-JavaScript codebases.

The proposed usage for the property is as follows:

{
  "schemaPath": "./schema.graphql",
  "env": {
    "production": {
      "schemaUrl": "http://your-app.com/graphqlschema"
    },
    "development": {
      "schemaPath": "./dev-schema.graphql"
    }
  }
}

GraphQL configurations do not support this property because there isn't a clear example how to utilize this property yet.

Configuring a schema defined programmatically

Suppose you have a schema defined using objects from graphql-js:

// In schema.js,
const queryType = new GraphQLObjectType({ name: 'Query' });
export const schema = new GraphQLSchema({ query: queryType });

Because this is a valid GraphQL schema that can be used within applications, we want to provide a way to configure the schema defined in this way:

{
  "schemaModule": "./schema.js"
}

This is not yet supported in GraphQL configuration because we're not sure what shape the type for the exported module is, nor whether this belongs in a JS-specific sub-configuration.

Including a set of customized validation rules

Sometimes a GraphQL application wants to either define an additional set of validation rules or specify a list of validation rules to be run at build/runtime. The GraphQL configuration can be a good place to locate where to look for this:

// In customRules.js,
export const customRules: Array<(context: ValidationContext) => any> = { ... };

// And in .graphqlconfig, specify where the custom rules are:
{
  "customValidationRules": "./customRules.js"
}
{
  "customValidationRules": [ "./customRules.js", "./moreCustomRules.js" ]
}

We're not yet officially supporting these rules, because many GraphQL tools don't yet have a way of using additional validation rules.

Helper/example libraries

To illustrate the GraphQL configuration in code as well as the behaviors defined in this documentation, we've collaborated to provide a few helper libraries for GraphQL configuration:

• https://github.com/graphcool/graphql-config
  • TODO: explain the util functions in this repo and how they work
  • TODO: actually PR out some util functions
• https://github.com/graphql/graphql-language-service