---
title: 'Scopes'
description: 'Reference and usage guidance for Scopes.'
---

# Scopes

Scopes are the contexts where the same attribute can hold a different value. You can usually think of them as markets, websites, or sales channels.

They are especially useful in e-commerce. A product is often one record, but many of its attributes change by where it is sold: the name may differ by market, the price may use another currency, and the description may be localized. Scopes store those variants without duplicating the product.

Configure scopes in `defineConfig()` alongside keys like `title`, `projectId`, `basePath`, `extensions`, 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

```tsx
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',
    },
  ],
  extensions: [
    // ...
  ],
  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, website, or channel — for example a product name, a localized description, or a price in a different currency.

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

```tsx
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

```tsx
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.


---

[View full sitemap](/docs/sitemap.md)