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 configuartion 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.

description

Type: string

Default: ""

Project description. Used in project search. This can be set in the UI from app menu → Project Info.

tags

Type: string[]

Default: []

Project tags. Used in project filter and search. This can be set in the UI from app 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.

markup

Type: Editor

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

Configures the language and content of the markup editor.

style

Type: Editor

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

Configures the language and content of the style editor.

script

Type: Editor

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

Configures the language and content of the script editor.

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://cdn.skypack.dev/moment",
      "lodash": "https://cdn.skypack.dev/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://cdn.skypack.dev/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 proprties:

• 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.

readonly

Type: boolean

Default: false

If true, editors are loaded in read-only mode, where the user is not allowed to change the code.

By default, when readonly is set to true, the light-weight code editor CodeJar is used. If you wish to use another editor, set the editor property.

allowLangChange

Type: boolean

Default: true

If false, the UI will not show the menu that allows changing editor language.

mode

Type: "full" | "result" | "editor" | "codeblock"

Default: "full"

Sets display mode

tools

Type: { enabled: Array<'console' | 'compiled' | 'tests'> | 'all'; active: 'console' | 'compiled' | 'tests' | ''; status: 'closed' | 'open' | 'full' | 'none' | ''; }

Default: { enabled: 'all', active: '', status: '' }

Sets enabled and active tools and status of tools pane.

Example:

{
  "tools": {
    "enabled": ["console", "compiled"],
    "active": "console",
    "status": "open"
  }
}

show code

JS

import { createPlayground } from 'livecodes';

const options = {
  "config": {
    "script": {
      "language": "javascript",
      "content": "console.log('Hello World!');"
    },
    "activeEditor": "script",
    "tools": {
      "enabled": [
        "console",
        "compiled"
      ],
      "active": "console",
      "status": "open"
    }
  }
};
createPlayground('#container', options);

TS

import { createPlayground, type EmbedOptions } from 'livecodes';

const options: EmbedOptions = {
  "config": {
    "script": {
      "language": "javascript",
      "content": "console.log('Hello World!');"
    },
    "activeEditor": "script",
    "tools": {
      "enabled": [
        "console",
        "compiled"
      ],
      "active": "console",
      "status": "open"
    }
  }
};
createPlayground('#container', options);

React

import LiveCodes from 'livecodes/react';

export default function App() {
  const options = {
  "config": {
    "script": {
      "language": "javascript",
      "content": "console.log('Hello World!');"
    },
    "activeEditor": "script",
    "tools": {
      "enabled": [
        "console",
        "compiled"
      ],
      "active": "console",
      "status": "open"
    }
  }
};
  return (<LiveCodes {...options}></LiveCodes>);
}

Vue

<script setup>
import LiveCodes from "livecodes/vue";

const options = {
  "config": {
    "script": {
      "language": "javascript",
      "content": "console.log('Hello World!');"
    },
    "activeEditor": "script",
    "tools": {
      "enabled": [
        "console",
        "compiled"
      ],
      "active": "console",
      "status": "open"
    }
  }
};
</script>
<template>
  <LiveCodes v-bind="options" />
</template>

Svelte

<script>
import { onMount } from 'svelte';
import { createPlayground } from 'livecodes';

const options = {
  "config": {
    "script": {
      "language": "javascript",
      "content": "console.log('Hello World!');"
    },
    "activeEditor": "script",
    "tools": {
      "enabled": [
        "console",
        "compiled"
      ],
      "active": "console",
      "status": "open"
    }
  }
};
let container;
onMount(() => {
  createPlayground(container, options);
});
</script>

<div bind:this="{container}"></div>

zoom

Type: 1 | 0.5 | 0.25

Default: 1

Sets result page zoom level.

User Settings

These are properties that define the user settings, including editor settings.

autoupdate

Type: boolean

Default: true

If true, the result page is automatically updated on code change, after time delay.

autosave

Type: boolean

Default: false

If true, the project is automatically saved on code change, after time delay.

autotest

Type: boolean

Default: false

If true, the project is watched for code changes which trigger tests to auto-run.

delay

Type: number

Default: 1500

Time delay (in milliseconds) follwing code change, after which the result page is updated (if autoupdate is true) and/or the project is saved (if autosave is true).

formatOnsave

Type: boolean

Default: false

If true, the code is automatically formatted on saving the project.

theme

Type: "light" | "dark"

Default: "dark"

Sets the app theme.

recoverUnsaved

Type: boolean

Default: true

Enables recovering last unsaved project when the app is reopened.

showSpacing

Type: boolean

Default: false

Enables showing element spacing in the result page.

editor

Type: "monaco" | "codemirror" | "codejar" | undefined

Default: undefined

Selects the code editor to use.

If undefined (the default), Monaco editor is used on desktop, CodeMirror is used on mobile and CodeJar is used in codeblocks, in lite mode and in readonly playgrounds.

fontFamily

Type: string | undefined

Default: undefined

Sets the code editor font family.

fontSize

Type: number | undefined

Default: undefined

Sets the code editor font size.

If undefined (the default), the font size is set to 14 for the full app and 12 for embeds.

useTabs

Type: boolean

Default: false

If true, lines are indented with tabs instead of spaces. Also used in code formatting.

tabSize

Type: number

Default: 2

The number of spaces per indentation-level. Also used in code formatting.

lineNumbers

Type: boolean

Default: true

Show line numbers in code editor.

wordWrap

Type: boolean

Default: false

Enables word-wrap for long lines.

closeBrackets

Type: boolean

Default: true

Use auto-complete to close brackets and quotes.

emmet

Type: boolean

Default: true

Enables emmet.

editorMode

Type: "vim" | "emacs" | undefined

Default: undefined

Sets editor mode.

semicolons

Type: boolean

Default: true

Configures Prettier code formatter to use semi-colons.

singleQuote

Type: boolean

Default: false

Configures Prettier code formatter to use single quotes instead of double quotes.

trailingComma

Type: boolean

Default: true

Configures Prettier code formatter to use trailing commas.