Introducing the Settings Store

Settings Store: a dedicated key-value system for persisting arbitrary, schema-less JSON configuration data.

It provides a flexible API with support for data scoping (global, user, channel), permission control, validation, and access via both GraphQL and a dedicated service.

Key Features of the Settings Store

The Settings Store provides a dedicated system for managing configuration with fine-grained control:

Scoped Storage: Store configuration globally (e.g., a third-party API key), per-channel (e.g., channel-specific settings), or per-user (e.g., Admin UI preferences).
Permission Control: Secure fields by requiring specific permissions, allowing you to control which administrators can view or modify sensitive data.
Dual API Access: Programmatic access through the SettingsStoreService and Admin API through GraphQL.
JSON Support with Validation: Store any JSON-serializable data, and ensure data integrity with custom validation functions.

Practical Example: Lightweight Content Management

The Settings Store is a versatile tool for configuring any type of system.

As an example, we can implement a lightweight content management system.

In this guide, we will build and manage a promotional banner and a promotional footer link.

This approach allows you to empower non-technical team members to update site content directly, without requiring a code deployment.

1. Defining Your Content Fields

First, define your content fields in vendure-config.ts. We'll use a promotions namespace to group our fields. Instead of a single field for footer links, we'll define separate fields for the link's text and its URL.

2. Managing Content via the GraphQL API

With simpler fields, the GraphQL mutations become much more straightforward. You can update multiple values at once using the setSettingsStoreValues mutation.

Remember that the value argument must still be a JSON-stringified string.

3. Displaying Content on the Storefront

Your storefront application can then fetch these individual fields. The API will automatically parse the JSON string, returning the original string values.

Here is a practical example of a React component that queries and displays the promotional content:

Other Use-Cases for the Settings Store

The content management example is just one application of the Settings Store. The system is designed for a variety of configuration needs, such as:

Plugin Configuration: Storing API keys, credentials, and settings for third-party integrations like payment or tax providers.
User Preferences: Allowing Admin Dashboard users to save their own preferences, such as a preferred theme or default table settings.
Feature Flags: Implementing a simple system to toggle new features on or off in your storefront without a full deployment.
A/B Testing: Managing parameters for A/B tests, such as which variant to display and defining traffic allocation between variants.