Stellate Configuration

When you use the Stellate CLI, you'll work with one configuration file, which is called stellate.<ts|js|mjs>. It's the central file to configure your service. From caching, over origin url to rate limiting (coming soon), this is the place to adjust your service.

If your current configuration file is called graphcdn.yml it will NOT automatically be renamed to stellate.yml (or stellate.ts). The CLI will print a warning message, but you will need to manually rename it, once you are ready.

Your config won't be automatically converted to the TypeScript/JavaScript format, instead newly created applications or new pulls without a config will result in the updated format.

To read more about rate limiting and how to configure that, check out the rate limiting api reference.


  • Name
    name
    Type
    Description

    The name of your service

  • Name
    schema
    Type
    Description

    A reference to your schema. It can be one of the following:

    • A URL like http://localhost:3000/graphql (only works if introspection is enabled)
    • A reference to a local schema.graphql file like ./api/schema.graphql
    • A reference to an SDL definition in your code like ./api/typeDefs.ts
  • Name
    originUrl
    Type
    Description

    The URL of your production backend you want your service to proxy to.

  • Name
    passThroughOnly
    Type
    Description

    A boolean that indicates whether caching is enabled for your service or if it operates in pass-through mode only.

  • Name
    queryDepthLimit
    Type
    Description

    An integer that indicates how deeply nested a query can be. A value of 0 disables the limit and is the default if the property is not provided. See Depth Limiting for more information.

  • Name
    injectHeaders
    Type
    Description

    Should your Stellate service inject the headers you provided into the edge? This might be required if you have some default headers that are always needed. Use this with care though, as you might expose unwanted auth data with this.

  • Name
    mutationPolicy
    Type
    Description

    Defining how Stellate automatically purges cached queries. See the mutation-policies documentation for more information on configuring mutation-policies.

  • Name
    enablePlayground
    Type
    Description

    Should your Stellate service serve a instance of GraphiQL?

  • Name
    headers
    Type
    Description

    A key-value map of headers and their values.

  • Name
    bypassCacheHeaders
    Type
    Description

    A list of headers to include if you want to bypass Stellate Edge Cache and always query your backend service. Including any one of those headers will trigger a cache pass.

  • Name
    rules
    Type
    Description

    The core of the Stellate Edge Cache configuration. Read more about this in the Cache Rules documentation.

  • Name
    keyFields
    Type
    Description

    A list of all types and their respective key fields. Types will only show up in that list if their key fields have been modified from the default id or key.

  • Name
    scopes
    Type
    Description

    A key-value map of custom cache scopes to scope cached data per user. See the documentation on Scopes for more information on setting up scopes.

  • Name
    retries
    Type
    Description

    Defining when Stellate should automatically retry requests to your origin server. See the Retries documentation for more information on configuring retries.

  • Name
    environments
    Type
    Description

    A key-value map of environments to push to, e.g. "staging". See the Environments documentation for more information.

  • Name
    ignoreOriginCacheControl
    Type
    Description

    Whether to ignore the origin Cache-Control response header or not. (default: true) If this is set to false, Stellate's GraphQL Edge Cache will cache query results based on the response Cache-Control header.

  • Name
    schemaView  ( beta)
    Type
    Description

    Following commands will apply the schemaView configuration:

    The schemaView property is used to configure a subset of a GraphQL schema that should be exposed to clients. The property accepts an object with two properties: include and exclude.

    The include property accepts an array of strings that specifies the GraphQL types that should be included in the subset. If left empty, then all types will be included by default.

    The exclude property is also array of strings that specifies the GraphQL types that should be excluded from the subset. If exclude is left empty, no types will be excluded from the schema.

    For more information see subset in the CLI documentation.

Example Stellate Configuration

  import { Config } from 'stellate'

  const config: Config = {
    config: {
      name: 'my-app',
      schema: 'https://end.point',
      originUrl: 'https://end.point',
      passThroughOnly: false,
      queryDepthLimit: 0,
      injectHeaders: false,
      mutationPolicy: 'Entity',
      enablePlayground: false,
      headers: {
        'x-gcdn-password': 'my-password',
      },
      bypassCacheHeaders: [{ name: 'x-preview-token' }],
      scopes: {
        AUTHENTICATED: 'header:authorization|cookie:session',
      },
      rules: [
        {
          description: 'cache all queries',
          maxage: 900,
          swr: 900,
          scope: 'authenticated',
          types: ['query'],
        },
      ],
      keyfields: {
        types: {
          ['<type>']: ['id', '<field>'],
        },
      },
      retries: {
        networkerrors: {
          isenabled: true,
          whengraphqlresponse: false,
        },
        servererrors: {
          isenabled: false,
        },
      },
      environments: {
        staging: {
          name: 'my-app-staging',
          schema: 'https://staging.end.point',
          originurl: 'https://staging.end.point',
        },
      },
      ignoreOriginCacheControl: true,
    },
    schemaView: {
      include: [],
      exclude: ['private'],
    },
  }
  export default config