Stellate Configuration File

When you use the Stellate CLI, you'll work with one configuration file, which is called stellate.<ts|js|mjs|yml>.

📘

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

An example config in the TypeScript and YAML formats

📘

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.

import { Config } from 'stellate';

const config: Config = {
  "config": {
    "name": "my-app",
    "schema": "https://end.point",
    "originUrl": "https://end.point",
    "passThroughOnly": false,
    "injectHeaders": false,
    "mutationPolicy": "Entity",
    "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"
      }
    }
  },
}

export default config;
name: my-app
schema: https://end.point
originUrl: https://end.point
passThroughOnly: false
injectHeaders: false
mutationPolicy: Entity
headers:
  x-gcdn-password: my-password
bypassCacheHeaders:
    - name: x-preview-token
    - name: some-other-token
scopes:
  AUTHENTICATED: header:Authorization|cookie:session

rules:
  - description: Cache all queries
    maxAge: 900
    swr: 900
    scope: AUTHENTICATED
    types:
      Query: true

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

Reference

name

The name of your service

schema

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

originUrl

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

passThroughOnly

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

injectHeaders

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.

mutationPolicy

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

headers

A key-value map of headers and their values.

bypassCacheHeaders

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.

rules

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

keyFields

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.

scopes

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.

retries

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

environments

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


Did this page help you?