Add a New LocalStorage Setting

Before You Start

This skill needs four pieces of information. If any are missing from the request, ask the user before writing any code:

Only proceed once all four are clear.

Overview

All persistent settings live under the ketcher-opts key in localStorage, managed through a centralized SettingsService in ketcher-core. React components read and write settings via the useSettings hook.

A complete addition touches four locations:

Step 1 — Declare the field in the Settings interface

File: packages/ketcher-core/src/application/settings/types.ts

Add a readonly field at the bottom of the interface, grouped by domain:

// My feature
readonly myNewSetting: string;          // scalar
readonly myNewArraySetting: readonly string[];  // array — always readonly

Rules

• Mark every field readonly (settings objects are frozen by the service).
• Use the narrowest type possible (e.g. 'px' | 'pt' instead of string).
• Arrays must be readonly T[], not T[].

Step 2 — Register the default value and JSON Schema

File: packages/ketcher-core/src/application/settings/schema.ts

2a — Default value in DEFAULT_SETTINGS

Add inside the matching domain comment block (or create a new one):

// My feature
myNewSetting: 'defaultValue',
myNewArraySetting: [],

2b — JSON Schema entry in SCHEMA.properties

Add next to the default value block:

// My feature
myNewSetting: { type: 'string' },
myNewArraySetting: { type: 'array', items: { type: 'string' } },

Common schema patterns:

Step 3 — Read and write in a React component

3a — Import the hook

import { useSettings } from 'src/hooks';

3b — Destructure inside the component

const { settings, updateSettings } = useSettings();

3c — Read the setting

// settings is null until the service initializes — always use optional chaining
const value = settings?.myNewSetting ?? defaultFallback;

// For arrays — spread to get a mutable copy if needed
const items = [...(settings?.myNewArraySetting ?? [])];

3d — Write the setting

updateSettings is async and performs a deep merge — pass only the fields that changed:

// In an event handler or callback
updateSettings({ myNewSetting: newValue });

// For arrays, compute the new array first, then update state and service together
const newItems = computeNewItems(currentItems, input);
setLocalState(newItems);
updateSettings({ myNewArraySetting: newItems });

Important

• Call updateSettings(...) without awaiting unless you need the result.
• Do not read from or write to localStorage directly. Always go through updateSettings / settings.
• settings is null on the first render (async init). Always guard with ?? fallback.
• If you need a local UI state that mirrors the setting, initialize it to [] / null / '' and populate it on first meaningful interaction (e.g., when a picker opens), reading from settings at that point.

Step 4 — Test the component

4a — Mock useSettings at the top of the test file

useSettings is the storage boundary for this component test; see the mocking rule in testing.md.

import { useSettings } from 'src/hooks';
jest.mock('src/hooks', () => ({
  useSettings: jest.fn(),
}));

4b — Set up mock state in beforeEach

let mockSettings;
let mockUpdateSettings;

beforeEach(() => {
  mockSettings = { myNewSetting: 'default', myNewArraySetting: [] };
  mockUpdateSettings = jest.fn().mockResolvedValue({});
  useSettings.mockReturnValue({
    settings: mockSettings,
    updateSettings: mockUpdateSettings,
  });
});

4c — Test initial state (reading from service)

Set the desired value on mockSettings before rendering:

it('should display value from settings', () => {
  mockSettings.myNewSetting = 'custom';
  renderComponent();
  // assert UI reflects 'custom'
});

4d — Test persistence (writing to service)

Assert that updateSettings was called with the expected partial:

it('should persist new value via SettingsService', async () => {
  renderComponent();
  // perform user interaction that changes the setting
  expect(mockUpdateSettings).toHaveBeenCalledWith(
    expect.objectContaining({ myNewSetting: 'expectedValue' }),
  );
});

4e — Test service update between renders

To simulate the service returning different data (e.g., cross-tab sync), update mockSettings and call useSettings.mockReturnValue again before triggering a re-render:

mockSettings.myNewArraySetting = ['newValue'];
useSettings.mockReturnValue({
  settings: mockSettings,
  updateSettings: mockUpdateSettings,
});
// trigger re-render / re-open

Checklist

• Field added to Settings interface (types.ts) as readonly
• Default value added to DEFAULT_SETTINGS (schema.ts)
• JSON Schema entry added to SCHEMA.properties (schema.ts)
• Component reads via settings?.fieldName ?? fallback
• Component writes via updateSettings({ fieldName: newValue })
• No direct localStorage access in the component
• Test mocks useSettings with jest.mock
• Test verifies initial render from mockSettings
• Test asserts mockUpdateSettings call arguments
• TypeScript: no new compile errors in types.ts or schema.ts

Key Files Reference