core/config

@use "@vrembem/core/config";

Basic usage

The purpose of core/config is to provide an API for managing library-wide configuration options. Configuration options are stored in a private map of key/value pairs.

There are two primary methods to configure options in the config module. The first is to import the module API directly and the second is using the Sass @use ... with clause.

Using config module

To use the configuration module directly, import the core/config module. Once imported you can use the API to set and get values in the configuration map.

// 1. Import the module
@use "@vrembem/core/config";

// 2. Set a configuration value
@include config.set("prefix-tokens", "sn");

// 3. Get a configuration value
@debug config.get("prefix-tokens"); // => "sn"

Changes to the global config should be done in a file that is loaded before other Vrembem or custom components that use them. This ensures components use the correct configuration values when their modules are loaded.

// 1. Make all your custom configurations
@use "./config";

// 2. Import components or other custom modules
@use "@vrembem/content";
@use "@vrembem/modal";
// ...

// 3. Output CSS variables
@use "@vrembem/core/tokens";

Using with clause

To set configuration options via the Sass @use ... with clause, define and set options in a $config options map. Options set in the $config map are stored in the config module and backfilled with the modules defaults.

@use "@vrembem/core" with (
  $config: (
    "prefix-blocks": "vb"
  )
);
@use "@vrembem/content" with (
  $config: (
    "content-output": false
  )
);

@debug core.config-get("prefix-blocks"); // => "vb"
@debug core.config-get("content-output"); // => false

Changes to the global config should be done before loading other Vrembem or custom components. This ensures components use the correct configuration values when their modules are loaded.

Reference

This reference details the available configuration API, their arguments, and usage examples so you can customize and control global configurations across Vrembem and custom modules.

get

Function to returns the value of an option in the configuration map.

Arguments

Example

@debug config.get("theme-default");
// Debug: light

@debug config.get("prefix-tokens");
// Debug: vb

set

Set an option in the configuration map by providing a key and value to store, or pass a map to store multiple key/value pairs.

Arguments

Example

// Set a single option
@include config.set("theme-default", "dark");

// Set multiple options using a map
@include config.set((
  "prefix-tokens": "custom",
  "theme-default": "light"
));

merge

Merges a map value of the configuration object with a provided map value.

Arguments

merge-with-default

Merges a configuration map to the config module based on the values in a default map. The provided configuration map must match the signature of the default map. This mixin is used to allow setting values in the config module using the Sass with clause.

Arguments

Example

We define an empty $config map with the !default flag and a $default map containing the configurations we want to expose and their default values.

@use "@vrembem/core/config";

$config: () !default;
$default: (
  "config-1": true,
  "config-2": "asdf",
);

@include config.merge-with-default($config, $default);

When we use this module, we can define the configuration using the Sass with clause:

@use "example" with (
  $config: (
    "config-1": false
  )
);

// More imports here...

We can also set our configuration values before the module is loaded and include our config at the top of our manifest file:

// Import the config module
@use "@vrembem/core/config";

// These values will be used once the module is loaded
@include config.set((
  "config-1": false,
  "config-2": "fdsa"
));

@use "config";
@use "example";

// More imports here...

remove

Remove an option from the configuration map.

Arguments

Example

// Remove the theme default option
@include config.remove("theme-default");

watch

Set a watcher to a specific property of the configuration object.

Arguments

unwatch

Remove a watcher to a specific property of the configuration object.

Arguments

log

Log to console the entire or a specific value in the configuration map.

Arguments

Example

@include config.log();
// Debug: 
// Config options map: (
//   "prefix-blocks": ,
//   "prefix-elements": __,
//   "prefix-modifiers": _,
//   "prefix-modifier-values": _,
//   ...
// )