Scopes

Scopes define the available value contexts for a project. Configure them in defineConfig() alongside keys like title, projectId, basePath, plugins, and schema.

Every project should define a scopes array, and at least one scope should be marked as the default with isDefault: true.

Defining Scopes

import { defineConfig } from '@flexkit/studio';
 
export default defineConfig({
  title: 'My Project',
  projectId: 'myprojectid',
  basePath: '/studio',
  scopes: [
    {
      name: 'default',
      label: 'Default',
      isDefault: true,
    },
    {
      name: 'es',
      label: 'Spain',
    },
    {
      name: 'fr',
      label: 'France',
    },
  ],
  plugins: [
    // ...
  ],
  schema: [
    // ...
  ],
});

Each scope object supports:

name: internal identifier stored in the project configuration.
label: display name shown in the Studio scope selector.
isDefault?: marks the fallback scope used when a local value is missing.
sortOrder?: optional ordering hint for the selector.

How Scopes Work In Studio

The Studio shows a scope selector in the UI.

When you select a scope, fields with scope: 'local' show the value for that scope.
Editing a local field saves the value for the currently selected scope.
Fields with scope: 'global' keep the same value in every scope.
Fields with scope: 'relationship' keep relationship semantics and are not scope-local content fields.

If a local field does not have a value for the selected scope, the value from the default scope is used.

Choosing Field Scopes

Use local for values that change by market, region, storefront, business unit, or language context.

Use global for values that should stay the same everywhere, such as SKUs, IDs, and workflow flags.

Use relationship for links to other entities.

Example: CRM Scopes

export default defineConfig({
  title: 'My Project',
  projectId: 'myprojectid',
  basePath: '/studio',
  scopes: [
    {
      name: 'default',
      label: 'Global',
      isDefault: true,
    },
    {
      name: 'na',
      label: 'North America',
    },
    {
      name: 'emea',
      label: 'Europe, Middle East & Africa',
    },
    {
      name: 'apac',
      label: 'Asia Pacific',
    },
    {
      name: 'latam',
      label: 'Latin America',
    },
    {
      name: 'enterprise',
      label: 'Enterprise Division',
    },
    {
      name: 'smb',
      label: 'SMB Division',
    },
    {
      name: 'government',
      label: 'Government',
    },
  ],
  schema: [
    // ...
  ],
});

This kind of setup works well when local fields vary by region or by internal business unit.

Example: E-commerce Scopes

export default defineConfig({
  title: 'My Project',
  projectId: 'myprojectid',
  basePath: '/studio',
  scopes: [
    {
      name: 'default',
      label: 'Default',
      isDefault: true,
    },
    {
      name: 'es',
      label: 'Spain Store',
    },
    {
      name: 'pt',
      label: 'Portugal Store',
    },
    {
      name: 'fr',
      label: 'France Store',
    },
    {
      name: 'it',
      label: 'Italy Store',
    },
    {
      name: 'uk',
      label: 'United Kingdom Store',
    },
    {
      name: 'en',
      label: 'United States Store',
    },
    {
      name: 'de',
      label: 'Germany Store',
    },
    {
      name: 'amazon',
      label: 'Partner Marketplace',
    },
  ],
  schema: [
    // ...
  ],
});

This setup is useful when product content changes by storefront or external sales channel.