StellatePlugin

StellatePlugin

@vendure/stellate-pluginstellate-plugin.ts

v2.1.5

A plugin to integrate the Stellate 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.

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.

Installation

npm install @vendure/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 PurgeRules which define how the plugin will respond to Vendure events in order to trigger calls to the Stellate Purging API.

Example

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:

Example

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.

Example

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:

Example

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:

Example

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.

Example

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,
           ],
       }),
   ],
};

Signature

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

• Implements: OnApplicationBootstrap

options

property

StellatePluginOptions

init

method

(options: StellatePluginOptions) =>

constructor

method

(options: StellatePluginOptions, eventBus: EventBus, stellateService: StellateService, moduleRef: ModuleRef) => StellatePlugin

onApplicationBootstrap

method

() =>