Custom File Formats

Sveltia CMS comes with built-in support for common file formats like JSON, YAML, TOML and Markdown. However, you can also register your own custom parsers and formatters to handle different file types or formats.

Overview

To register a custom file format, use the registerCustomFormat method on the CMS object:

CMS.registerCustomFormat(name, extension, { fromFile, toFile });

Parameters

• name (string): A unique name for the custom format. This name will be used to reference the format in collection configurations.
• extension (string): The file extension associated with this format (e.g., json5, yaml, toml).
• fromFile (function): A parser function that takes a string (the content of the file) and returns a JavaScript object.
• toFile (function): A formatter function that takes a JavaScript object and returns a string (the content to be saved to the file).

You can omit either fromFile or toFile if you only need to customize one direction (parsing or formatting). If you omit fromFile, the CMS will use the default parser for the specified file extension. Similarly, if you omit toFile, the CMS will use the default formatter. You must provide at least one of the two functions.

The functions fromFile and toFile can also be asynchronous, allowing you to perform async operations if needed.

Using Custom Formats

Once registered, the custom format can be used in your collection configurations by specifying the format property. For example:

YAML

collections:
  - name: myCollection
    format: json5
    fields:
      - name: item1
        label: Item 1

TOML

[[collections]]
name = "myCollection"
format = "json5"

[[collections.fields]]
name = "item1"
label = "Item 1"

JSON

{
  "collections": [
    {
      "name": "myCollection",
      "format": "json5",
      "fields": [
        {
          "name": "item1",
          "label": "Item 1"
        }
      ]
    }
  ]
}

JavaScript

{
  collections: [
    {
      name: "myCollection",
      format: "json5",
      fields: [
        {
          name: "item1",
          label: "Item 1",
        },
      ],
    },
  ],
}

You don’t need to specify the file extension in the collection configuration; the CMS will automatically use the correct extension based on the registered format.

Examples

Registering JSON5 Format

The following example demonstrates how to register a custom formatter for the JSON5 format using the json5 library:

import JSON5 from 'json5';

CMS.registerCustomFormat('json5', 'json5', {
  fromFile: (text) => JSON5.parse(text),
  toFile: (data) => JSON5.stringify(data, null, 2),
});

Registering YAML Parser with Custom Behavior

You can customize the behavior of the formatter functions. For example, you might want to add a timestamp to the YAML file whenever it is saved:

import YAML from 'js-yaml';

CMS.registerCustomFormat('yaml', 'yaml', {
  fromFile: (text) => YAML.load(text),
  toFile: (data) => YAML.dump({ ...data, last_updated: new Date().toISOString() }),
});

An event hook is a better way to add metadata like timestamps, but this example illustrates how you can customize the formatter functions.

Registering JavaScript Module Format

The following example demonstrates how to register a custom formatter for JavaScript modules that export data using export default syntax and parse it back into a JavaScript object:

CMS.registerCustomFormat('mjs', 'js', {
  fromFile: (text) => JSON.parse(text.replace(/^export default (.+);$/s, '$1')),
  toFile: (data) => `export default ${JSON.stringify(data, null, 2)};`,
});

The file extension is set to js for demonstration purposes. You can use mjs if you prefer.

This example uses a simple regex to extract the JSON object from the export default statement. If you need a more robust solution for parsing JavaScript modules, consider using a library like acorn or esbuild to handle the parsing.

Registering an Asynchronous Formatter

The parser and formatter functions can also be asynchronous. For example, you might want to format JSON data using a library like Prettier, which returns a promise:

import Prettier from 'prettier';

CMS.registerCustomFormat('json', 'json', {
  toFile: async (data) => Prettier.format(data),
});

If you omit fromFile, the CMS will fall back to the default parser for that file extension. In this case, the standard JSON.parse method will be used to parse JSON files.