`.graphqlrc` redesign proposal

@schickling and a group of contributors including myself discussed how a common GraphQL configuration would look like, and thought of redesigning the current implementation of graphql-config as well as including some new suggestions. Since GraphQL-powered environments usually include information about the common set of GraphQL artifacts (such as the location and specifications within the application directory), the idea is basically to recommend a commonly-used format/options within .graphqlrc, and provide some helper methods and use cases from other applications that already incorporate this concept.

A minimal .graphqlrc config file would consist of a JSON blob such as:

// Let's assume there is a directory that acts as one repository.
// For a single application within a directory,
{
  "schema-path": "url/to/your/endpoint/or/local/schema/path",
}
// For more than one application within a directory,
{
  "app-1-name": {
    "schema-path": "url/to/your/schema"
  },
  "app-2-name": {
    "schema-path": "url/to/your/schema"
  }
}

To support more use cases, .graphqlrc would have a potential to evolve into something a bit more complicated. For instance, user might need to specify which sub-directories to look into for .graphql files and other GraphQL-related artifacts. Also, schema-path can be a local path to the GraphQL schema definition within the application, or an URL to the endpoint that would be used to fetch GraphQL introspection.

To list these capabilities below:

{
  "app-1-name": {
    "schema-path": "url/to/your/schema",
    // the list of directories to look for GraphQL artifacts/queries
    "input-dirs": [
      "foo/bar",
      "foo/bar/baz"
    ],
    // the list of directories to ignore while looking for GraphQL artifacts/queries
    "exclude-dirs": [
      "a/b/c"
    ],
    // specifying customized validation rules if available
    "custom-validation-rules": "./customRules.js"
  },
  "app-2-name": {
    "schema-path": {
      "endpoint-url": "https://url",
      "local-schema-path": "./schema.graphql"
    },
    ...
  }
}

In a pseudo-flowtype format:

type GraphQLRC = {
  [appName: string]: GraphQLAppConfig
} | GraphQLAppConfig;

type GraphQLAppConfig = {
  schemaPath: URL | FilePath | {
    endPoint?: URL,
    localSchemaPath?: FilePath
  },
  inputDirs?: Array<DirPath>,
  excludeDirs?: Array<DirPath>,
  customValidationRules?: FilePath | Array<FilePath>
};

Note that these are not at all requirements - these specifications, I believe, will serve as an example for how to set up configurations for various GraphQL app use cases. From the above format I’ve suggested all config properties to be optional except for schemaPath.

@wincent and @jimkyndemeyer made a great suggestion that we provide some helpful tools/guidelines related to the configuration details we’re proposing. Some examples are described below:

• How would one discover .graphqlrc file programmatically from the top-level/sub-directories?
• How would one fetch/parse/build a GraphQL schema from the introspection endpoint specified in schema-path?
• Given a .graphql file in a repository, how would one recognize which app config to use?
• How would configured custom validation rules be used?
• How could existing GraphQL configurations be migrated into using this proposed .graphqlrc approach?

Finally, we’re planning to propose this concept as one of “Best Practices” in graphql.org once it matures.

Please feel free to add/let me know if I’ve missed anything from our conversation @schickling and @wincent! I’m looking forward to see how this shapes up.

[nodkz]

@asiandrummer can we split schemaPath on separate vars for localPath and url? Some tools will work only with path, other may support urls. So will be better just provide two vars (eg. schemaPath: FilePath, schemaUrl: URL) instead of union.

Also "env": { "production": "prodUri", "dev": "devUri" } is not good simplification. Tools maintainers curse you 🤗. Let keep it ready for simple merge function call and futher format extension. So it should be:

{
  "schemaPath": "path",
  "env": { 
    "production": { "schemaPath": "prodPath" }, 
    "dev": { "schemaPath": "devPath" }
  }
}

So in JS config under some environment can be fastly assembled in such way without deep merging:

opts = { ...config, ...config[GRAPHQL_ENV || NODE_ENV || 'dev']};

Dot config files intended mostly for programs/tools and less for humans.

[wincent]

I think YAML is pretty readable, and in some ways easier to write, compared to JSON. There may be some precedent for tools being agnostic about whether stuff is stored in YAML or JSON, although I can’t remember specific examples right now.

I do like the idea of starting with a declarative format that can be consumed from any language (not .js, which can only be consumed by evaluating it, and that’s not so easy to do from outside JavaScript), and both YAML and JSON satisfy that. One question would be, should we:

• Auto-detect .graphqlrc format type by sniffing the file contents, and then parsing using the appropriate tool (YAML or JSON)? This would unfortunately mean that all tools would have to implement support for both if they wanted to consume an arbitrary .graphqlrc file.
• Assume JSON by default, but fall back to .graphqlrc.yml (explicit extension). In this case, how to resolve the ambiguity if the filesystem contains more than one of .graphqlrc, .graphqlrc.yaml and .graphqlrc.json?

At least to begin with, I think it’s probably safest to start narrow and assume/require JSON, but consider extending to include YAML support once some of the above questions have been resolved.