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
    cacheIntrospection
    Type
    Description

    A boolean allowing you to indicate whether introspection-queries should be cached or not.

  • 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? (Deprecated in favor of the graphiql property)

  • Name
    graphiql
    Type
    Description

    An object containing the enabled and title properties, the title will be used to name your GraphiQL instance.

  • 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
    nonCacheable
    Type
    Description

    A list of type names and field names (in the form of <type-name>.<field-name>) that should never be cached.

  • 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
    removeCookies
    Type
    Description

    A list of cookie names you would like to remove from responses from your GraphQL backend service. You can use * as a wildcard character.

  • 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:

    Note: As this feature is still in beta:

    • Queries will not be validated
    • Schema will only be applied via the CLI commands mentioned above

    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.

    The rules for schema views are inspired by Apollo Contracts and follow the same rule set outlined in their documentation. The rules are based on the Federation v1 standard.

    For more information see subset in the CLI documentation.

  • Name
    customAttributes
    Type
    Description

    A map that defines Custom Attributes which are extracted for each request and made available in our GraphQL Metrics.

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',
      graphiql: { enabled: false },
      headers: {
        'x-gcdn-password': 'my-password',
      },
      bypassCacheHeaders: [{ name: 'x-preview-token' }],
      scopes: {
        AUTHENTICATED: 'header:authorization|cookie:session',
      },
      nonCacheable: ['User'],
      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,
        },
      },
      ignoreOriginCacheControl: true,
      customAttributes: {
        userId: { header: 'x-user-id' },
      },
      removeCookies: [
        '_cfuvid',
        '__cf*'
      ],
      environments: {
        staging: {
          name: 'my-app-staging',
          schema: 'https://staging.end.point',
          originurl: 'https://staging.end.point',
        },
      },
    },
    schemaView: {
      include: [],
      exclude: ['private'],
    },
  }
  export default config