---
url: /en/docs/api/initialization.md
description: >-
  Manually initialize Sveltia CMS with the init function for greater control
  over CMS startup.
---

# 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](/en/docs/api#accessing-the-cms-object):

```js
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">`](/en/docs/customization#custom-mount-element) 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.

::: tip 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.

```html
<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](/en/docs/api/field-types#field-schema), [editor component](/en/docs/api/editor-components) fields and [custom file formats](/en/docs/api/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:

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

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

init({ config });
```

::: info 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.

```js
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`.

```js {3}
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`](https://www.npmjs.com/package/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](/en/docs/backends#branch-selection) like this:

```js
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:

```js
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.

::: tip 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](/en/showcase?feature=initialization).