JavaScript API

Sveltia CMS provides a flexible, client-side JavaScript/TypeScript API that allows developers to customize and extend its functionality. This document provides an overview of the main API components and how to use them.

Accessing the CMS Object

The main entry point for the Sveltia CMS JavaScript API is the global CMS object. This object exposes various methods for initializing the CMS, registering custom components, and interacting with the CMS programmatically.

There are two primary ways to access the CMS object: via a CDN build or by installing the NPM package.

Using the CDN

CMS is exposed as a global variable when using the UNPKG CDN build. You can access it directly in your scripts:

<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
<script>
  CMS.init({ config });
  CMS.registerPreviewStyle(filePath);
  CMS.registerEditorComponent(definition);
</script>

Alternatively, you can use the ES module version, which can be imported using the mjs file extension. This script is the same as the NPM package version:

<script type="module">
  import CMS from 'https://unpkg.com/@sveltia/cms/dist/sveltia-cms.mjs';

  CMS.init({ config });
  CMS.registerPreviewStyle(filePath);
  CMS.registerEditorComponent(definition);
</script>

Using the NPM Package

Install the @sveltia/cms package via your preferred package manager:

npm

npm install @sveltia/cms

yarn

yarn add @sveltia/cms

pnpm

pnpm add @sveltia/cms

bun

bun add @sveltia/cms

Then, import the CMS object in your script to access the initialization and other API methods:

import CMS from '@sveltia/cms';

CMS.init({ config });
CMS.registerPreviewStyle(filePath);
CMS.registerEditorComponent(definition);

or import only the methods you need:

import { init } from '@sveltia/cms';

init({ config });

TypeScript types are included in the package, so if you edit your project with a TypeScript-aware editor like VS Code, you should get type checking and autocompletion without any additional setup.

Available Methods

Currently, the following methods are available on the CMS object:

• Manual Initialization: init
• Custom Preview Styles: registerPreviewStyle
• Custom Preview Templates: registerPreviewTemplate
• Custom Editor Components: registerEditorComponent
• Custom Field Types: registerFieldType (alias: registerWidget)
• Custom File Formats: registerCustomFormat
• Event Hooks: registerEventListener

Breaking changes from Netlify/Decap CMS

The methods other than those listed above are not supported in Sveltia CMS. This includes:

• registerLocale: Sveltia CMS automatically detects and uses the browser’s language settings for localization. No manual registration of locales is necessary.
• registerRemarkPlugin: Sveltia CMS uses the Lexical framework for Markdown processing instead of Remark. Therefore, Remark plugins are not compatible.
• All other undocumented methods, including custom backends and custom media storage providers. We may support these features in the future, but our implementation would likely be incompatible with Netlify/Decap CMS.