Configuration Object

LiveCodes is very flexible and provides a wide range of configuration options. A JavaScript object is used for configuration and keeping state.

Usage

The configuration object can be used while initializing a new playground using the SDK.

import { createPlayground } from 'livecodes';

(async () => {
  const playground = await createPlayground('#container', {
    config: {
      // config options here
    },
  });

  // the object can be retrieved using the method `getConfig`
  console.log(await playground.getConfig());

  // and can be later changed using the method `setConfig`
  await playground.setConfig({
    // new config options
  });
})();

Alternatively, the URL query parameter config can provide a URL to a JSON representation of the configuration object to be used while initializing the app.

Example:

https://livecodes.io/?config=https://my-custom-server.com/config.json

TypeScript Types

TypeScript types are documented here and can be imported from the library.

import type { Config } from 'livecodes';

Default Config

Default config is defined here.

Project Content

These are properties that define the content of the current project.

`title`

Type: string

Default: "Untitled Project"

Project title. This is used as result page title and title meta tag. Also used in project search. This can be set in the UI from the title input (above result page) or from Project menu → Project Info.

`description`

Type: string

Default: ""

Project description. Used in project search and result page description meta tag. This can be set in the UI from Project menu → Project Info.

`head`

Type: string

Default: '<meta charset="UTF-8" />\n<meta name="viewport" content="width=device-width, initial-scale=1.0" />'

Content added to the result page <head> element. This can be set in the UI from Project menu → Project Info.

`htmlAttrs`

Type: string | Record<string, string>

Default: 'lang="en" class=""'

Attributes added to the result page <html> element. It can be an object or a string.

Example: { lang: "en", class: "dark" } or 'lang="en" class="dark"',
become <html lang="en" class="dark">.

This can be set in the UI from Project menu → Project Info.

`tags`

Type: string[]

Default: []

Project tags. Used in project filter and search. This can be set in the UI from Project menu → Project Info.

`activeEditor`

Type: "markup" | "style" | "script" | undefined

Default: Last used editor for user, otherwise "markup"

Selects the active editor to show.

`languages`

Type: Language[] | undefined

Default: all supported languages in full app and only current editor languages in embeds.

List of enabled languages. Languages that are not already loaded in the editors (markup, style and script) can be selected from a drop down menu at the editor title.

Change Language

`markup`

Type: Editor

Default: { language: "html", content: "" }

An object that configures the language and content of the markup editor. This can include the following properties:

language:
Type: Language
Default: "html" in markup editor, "css" in style editor and "javascript" in script editor.
This can be a language name, extension or alias (as defined in language documentations).
(e.g. "markdown", "md")
title: Type: string | undefined
Default: ""
If set, this is used as the title of the editor in the UI, overriding the default title set to the language name (e.g. "Python" can be used instead of "Py (Wasm)").
content: Type: string | undefined
Default: ""
The initial content of the code editor.
contentUrl: Type: string | undefined
Default: undefined
A URL to load content from. It has to be a valid URL that is CORS-enabled.
The URL is only fetched if content property had no value.
hiddenContent: Type: string | undefined
Default: undefined
Hidden content that gets evaluated without being visible in the code editor. This can be useful in embedded playgrounds (e.g. for adding helper functions, utilities or tests)
hiddenContentUrl: Type: string | undefined
Default: undefined
A URL to load hiddenContent from. It has to be a valid URL that is CORS-enabled.
The URL is only fetched if hiddenContent property had no value.
selector: Type: string | undefined
Default: undefined
A CSS selector to load content from DOM import.
position: Type: {lineNumber: number, column?: number} | undefined
Default: undefined
The initial position of the cursor in the code editor.
Example: {lineNumber: 5, column: 10}

`style`

Type: Editor

Default: { language: "css", content: "" }

An object that configures the language and content of the style editor. See markup for more details.

`script`

Type: Editor

Default: { language: "javascript", content: "" }

An object that configures the language and content of the script editor. See markup for more details.

`stylesheets`

Type: string[]

Default: []

List of URLs for external stylesheets to add to the result page.

`scripts`

Type: string[]

Default: []

List of URLs for external scripts to add to the result page.

`cssPreset`

Type: "" | "normalize.css" | "reset-css"

Default: ""

CSS Preset to use.

`processors`

Type: Processor[]

Default: []

List of enabled CSS processors.

`customSettings`

Type: CustomSettings

Default: {}

Defines custom settings for the current project.

`imports`

Type: [key: string]: string

Default: {}

Allows specifying custom import maps for module imports.

For example, adding this JavaScript code:

import moment from 'moment';
import { partition } from 'lodash';

would add this import map in the result page:

<script type="importmap">
  {
    "imports": {
      "moment": "https://esm.sh/moment",
      "lodash": "https://esm.sh/lodash"
    }
  }
</script>

However, if imports is specified as follows:

{
  "imports": {
    "moment": "https://cdn.jsdelivr.net/npm/[email protected]/dist/moment.js"
  }
}

The import map becomes like this:

<script type="importmap">
  {
    "imports": {
      "moment": "https://cdn.jsdelivr.net/npm/[email protected]/dist/moment.js",
      "lodash": "https://esm.sh/lodash"
    }
  }
</script>

Note

Currently, multiple import maps are not yet supported. https://crbug.com/927119

When bare module imports are encountered, LiveCodes adds an import map to the result page. If you need to add custom import map or override the automatically generated one, you need to add them to imports config property or imports customSettings property.

`types`

Type: [key: string]: string | { autoload?: boolean ; declareAsModule?: boolean ; url: string }

Default: {}

Allows providing custom TypeScript type declarations for better editor intellisense.

It is an object where each key represents module name and value represents the types. This can be a URL to a type declaration file. For example, if this is the type declaration file:

https://my-custom-domain/my-type-declarations.d.ts
declare module 'my-demo-lib' {
  export class Greeter {
    morning(): string;
    evening(): string;
  }
}

It can be used like that:

{
  "types": {
    "my-demo-lib": "https://my-custom-domain/my-type-declarations.d.ts"
  }
}

Alternatively, the value for module name can be an object with the following properties:

url: string (required). The URL to type declaration file.
autoload: boolean (optional). By default, the types are only loaded when the module is imported in code. If autoload property is set to true, the types are loaded regardless if the module was imported.
declareAsModule: boolean (optional). Declares the types as module with the supplied module name.

Example:

{
  "types": {
    "my-demo-lib": {
      "url": "https://my-custom-domain/types.d.ts",
      "autoload": true,
      "declareAsModule": true
    }
  }
}

`tests`

Type: undefined | Partial<Editor>

Default: { language: 'typescript', content: '' }

Configures the language and content of tests.

`version`

Type: Readonly string

Default: Current LiveCodes Version.

This is a read-only property which specifies the current LiveCodes version. It can be shown using the SDK exec method.

// in browser console of full app (e.g. https://livecodes.io)
await livecodes.exec('showVersion');

Version specified in exported projects allows automatically upgrading the project configuration when imported by an app with a newer version.

App Settings

These are properties that define how the app behaves.

Configuration Object

Usage​

TypeScript Types​

Default Config​

Project Content​

title​

description​

head​

htmlAttrs​

tags​

activeEditor​

languages​

markup​

style​

script​

stylesheets​

scripts​

cssPreset​

processors​

customSettings​

imports​

types​

tests​

version​

App Settings​

readonly​

allowLangChange​

mode​

tools​

zoom​

User Settings​

enableAI​

autoupdate​

autosave​

autotest​

delay​

formatOnsave​

layout​

theme​

themeColor​

editorTheme​

appLanguage​

recoverUnsaved​

welcome​

showSpacing​

editor​

fontFamily​

fontSize​

useTabs​

tabSize​

lineNumbers​

wordWrap​

closeBrackets​

emmet​

editorMode​

semicolons​

singleQuote​

trailingComma​

Usage

TypeScript Types

Default Config

Project Content

`title`

`description`

`head`

`htmlAttrs`

`tags`

`activeEditor`

`languages`

`markup`

`style`

`script`

`stylesheets`

`scripts`

`cssPreset`

`processors`

`customSettings`

`imports`

`types`

`tests`

`version`

App Settings

`readonly`

`allowLangChange`

`mode`

`tools`

`zoom`

User Settings

`enableAI`

`autoupdate`

`autosave`

`autotest`

`delay`

`formatOnsave`

`layout`

`theme`

`themeColor`

`editorTheme`

`appLanguage`

`recoverUnsaved`

`welcome`

`showSpacing`

`editor`

`fontFamily`

`fontSize`

`useTabs`

`tabSize`

`lineNumbers`

`wordWrap`

`closeBrackets`

`emmet`

`editorMode`

`semicolons`

`singleQuote`

`trailingComma`