Skip to main content

Custom Settings

Custom settings allow you to configure various aspects of a LiveCodes project. They are defined as a JSON object and provide fine-grained control over languages, compilers, processors, templates, module resolution, and more.

Where to Use​

Standalone App​

In the standalone app, the custom settings screen can be accessed from:

  • The editor toolbar - below the editor (the {} button)
  • The Project menu → Custom Settings …
  • The URL parameter ?screen=custom-settings.

SDK​

For embedded playgrounds, use the config.customSettings property of the configuration object:

import { createPlayground } from 'livecodes';

createPlayground('#container', {
  config: {
    customSettings: {
      // your settings here
    },
  },
});

URL Parameter​

Custom settings can also be passed as a URL query parameter using customSettings:

https://livecodes.io/?customSettings={"jsx":{"jsxFactory":"h"}}

Language and Compiler Settings​

Custom settings can be passed as options to the compiler of any supported language. The property name is the language name, and the value is a JSON object that gets passed to the compiler.

Many languages document their supported options on their respective documentation pages.

Example: TypeScript compiler options

Custom Settings
{
  "typescript": {
    "target": "es2020",
    "jsx": "react-jsx"
  }
}
note

Custom settings must be valid JSON. Functions, callbacks, and non-serializable values are not allowed.

CSS Processor Settings​

CSS processors can also be configured via custom settings using the processor name as the property.

Example: PostCSS Preset Env

Custom Settings
{
  "postcssPresetEnv": {
    "stage": 2,
    "features": {
      "nesting-rules": true
    }
  }
}

Template Data​

Pre-rendered (Default)​

For template languages (e.g. EJS, Handlebars, Mustache, Jinja, etc.), template expressions are evaluated during compilation. The values are supplied using the template.data property:

Custom Settings
{
  "template": {
    "data": {
      "name": "LiveCodes",
      "description": "A Code Playground That Just Works!",
    }
  }
}
EJS Template
<h1>Hello, <%= name %>!</h1>
<p>Description: <%= description %></p>

Dynamic​

Template rendering can be deferred to runtime by setting template.prerender to false. Values can then be provided at runtime via window.livecodes.templateData:

Custom Settings
{
  "template": {
    "prerender": false,
    "data": {
      "name": "Default Name"
    }
  }
}
Script Editor
window.livecodes.templateData = {
  name: 'Dynamic Value',
};
caution

When prerender is false, the window.livecodes.templateData assignment must occur before the page load event, as template rendering happens on page load.

Module Resolution​

Custom Import Maps​

Custom import maps allow you to override module URLs, specify versions, or import unpublished libraries:

Custom Settings
{
  "imports": {
    "react": "https://esm.sh/[email protected]",
    "lodash": "https://cdn.jsdelivr.net/npm/[email protected]",
    "my-lib": "https://my-server.com/path/to/library.js"
  }
}

This is equivalent to using <script type="importmap"> in the HTML. See Module Resolution for full details.

Default CDN​

Change the default CDN used for bare module imports:

Custom Settings
{
  "defaultCDN": "skypack"
}

Available CDN aliases: esm.sh, skypack, esm.run, jspm, bundlejs.

Custom Type Definitions​

Providing type definitions enables editor IntelliSense for custom or unpublished modules:

Custom Settings
{
  "types": {
    "my-module": "https://my-server.com/types/my-module.d.ts",
    "my-other-lib": "data:text/typescript;charset=UTF-8;base64,..."
  }
}

See IntelliSense documentation for full details and examples.

Script Type​

Override the type of the script tag used to serve the script editor compiled code.

Custom Settings
{
  "scriptType": "module"
}

CommonJS Conversion​

By default, LiveCodes converts CommonJS require() calls to ESM imports. You can disable this behavior:

Custom Settings
{
  "convertCommonjs": false
}

Language and Processor Combinations​

Custom settings for different languages and processors can be combined in a single JSON object:

Custom Settings
{
  "typescript": {
    "target": "es2022"
  },
  "autoprefixer": {
    "cascade": true
  },
  "postcssPresetEnv": {
    "stage": 3
  },
  "imports": {
    "react": "https://esm.sh/[email protected]"
  },
  "template": {
    "prerender": false,
    "data": {
      "title": "My Project"
    }
  }
}
Sponsors