StellatePlugin
StellatePlugin
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,
],
}),
],
};
class StellatePlugin implements OnApplicationBootstrap {
static options: StellatePluginOptions;
init(options: StellatePluginOptions) => ;
constructor(options: StellatePluginOptions, eventBus: EventBus, stellateService: StellateService, moduleRef: ModuleRef)
onApplicationBootstrap() => ;
}
- Implements:
OnApplicationBootstrap
options
init
(options: StellatePluginOptions) => constructor
(options: StellatePluginOptions, eventBus: EventBus, stellateService: StellateService, moduleRef: ModuleRef) => StellatePluginonApplicationBootstrap
() =>