Vendure Settings Store - Scoped Configuration Data Storage

Vendure Settings Store - Scoped Configuration Data Storage | Vendure Docs

import { VendureConfig, SettingsStoreScopes } from '@vendure/core';export const config: VendureConfig = {  // ... other config  settingsStoreFields: {    dashboard: [        {          name: 'theme',          scope: SettingsStoreScopes.user,        },        {          name: 'companyName',          scope: SettingsStoreScopes.global,        }      ]    }  };

Option	Type	Description
`name`	`string`	The field name (combined with namespace to create full key)
`scope`	`SettingsStoreScopeFunction`	How the field should be scoped (see scoping section)
`readonly`	`boolean`	If true, field cannot be modified via GraphQL API
`requiresPermission`	`Permission \| Permission[] \| { read: Permission, write: Permission }`	Permissions required to access this field
`validate`	`function`	Custom validation function for field values

import { SettingsStoreScopes } from '@vendure/core';// Global - single value for entire systemSettingsStoreScopes.global;// User-specific - separate values per userSettingsStoreScopes.user;// Channel-specific - separate values per channelSettingsStoreScopes.channel;// User and channel specific - separate values per user per channelSettingsStoreScopes.userAndChannel;

import { VendureConfig, SettingsStoreScopeFunction } from '@vendure/core';const customScope: SettingsStoreScopeFunction = ({ key, value, ctx }) => {    // Custom scoping logic    const env = process.env.NODE_ENV === 'production' ? 'prod' : 'dev';    return `env:${env}`;};export const config: VendureConfig = {    settingsStoreFields: {        myNamespace: [            {                name: 'customField',                // The value will be saved with the scope                // "env:prod" or "env:dev"                scope: customScope,            },        ],    },};

import { Permission, VendureConfig, RwPermissionDefinition } from '@vendure/core';export const dashboardSavedViews = new RwPermissionDefinition('DashboardSavedViews');export const config: VendureConfig = {    settingsStoreFields: {        myNamespace: [            {                name: 'myField1',                // Single permission for both read and write                requiresPermission: Permission.UpdateSettings,            },            {                name: 'myField2',                // Separate read and write permissions                requiresPermission: {                  read: Permission.ReadSettings,                  write: Permission.UpdateSettings,                },            },            {                name: 'myField3',                // Using custom RwPermissionDefinition                requiresPermission: {                  read: dashboardSavedViews.Read,                  write: dashboardSavedViews.Write,                },            },        ],    },};

Graphql

# Get a single valuequery GetSettingsStoreValue($key: String!) {    getSettingsStoreValue(key: $key)}# Get multiple valuesquery GetSettingsStoreValues($keys: [String!]!) {    getSettingsStoreValues(keys: $keys)}

Graphql

# Set a single valuemutation SetSettingsStoreValue($input: SettingsStoreInput!) {    setSettingsStoreValue(input: $input) {        key        result        error    }}# Set multiple valuesmutation SetSettingsStoreValues($inputs: [SettingsStoreInput!]!) {    setSettingsStoreValues(inputs: $inputs) {        key        result        error    }}

// Setting a valueconst result = await adminClient.query(gql`    mutation SetSettingsStoreValue($input: SettingsStoreInput!) {        setSettingsStoreValue(input: $input) {            key            result            error        }    }`, {    input: {        key: 'dashboard.theme',        value: 'dark'    }});// Getting a valueconst theme = await adminClient.query(gql`    query GetSettingsStoreValue($key: String!) {        getSettingsStoreValue(key: $key)    }`, {    key: 'dashboard.theme'});

import { Injectable } from '@nestjs/common';import { SettingsStoreService, RequestContext } from '@vendure/core';@Injectable()export class MyService {    constructor(private settingsStoreService: SettingsStoreService) {}    async getUserTheme(ctx: RequestContext): Promise<string> {        const theme = await this.settingsStoreService.get<string>(ctx, 'dashboard.theme');        return theme || 'light'; // Default fallback    }    async setUserTheme(ctx: RequestContext, theme: string): Promise<boolean> {        const result = await this.settingsStoreService.set(ctx, 'dashboard.theme', theme);        return result.result;    }}

Method	Description
`get<T>(ctx, key)`	Get a single value with optional type parameter
`getMany(ctx, keys)`	Get multiple values efficiently in a single query
`set<T>(ctx, key, value)`	Set a value with structured result feedback
`setMany(ctx, values)`	Set multiple values with individual result feedback
`getFieldDefinition(key)`	Get the field configuration for a key

// Find orphaned entriesconst orphanedEntries = await settingsStoreService.findOrphanedEntries({    olderThan: '7d',    maxDeleteCount: 1000,});// Clean them upconst cleanupResult = await settingsStoreService.cleanupOrphanedEntries({    olderThan: '7d',    dryRun: false,    batchSize: 100,});

import { VendurePlugin, SettingsStoreScopes } from '@vendure/core';@VendurePlugin({    configuration: config => {        config.settingsStoreFields = {            ...config.settingsStoreFields,            myPlugin: [                {                    name: 'apiEndpoint',                    scope: SettingsStoreScopes.global,                    requiresPermission: Permission.UpdateSettings,                    validate: value => {                        if (typeof value !== 'string' || !value.startsWith('https://')) {                            return 'API endpoint must be a valid HTTPS URL';                        }                    },                },                {                    name: 'userPreferences',                    scope: SettingsStoreScopes.userAndChannel,                },            ],        };        return config;    },})export class MyPlugin {}

Tsx

import React from 'react';import { useQuery, useMutation } from '@apollo/client';import gql from 'graphql-tag';const GET_THEME = gql`    query GetTheme {        getSettingsStoreValue(key: "dashboard.theme")    }`;const SET_THEME = gql`    mutation SetTheme($theme: String!) {        setSettingsStoreValue(input: { key: "dashboard.theme", value: $theme }) {            result            error        }    }`;export function ThemeSelector() {    const { data } = useQuery(GET_THEME);    const [setTheme] = useMutation(SET_THEME, {        refetchQueries: [GET_THEME],    });    const currentTheme = data?.getSettingsStoreValue || 'light';    const handleThemeChange = (theme: string) => {        setTheme({ variables: { theme } });    };    return (        <select value={currentTheme} onChange={e => handleThemeChange(e.target.value)}>            <option value="light">Light</option>            <option value="dark">Dark</option>        </select>    );}

Settings Store

Overview

Settings Store vs Custom Fields

Settings Store

Overview

Settings Store vs Custom Fields

Defining Settings Fields

Field Configuration Options

Scoping

Permissions

GraphQL API

Queries

Mutations

Usage Examples

Using the SettingsStoreService

SettingsStoreService Methods

Orphaned Entries Cleanup

Manual Cleanup

Best Practices

Examples

Plugin Integration

Frontend usage