Manual Initialization

By default, Sveltia CMS automatically initializes itself when the script is loaded. However, in some cases, you may want to have more control over when and how the CMS is initialized. This is where the init function comes into play.

Overview

To manually initialize the CMS, call the init function on the CMS object:

CMS.init({ config });

Parameters

• config (optional): An object that can contain any of the configuration options available in the config.yml file. If provided, this configuration will be merged with the one loaded from config.yml (if the load_config_file option is true or omitted) or used directly (if load_config_file is false).

Config File Loading Behavior

Unless you set the load_config_file option to false, the CMS will always attempt to load the config.yml file, even when you provide a configuration object, and raise an error if the file is not found or cannot be loaded. If you want to completely bypass loading the configuration file, make sure to set this option accordingly.

Usage Notes

Preventing Automatic Initialization

If you use the UNPKG CDN, you have to set a global variable CMS_MANUAL_INIT to true before loading the script to prevent automatic initialization.

<script>
  // Set this before loading the CMS script
  window.CMS_MANUAL_INIT = true;
</script>
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
<script>
  // Now you can call init() manually
  CMS.init();
</script>

For NPM installations, you don’t need this step; manual initialization is the default behavior. In other words, you always have to call init() yourself.

Typing the Configuration Object

The CMS object is typed, so if you are using TypeScript, you will get type checking and autocompletion when providing the configuration object to the init function.

You can also import the CmsConfig type from the @sveltia/cms package to type the configuration object if you construct it outside of the init call. Here’s an example:

import { init, type CmsConfig } from '@sveltia/cms';

const config: CmsConfig = {
  // your config here
};

init({ config });

Experimental Types

Types other than CmsConfig can also be imported for more specific parts of the configuration, such as GitHubBackend, EntryCollection, DateTimeField, etc. However, this is experimental and subject to change, so it’s recommended to use CmsConfig for now.

Examples

Initializing the CMS Normally

This will load the configuration from config.yml and initialize the CMS as usual, just like the automatic initialization.

CMS.init();

Providing a Full Configuration

When the load_config_file option is set to false, the configuration provided here will be used directly, and the config.yml file will not be loaded. Make sure to include all required options: backend, media_folder and collections.

CMS.init({
  config: {
    load_config_file: false,
    backend: {
      name: 'github',
      repo: 'user/repo',
    },
    media_folder: '/static/media',
    public_folder: '/media',
    collections: [
      // your collections here
    ],
  },
});

Providing a Partial Configuration

If the load_config_file option is set to true or omitted, the configuration provided here will be merged with the one loaded from config.yml using the deepmerge library, so you can override or add specific settings. Use cases for this are more limited, but it can be useful in some scenarios.

For example, you could override the backend branch like this:

CMS.init({
  config: {
    backend: {
      branch: 'development',
    },
  },
});