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), with its options taking precedence over the file’s — except that arrays such as collections are concatenated rather than replaced, so an item can be added but not replaced — or used directly as a complete configuration (if load_config_file is false).

Return Value

The function returns a Promise that resolves once the app has been mounted. The app is mounted on the <div id="nc-root"> element if present, or the <body> element otherwise. If the page is still loading and there is no such element yet, the CMS waits for the page content to be loaded first.

If config is neither an object nor undefined, the Promise is rejected with a TypeError. Calls after the first one are ignored, so the CMS can only be initialized once.

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>

The init function is also exposed as the global initCMS variable, so code written for Netlify/Decap CMS, such as const { CMS, initCMS: init } = window;, works as is.

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.

Registering Customizations

The register* methods, such as registerPreviewTemplate and registerFieldType, can be called before or after init(). Registered items are looked up when they are needed, and the configuration is loaded asynchronously after init() is called, so anything registered in the same script is picked up either way.

However, field type schemas, editor component fields and custom file formats are processed when the configuration or the content is loaded. Register them synchronously rather than in a delayed callback, so they are available by then.

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: '/public/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',
    },
  },
});

Objects are merged recursively, but arrays are appended rather than replaced. For example, if config.yml defines a posts collection and the manual configuration defines a pages collection, the CMS will have both collections, in that order:

CMS.init({
  config: {
    collections: [
      {
        name: 'pages',
        // other options
      },
    ],
  },
});

This means you can’t use a partial configuration to remove, reorder or modify items in an array such as collections. A collection with the same name as one in config.yml is added as a separate item rather than overriding it. If you need full control, set load_config_file to false and provide the complete configuration instead.

Note for Netlify/Decap CMS users

The Netlify/Decap CMS documentation says arrays are replaced during the merge. However, Netlify/Decap CMS actually appends them, just like Sveltia CMS, so your existing configuration will work the same way.

Showcase

Real-world examples of manual initialization can be found in our showcase.