Configuration Object

The Config object is the central configuration interface for LiveCodes. It contains all settings that control the playground’s content, appearance, and behavior.

Config Interface

The Config interface extends three main configuration categories:

interface Config extends ContentConfig, AppConfig, UserConfig {}

Content Configuration

Properties that define the content of the current project.

Project Metadata

title

string

default:"\"Untitled Project\""

Project title. Used as result page title, title meta tag, and in project search.

description

string

default:"\"\""

Project description. Used in project search and result page description meta tag.

HTML Configuration

head

string

Content added to the result page <head> element.

head: '<meta name="author" content="John Doe" />'

htmlAttrs

Record<string, string> | string

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

// As object
htmlAttrs: { lang: 'en', class: 'dark' }

// As string
htmlAttrs: 'lang="en" class="dark"'

// Both become: <html lang="en" class="dark">

Editor Configuration

activeEditor

"markup" | "style" | "script" | undefined

Selects the active editor to show. Defaults to the last used editor for user, otherwise "markup".

markup

Editor

default:"{ language: \"html\", content: \"\" }"

Configuration for the markup editor.See Editor interface for details.

style

Editor

default:"{ language: \"css\", content: \"\" }"

Configuration for the style editor.See Editor interface for details.

script

Editor

default:"{ language: \"javascript\", content: \"\" }"

Configuration for the script editor.See Editor interface for details.

languages

Language[] | undefined

List of enabled languages. Defaults to all supported languages in full app and only current editor languages in embeds.

languages: ['html', 'css', 'javascript', 'typescript', 'jsx', 'tsx']

External Resources

stylesheets

string[]

default:"[]"

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

stylesheets: [
  'https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css'
]

scripts

string[]

default:"[]"

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

scripts: [
  'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js'
]

cssPreset

"" | "normalize.css" | "reset-css"

default:"\"\""

CSS preset to use.

"normalize.css": Normalize.css for consistent cross-browser styling
"reset-css": CSS reset to remove default browser styles
"": No preset

Processors

processors

Processor[]

default:"[]"

List of enabled CSS processors.Available processors:

"postcss"
"tailwindcss"
"windicss"
"unocss"
"tokencss"
"lightningcss"
"autoprefixer"
"postcssPresetEnv"
"cssmodules"
"purgecss"
"cssnano"

processors: ['tailwindcss', 'autoprefixer']

Module Resolution

imports

{ [key: string]: string }

default:"{}"

Custom import maps for module resolution.

imports: {
  "react": "https://esm.sh/react@18",
  "moment": "https://cdn.jsdelivr.net/npm/[email protected]/+esm"
}

This creates an import map:

<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@18",
    "moment": "https://cdn.jsdelivr.net/npm/[email protected]/+esm"
  }
}
</script>

types

Types

default:"{}"

Custom TypeScript type declarations for editor IntelliSense.

types: {
  // Simple URL reference
  "my-lib": "https://example.com/types.d.ts",
  
  // Advanced configuration
  "other-lib": {
    url: "https://example.com/other.d.ts",
    autoload: true,
    declareAsModule: true
  }
}

Tests

tests

Partial<Editor> | undefined

Configures the language and content of tests.

tests: {
  language: 'typescript',
  content: `
import { test, expect } from '@playwright/test';

test('example test', () => {
expect(1 + 1).toBe(2);
});
  `
}

Custom Settings

customSettings

CustomSettings

default:"{}"

Advanced language-specific and compiler settings.See Custom Settings for details.

Version

version

string

Read-only property specifying the current LiveCodes version. Used for automatic configuration upgrades when importing projects.

App Configuration

Properties that define how the app behaves.

Display and Behavior

readonly

boolean

default:"false"

If true, editors are loaded in read-only mode. Users cannot change the code.By default, the lightweight CodeJar editor is used in readonly mode. To use a different editor, set the editor property.

allowLangChange

boolean

default:"true"

If false, the UI does not show the menu for changing editor language.

view

"split" | "editor" | "result"

default:"\"split\""

Sets the default view for the playground.

"split": Shows both editor and result side-by-side
"editor": Shows only the editor
"result": Shows only the result page

mode

default:"\"full\""

Sets the display mode.See Display Modes for details on each mode.

zoom

1 | 0.5 | 0.25

default:"1"

Sets result page zoom level.

1: 100% zoom (default)
0.5: 50% zoom
0.25: 25% zoom

Tools Configuration

tools

object

Sets enabled and active tools and status of tools pane.

tools: {
  enabled: ['console', 'compiled'],  // or 'all'
  active: 'console',
  status: 'open'  // 'open' | 'closed' | 'full' | 'none' | ''
}

Available tools:

"console": JavaScript console
"compiled": Compiled code viewer
"tests": Test runner and results

User Configuration

User preferences and settings.

Auto Features

autoupdate

boolean

default:"true"

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

autosave

boolean

default:"false"

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

autotest

boolean

default:"false"

If true, tests automatically run on code changes.

delay

number

default:"1500"

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

formatOnsave

boolean

default:"false"

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

Layout and UI

layout

"responsive" | "horizontal" | "vertical" | undefined

default:"\"responsive\""

Sets the app layout.

"responsive": Vertical on small screens when height is greater than width, otherwise horizontal
"horizontal": Always horizontal layout
"vertical": Always vertical layout

recoverUnsaved

boolean

default:"true"

Enables recovering last unsaved project when the app is reopened.

showSpacing

boolean

default:"false"

Enables showing element spacing in the result page.

welcome

boolean

If true, the welcome screen is displayed when the app loads.

appLanguage

AppLanguage | undefined

Sets the app UI language.Available languages: "auto", "ar", "bn", "de", "en", "es", "fa", "fr", "hi", "id", "it", "ja", "nl", "pt", "tr", "ru", "ur", "zh-CN"

Editor Settings

editor

"monaco" | "codemirror" | "codejar" | "auto" | undefined

default:"undefined"

Selects the code editor to use.

undefined: Monaco on desktop, CodeMirror on mobile, CodeJar in lite/readonly/codeblock modes
"auto": Monaco on desktop, CodeMirror on mobile (regardless of other settings)
"monaco": Always use Monaco editor
"codemirror": Always use CodeMirror editor
"codejar": Always use CodeJar editor

theme

"light" | "dark"

default:"\"dark\""

Sets the app theme.

themeColor

string | undefined

Sets the app theme color. Defaults to "hsl(214, 40%, 50%)".

editorTheme

EditorTheme[] | string | undefined

Sets the code editor theme(s).

// Simple theme name
editorTheme: "vs-dark"

// Multiple themes for different app themes
editorTheme: ["github-light@light", "github-dark@dark"]

// Editor-specific themes
editorTheme: "monaco:vs-dark, codemirror:one-dark"

See Themes for available theme names.

fontFamily

string | undefined

Sets the code editor font family.

fontSize

number | undefined

Sets the font size. Defaults to 14 for full app, 12 for embeds.

useTabs

boolean

default:"false"

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

tabSize

number

default:"2"

Number of spaces per indentation level. Also used in code formatting.

lineNumbers

boolean | 'relative'

default:"true"

Show line numbers in code editor.

true: Show absolute line numbers
false: Hide line numbers
"relative": Show relative line numbers (Vim-style)

wordWrap

boolean

default:"false"

Enables word-wrap for long lines.

foldRegions

boolean

default:"false"

When true, regions marked by #region and #endregion comments are folded when the project loads.

closeBrackets

boolean

default:"true"

Use auto-complete to close brackets and quotes.

minimap

boolean

default:"false"

Enables minimap in code editor.

emmet

boolean

default:"true"

Enables Emmet abbreviations.

editorMode

"vim" | "emacs" | undefined

Sets editor mode for keybindings.

"vim": Vim keybindings
"emacs": Emacs keybindings
undefined: Standard editor keybindings

Formatter Settings

semicolons

boolean

default:"true"

Configures Prettier code formatter to use semicolons.

singleQuote

boolean

default:"false"

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

trailingComma

boolean

default:"true"

Configures Prettier code formatter to use trailing commas.

Editor Interface

The Editor interface defines configuration for each code editor (markup, style, script).

language

Language

required

A language name, extension, or alias.See Language type for all supported values.

language: 'typescript'  // or 'ts'

content

string

default:"\"\""

The initial content of the code editor.

content: 'console.log("Hello, World!");'

contentUrl

string

A URL to load content from. Must be a valid CORS-enabled URL.Only fetched if content property has no value.

contentUrl: 'https://example.com/script.js'

hiddenContent

string

Hidden content that gets evaluated without being visible in the code editor.Useful for helper functions, utilities, or tests in embedded playgrounds.

hiddenContent: 'const helper = (x) => x * 2;'

hiddenContentUrl

string

A URL to load hiddenContent from. Must be a valid CORS-enabled URL.Only fetched if hiddenContent property has no value.

foldedLines

Array<{ from: number; to: number }>

Lines that get folded when the editor loads.

foldedLines: [
  { from: 5, to: 8 },
  { from: 15, to: 20 }
]

title

string

Custom title for the editor in the UI. Overrides the default language name.

title: "Python"  // instead of "Py (Wasm)"

hideTitle

boolean

If true, the title of the code editor is hidden, but the code is still evaluated.Useful in embedded playgrounds for hiding unnecessary code.

order

number

default:"0"

The order of the editor in the UI.

selector

string

A CSS selector to load content from DOM import.

selector: '#my-code'

position

EditorPosition

The initial cursor position in the code editor.

position: { lineNumber: 5, column: 10 }

Complete Example

import { createPlayground } from 'livecodes';
import type { Config } from 'livecodes';

const config: Partial<Config> = {
  // Content Configuration
  title: 'React TypeScript App',
  description: 'A React application with TypeScript',
  tags: ['react', 'typescript'],
  head: '<meta name="author" content="LiveCodes" />',
  htmlAttrs: { lang: 'en', class: 'dark' },
  
  activeEditor: 'script',
  markup: {
    language: 'html',
    content: '<div id="root"></div>',
  },
  style: {
    language: 'scss',
    content: `
body {
  font-family: system-ui;
  padding: 2rem;
}
    `,
  },
  script: {
    language: 'tsx',
    content: `
import { createRoot } from 'react-dom/client';

function App() {
  return <h1>Hello, React!</h1>;
}

const root = createRoot(document.getElementById('root')!);
root.render(<App />);
    `,
  },
  
  stylesheets: [],
  scripts: [],
  processors: ['autoprefixer'],
  
  imports: {
    'react': 'https://esm.sh/react@18',
    'react-dom/client': 'https://esm.sh/react-dom@18/client',
  },
  
  // App Configuration
  readonly: false,
  allowLangChange: true,
  view: 'split',
  mode: 'full',
  tools: {
    enabled: ['console', 'compiled'],
    active: 'console',
    status: 'closed',
  },
  zoom: 1,
  
  // User Configuration
  autoupdate: true,
  autosave: false,
  delay: 1500,
  formatOnsave: false,
  layout: 'responsive',
  
  theme: 'dark',
  editorTheme: ['github-light@light', 'github-dark@dark'],
  fontSize: 14,
  fontFamily: 'Monaco, Consolas, monospace',
  
  useTabs: false,
  tabSize: 2,
  lineNumbers: true,
  wordWrap: false,
  closeBrackets: true,
  emmet: true,
  
  semicolons: true,
  singleQuote: false,
  trailingComma: true,
};

await createPlayground('#container', { config });

Query Parameters

Configure playgrounds using URL parameters

Editor Settings

Detailed editor configuration options

Custom Settings

Advanced language-specific settings

Display Modes

Different playground display modes

Get Started

Features

SDK

Languages

Configuration

Advanced

Resources

Configuration Object

Config Interface

Content Configuration

Project Metadata

HTML Configuration

Editor Configuration

External Resources

Processors

Module Resolution

Tests

Custom Settings

Version

App Configuration

Display and Behavior

Tools Configuration

User Configuration

Auto Features

Layout and UI

Editor Settings

Formatter Settings

Editor Interface

Complete Example

Query Parameters

Editor Settings

Custom Settings

Display Modes

Build docs developers (and LLMs) love

Get Started

Features

SDK

Languages

Configuration

Advanced

Resources

​Config Interface

​Content Configuration

​Project Metadata

​HTML Configuration

​Editor Configuration

​External Resources

​Processors

​Module Resolution

​Tests

​Custom Settings

​Version

​App Configuration

​Display and Behavior

​Tools Configuration

​User Configuration

​Auto Features

​Layout and UI

​Editor Settings

​Formatter Settings

​Editor Interface

​Complete Example

​Related Documentation

Query Parameters

Editor Settings

Custom Settings

Display Modes

Build docs developers (and LLMs) love

Config Interface

Content Configuration

Project Metadata

HTML Configuration

Editor Configuration

External Resources

Processors

Module Resolution

Tests

Custom Settings

Version

App Configuration

Display and Behavior

Tools Configuration

User Configuration

Auto Features

Layout and UI

Editor Settings

Formatter Settings

Editor Interface

Complete Example

Related Documentation