***

title: "StellatePlugin"
generated: true
---------------

<GenerationInfo sourceFile="packages/stellate-plugin/src/stellate-plugin.ts" sourceLine="27" packageName="@vendure-community/stellate-plugin" since="2.1.5" />

A plugin to integrate the [Stellate](https://stellate.co/) GraphQL caching service with your Vendure server.
The main purpose of this plugin is to ensure that cached data gets correctly purged in
response to events inside Vendure. For example, changes to a Product's description should
purge any associated record for that Product in Stellate's cache.

## Pre-requisites

You will first need to [set up a free Stellate account](https://stellate.co/signup).

You will also need to generate an **API token** for the Stellate Purging API. For instructions on how to generate the token,
see the [Stellate Purging API docs](https://docs.stellate.co/docs/purging-api#authentication).

## Installation

```shell
npm install @vendure-community/stellate-plugin
```

## Configuration

The plugin is configured via the `StellatePlugin.init()` method. This method accepts an options object
which defines the Stellate service name and API token, as well as an array of `PurgeRule`s which
define how the plugin will respond to Vendure events in order to trigger calls to the
Stellate [Purging API](https://stellate.co/docs/graphql-edge-cache/purging-api).

```ts
import { StellatePlugin, defaultPurgeRules } from '@vendure/stellate-plugin';
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
   // ...
   plugins: [
       StellatePlugin.init({
           // The Stellate service name, i.e. `<serviceName>.stellate.sh`
           serviceName: 'my-service',
           // The API token for the Stellate Purging API. See the "pre-requisites" section above.
           apiToken: process.env.STELLATE_PURGE_API_TOKEN,
           devMode: !isProd || process.env.STELLATE_DEBUG_MODE ? true : false,
           debugLogging: process.env.STELLATE_DEBUG_MODE ? true : false,
           purgeRules: [
               ...defaultPurgeRules,
               // custom purge rules can be added here
           ],
       }),
   ],
};
```

In your Stellate dashboard, you can use the following configuration example as a sensible default for a
Vendure application:

```ts
import { Config } from "stellate";

const config: Config = {
  config: {
    name: "my-vendure-server",
    originUrl: "https://my-vendure-server.com/shop-api",
    ignoreOriginCacheControl: true,
    passThroughOnly: false,
    scopes: {
      SESSION_BOUND: "header:authorization|cookie:session",
    },
    headers: {
      "access-control-expose-headers": "vendure-auth-token",
    },
    rootTypeNames: {
      query: "Query",
      mutation: "Mutation",
    },
    keyFields: {
      types: {
        SearchResult: ["productId"],
        SearchResponseCacheIdentifier: ["collectionSlug"],
      },
    },
    rules: [
      {
        types: [
          "Product",
          "Collection",
          "ProductVariant",
          "SearchResponse",
        ],
        maxAge: 900,
        swr: 900,
        description: "Cache Products & Collections",
      },
      {
        types: ["Channel"],
        maxAge: 9000,
        swr: 9000,
        description: "Cache active channel",
      },
      {
        types: ["Order", "Customer", "User"],
        maxAge: 0,
        swr: 0,
        description: "Do not cache user data",
      },
    ],
  },
};
export default config;
```

## Storefront Setup

In your storefront, you should point your GraphQL client to the Stellate GraphQL API endpoint, which is
`https://<service-name>.stellate.sh`.

Wherever you are using the `search` query (typically in product listing & search pages), you should also add the
`cacheIdentifier` field to the query. This will ensure that the Stellate cache is correctly purged when
a Product or Collection is updated.

```ts
import { graphql } from '../generated/gql';

export const searchProductsDocument = graphql(`
    query SearchProducts($input: SearchInput!) {
        search(input: $input) {
            cacheIdentifier {
                collectionSlug
            }
            items {
               # ...
            }
        }
    }
`);
```

## Custom PurgeRules

The configuration above only accounts for caching of some of the built-in Vendure entity types. If you have
custom entity types, you may well want to add them to the Stellate cache. In this case, you'll also need a way to
purge those entities from the cache when they are updated. This is where the `PurgeRule` comes in.

Let's imagine that you have built a simple CMS plugin for Vendure which exposes an `Article` entity in your Shop API, and
you have added this to your Stellate configuration:

```ts
import { Config } from "stellate";

const config: Config = {
    config: {
        // ...
        rules: [
            // ...
            {
                types: ["Article"],
                maxAge: 900,
                swr: 900,
                description: "Cache Articles",
            },
        ],
    },
    // ...
};
export default config;
```

You can then add a custom `PurgeRule` to the StellatePlugin configuration:

```ts
import { StellatePlugin, defaultPurgeRules } from "@vendure/stellate-plugin";
import { VendureConfig } from "@vendure/core";
import { ArticleEvent } from "./plugins/cms/events/article-event";

export const config: VendureConfig = {
    // ...
    plugins: [
        StellatePlugin.init({
            // ...
            purgeRules: [
                ...defaultPurgeRules,
                new PurgeRule({
                    eventType: ArticleEvent,
                    handler: async ({ events, stellateService }) => {
                        const articleIds = events.map((e) => e.article.id);
                        stellateService.purge("Article", articleIds);
                    },
                }),
            ],
        }),
    ],
};
```

## DevMode & Debug Logging

In development, you can set `devMode: true`, which will prevent any calls being made to the Stellate Purging API.

If you want to log the calls that *would* be made to the Stellate Purge API when in devMode, you can set `debugLogging: true`.
Note that debugLogging generates a lot of debug-level logging, so it is recommended to only enable this when needed.

```ts
import { StellatePlugin, defaultPurgeRules } from '@vendure/stellate-plugin';
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
   // ...
   plugins: [
       StellatePlugin.init({
           // ...
           devMode: !process.env.PRODUCTION,
           debugLogging: process.env.STELLATE_DEBUG_MODE ? true : false,
           purgeRules: [
               ...defaultPurgeRules,
           ],
       }),
   ],
};
```

```ts title="Signature"
class StellatePlugin implements OnApplicationBootstrap {
    static options: StellatePluginOptions;
    init(options: StellatePluginOptions) => ;
    constructor(options: StellatePluginOptions, eventBus: EventBus, stellateService: StellateService, moduleRef: ModuleRef)
    onApplicationBootstrap() => ;
}
```

* Implements: OnApplicationBootstrap

<div className="members-wrapper">

### options

\<MemberInfo kind="property" type={`<a href='/current/community-plugins/reference/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>`}   />

### init

\<MemberInfo kind="method" type={`(options: <a href='/current/community-plugins/reference/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>) => `}   />

### constructor

\<MemberInfo kind="method" type={`(options: <a href='/current/community-plugins/reference/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>, eventBus: EventBus, stellateService: <a href='/current/community-plugins/reference/stellate-plugin/stellate-service#stellateservice'>StellateService</a>, moduleRef: ModuleRef) => StellatePlugin`}   />

### onApplicationBootstrap

\<MemberInfo kind="method" type={`() => `}   />

</div>