Lime Web Components API Documentation - v7.10.0
    Preparing search index...

    Interface ConfigRepository

    Repository for storing and retrieving application-wide configuration data.

    ConfigRepository provides persistent key-value storage for configuration that applies to all users across the application. Typical use cases include:

    • View configurations (card layouts, table columns, form structures)
    • Plugin-specific configuration settings

    Each plugin or package typically manages its own configuration namespace, storing settings that define how components should be rendered or behave for all users.

    Important: This repository is NOT for user preferences. User-specific settings should use UserPreferencesRepository instead.

    Configuration data is:

    • Stored persistently in the database
    • Shared across all users and sessions
    • Read-only for non-admin users (set method requires admin privileges)

    The repository extends StateRepository, providing reactive state management with automatic UI updates when configuration changes.

    The repository also holds describers for parts of the configuration. A describer is registered at runtime and is not stored in the database. Subscriptions cover only the configuration data, not the describers.

    Access the repository through the platform service:

    const repo = this.platform.get(PlatformServiceName.ConfigRepository);

    import { PlatformServiceName } from '@limetech/lime-web-components';

    interface CompanyViewConfig {
        card: {
            fields: string[];
        };
    }

    const configs = platform.get(PlatformServiceName.ConfigRepository);

    // A key holds nothing until an admin saves a config for it, so ask `has` before
    // reading
    const cardFields = configs.has('webclient_view.company')
        ? configs.get<CompanyViewConfig>('webclient_view.company').card.fields
        : [];

    import { PlatformServiceName } from '@limetech/lime-web-components';

    interface MyPluginConfig {
        enabled: boolean;
        apiEndpoint: string;
    }

    const defaultConfig: MyPluginConfig = {
        enabled: false,
        apiEndpoint: 'https://api.example.com',
    };

    function getPluginConfig(): MyPluginConfig {
        const configs = platform.get(PlatformServiceName.ConfigRepository);

        if (!configs.has('my_plugin_config')) {
            return defaultConfig;
        }

        // An admin may have saved only some of the keys, so merge over the defaults
        const saved = configs.get<Partial<MyPluginConfig>>('my_plugin_config');

        return { ...defaultConfig, ...saved };
    }

    const isEnabled = getPluginConfig().enabled;

    StateRepository for subscription patterns

    interface ConfigRepository {
        get<T = any>(key: string): T;
        getDescriber?(name: string): ConfigDescriber | undefined;
        has(key: string): boolean;
        registerDescriber?<T>(name: string, describer: ConfigDescriber<T>): void;
        set<T = any>(key: string, data: T, version?: number): Promise<void>;
        subscribe(
            callback: (...args: unknown[]) => void,
            options?: StateOptions,
        ): () => void;
    }

    Hierarchy (View Summary)

    Index

    Methods

    get getDescriber? has registerDescriber? set subscribe

    Methods

    • Get configuration data for a key.

      Retrieves the configuration value stored under the specified key. Returns the stored data, or undefined if the key doesn't exist.

      Use the type parameter <T> to specify the expected type of the configuration data for type safety. The repository does not validate types at runtime.

      Type Parameters

      • T = any

      Parameters

      • key: string

        Name of the configuration key to retrieve

      Returns T

      The stored configuration data, or undefined if not found

      May throw if the stored data cannot be deserialized

      import { PlatformServiceName } from '@limetech/lime-web-components';

      interface CompanyCardConfig {
          card: {
              fields: string[];
          };
      }

      const configs = platform.get(PlatformServiceName.ConfigRepository);

      // The type parameter says what the config looks like, it does not promise the
      // key exists, so guard the value before using it
      const cardConfig = configs.get<CompanyCardConfig>(
          'webclient_view.company'
      )?.card;

    • Check if a configuration key exists.

      Returns true if configuration data has been stored under the specified key, false otherwise. Use this to check for the existence of optional configuration before attempting to retrieve it.

      Parameters

      • key: string

        Name of the configuration key to check

      Returns boolean

      true if the configuration exists, false otherwise

      import { PlatformServiceName } from '@limetech/lime-web-components';

      const configs = platform.get(PlatformServiceName.ConfigRepository);

      // Render the built-in columns when no admin has configured any
      const hasCustomColumns = configs.has('person_table_columns');
    • Beta

      Register a describer for one kind of config part.

      The name must contain a ., for example my-addon.account, so that describers from different add-ons do not collide. Registering a describer with a name that is already taken replaces the earlier describer.

      The platform registers the describeConfig of a web component, a command or a rule primitive under its tag or id. Such a describer takes the whole part, not only its config. A web component describer takes a ComponentDescriptor, a command describer takes a CommandConfig, and a rule primitive describer takes a RuleRef.

      Type Parameters

      • T

      Parameters

      • name: string

        The name of the describer.

      • describer: ConfigDescriber<T>

        The function that describes the part.

      Returns void

      If the name has no ..

      import {
          ConfigDescription,
          PlatformServiceName,
      } from '@limetech/lime-web-components';

      interface Account {
          name: string;
          email: string;
          role: string;
      }

      const translator = platform.get(PlatformServiceName.Translate);

      function describeAccount(account: Account): ConfigDescription {
          return {
              title: account.name,
              icon: 'user',
              facts: [
                  {
                      label: translator.get('my-addon.account.email'),
                      text: account.email,
                  },
                  {
                      label: translator.get('my-addon.account.role'),
                      text: account.role,
                  },
              ],
          };
      }

      const configs = platform.get(PlatformServiceName.ConfigRepository);

      configs.registerDescriber?.('my-addon.account', describeAccount);

      ConfigRepository.getDescriber to get a describer

    • Save configuration data under a key.

      Important: This method requires admin privileges. The backend endpoint is protected and will reject requests from non-admin users.

      Stores the provided data persistently under the specified key. If the key already exists, its value is overwritten. The data is serialized and saved to the database, making it available to all users across the application.

      After saving, the repository state is updated, triggering any subscriptions. The data can be any serializable JavaScript value (objects, arrays, primitives).

      Type Parameters

      • T = any

      Parameters

      • key: string

        Name of the configuration key to set

      • data: T

        Configuration data to store (must be serializable)

      • Optionalversion: number

        The version of the plugin config the data was read at, which the backend migrates it from. Defaults to the version of the data the repository holds under the key.

      Returns Promise<void>

      Promise that resolves when the data is saved

      Error if save fails, data cannot be serialized, or user lacks admin privileges

      import { PlatformServiceName } from '@limetech/lime-web-components';

      interface PluginConfiguration {
          enabled: boolean;
          apiEndpoint: string;
          settings: {
              timeout: number;
              retries: number;
          };
      }

      const pluginConfig: PluginConfiguration = {
          enabled: true,
          apiEndpoint: 'https://api.example.com',
          settings: {
              timeout: 5000,
              retries: 3,
          },
      };

      const configs = platform.get(PlatformServiceName.ConfigRepository);

      // The backend endpoint rejects this call for anyone who is not an admin
      await configs.set('my_plugin_config', pluginConfig);

    • Subscribe to state changes with optional transformation and filtering.

      The subscription will immediately invoke the callback with the current state (if any), then continue to call it whenever the state changes. The map and filter options allow you to transform and selectively receive updates.

      Parameters

      • callback: (...args: unknown[]) => void

        Function called with state updates (after map/filter applied)

      • Optionaloptions: StateOptions

        Optional transformations and filters for the subscription

      Returns () => void

      Unsubscribe function - call this to stop receiving updates

      • Map functions are applied sequentially to transform the state
      • Filter functions must all return true for the callback to be invoked
      • Functions in map/filter arrays are bound to the component instance
      • Always store and call the unsubscribe function when component is destroyed
      import { PlatformServiceName } from '@limetech/lime-web-components';

      const repository = platform.get(PlatformServiceName.Application);
      const logger = platform
          .get(PlatformServiceName.Logger)
          .createLogger('my-component');

      // Basic subscription
      const unsubscribeState = repository.subscribe((state) => {
          logger.debug('State updated', { state });
      });

      // With transformations
      const unsubscribeFullname = repository.subscribe(
          (fullname) => logger.debug('User', { fullname }),
          { map: [(state) => state.currentUser?.fullname] }
      );

    Settings

    Member Visibility

    On This Page

    Methods