Core Types
Playground
The main playground instance returned bycreatePlayground.
interface Playground {
load: () => Promise<void>;
run: () => Promise<void>;
format: (allEditors?: boolean) => Promise<void>;
getShareUrl: (shortUrl?: boolean) => Promise<string>;
getConfig: (contentOnly?: boolean) => Promise<Config>;
setConfig: (config: Partial<Config>) => Promise<Config>;
getCode: () => Promise<Code>;
show: (panel: string, options?: ShowOptions) => Promise<void>;
runTests: () => Promise<{ results: TestResult[] }>;
onChange: (fn: ChangeHandler) => { remove: () => void }; // deprecated
watch: WatchFn;
exec: (command: string, ...args: any[]) => Promise<any>;
destroy: () => Promise<void>;
}
EmbedOptions
Options for embedding a playground.interface EmbedOptions {
appUrl?: string;
params?: UrlQueryParams;
config?: Partial<Config> | string;
headless?: boolean;
import?: string;
lite?: boolean; // deprecated
loading?: 'lazy' | 'click' | 'eager';
template?: TemplateName;
view?: 'split' | 'editor' | 'result' | 'headless'; // deprecated
}
Config
The complete configuration object.interface Config extends ContentConfig, AppConfig, UserConfig {}
ContentConfig
interface ContentConfig {
title: string;
description: string;
head: string;
htmlAttrs: Record<string, string> | string;
tags: string[];
activeEditor: EditorId | undefined;
languages: Array<Language | Processor> | undefined;
markup: Editor;
style: Editor;
script: Editor;
stylesheets: string[];
scripts: string[];
cssPreset: CssPresetId;
processors: Processor[];
customSettings: CustomSettings;
imports: { [key: string]: string };
types: Types;
tests: Partial<Editor> | undefined;
readonly version: string;
}
AppConfig
interface AppConfig {
readonly: boolean;
allowLangChange: boolean;
view?: 'split' | 'editor' | 'result';
mode: 'full' | 'focus' | 'lite' | 'simple' | 'editor' | 'codeblock' | 'result';
tools: Partial<{
enabled: Array<Tool['name']> | 'all';
active: Tool['name'] | '';
status: ToolsPaneStatus;
}>;
zoom: 1 | 0.5 | 0.25;
}
UserConfig
interface UserConfig extends EditorConfig, FormatterConfig {
autoupdate: boolean;
autosave: boolean;
autotest: boolean;
delay: number;
formatOnsave: boolean;
layout: 'responsive' | 'horizontal' | 'vertical' | undefined;
recoverUnsaved: boolean;
showSpacing: boolean;
welcome: boolean;
appLanguage: AppLanguage | undefined;
}
Editor
Configuration for a code editor.interface Editor {
language: Language;
content?: string;
contentUrl?: string;
hiddenContent?: string;
hiddenContentUrl?: string;
foldedLines?: Array<{ from: number; to: number }>;
title?: string;
hideTitle?: boolean;
order?: number;
selector?: string;
position?: EditorPosition;
}
EditorPosition
interface EditorPosition {
lineNumber: number;
column?: number;
}
Code
Represents code from all editors.interface Code {
markup: {
language: Language;
content: string;
compiled: string;
};
style: {
language: Language;
content: string;
compiled: string;
};
script: {
language: Language;
content: string;
compiled: string;
};
result: string;
}
Language Types
Language
Supported language names, aliases, and extensions.type Language =
// Markup Languages
| 'html' | 'htm'
| 'markdown' | 'md' | 'mdown' | 'mkdn'
| 'mdx'
| 'astro'
| 'pug' | 'jade'
| 'haml'
| 'asciidoc' | 'adoc' | 'asc'
// Template Languages
| 'mustache'
| 'handlebars' | 'hbs'
| 'ejs'
| 'eta'
| 'nunjucks' | 'njk'
| 'liquid' | 'liquidjs'
| 'dot'
| 'twig'
| 'vento' | 'vto'
| 'art-template' | 'art'
| 'jinja'
// Other Markup
| 'bbcode' | 'bb'
| 'mjml'
| 'diagrams' | 'diagram' | 'graph' | 'plt'
| 'richtext' | 'rte' | 'rich' | 'rte.html'
// Style Languages
| 'css'
| 'scss'
| 'sass'
| 'less'
| 'stylus' | 'styl'
| 'stylis'
| 'postcss'
// JavaScript & Variants
| 'javascript' | 'js' | 'mjs'
| 'json'
| 'babel' | 'es'
| 'sucrase'
| 'typescript' | 'ts' | 'mts'
| 'flow'
// JSX & Frameworks
| 'jsx'
| 'tsx'
| 'react' | 'react-jsx' | 'react.jsx'
| 'react-tsx' | 'react.tsx'
| 'react-native' | 'react-native.jsx'
| 'react-native-tsx' | 'react-native.tsx'
| 'vue' | 'vue3' | 'vue2' | 'vue-app' | 'app.vue'
| 'svelte' | 'svelte-app' | 'app.svelte'
| 'stencil' | 'stencil.tsx'
| 'solid' | 'solid.jsx' | 'solid.tsx'
| 'riot' | 'riotjs'
| 'malina' | 'malinajs'
| 'ripple' | 'ripplejs'
| 'xht'
// Compile-to-JS Languages
| 'coffeescript' | 'coffee'
| 'livescript' | 'ls'
| 'civet'
| 'clio'
| 'imba'
| 'assemblyscript' | 'as'
// Python
| 'python' | 'py' | 'pyodide'
| 'python-wasm' | 'py-wasm' | 'pythonwasm' | 'pywasm' | 'py3' | 'wasm.py'
// Other Languages
| 'r' | 'rlang' | 'rstats' | 'r-wasm'
| 'ruby' | 'rb' | 'ruby-wasm' | 'wasm.rb' | 'rubywasm'
| 'go' | 'golang' | 'go-wasm' | 'wasm.go' | 'gowasm'
| 'php' | 'php-wasm' | 'phpwasm' | 'wasm.php'
| 'cpp' | 'c' | 'C' | 'cp' | 'cxx' | 'c++' | 'cppm' | 'ixx' | 'ii' | 'hpp' | 'h'
| 'cpp-wasm' | 'cppwasm' | 'cwasm' | 'wasm.cpp' | 'clang' | 'clang.cpp'
| 'java'
| 'csharp' | 'csharp-wasm' | 'cs' | 'cs-wasm' | 'wasm.cs'
| 'perl' | 'pl' | 'pm'
| 'lua' | 'lua-wasm' | 'luawasm' | 'wasm.lua'
| 'teal' | 'tl'
| 'fennel' | 'fnl'
| 'julia' | 'jl'
| 'scheme' | 'scm'
| 'commonlisp' | 'common-lisp' | 'lisp'
| 'clojurescript' | 'clojure' | 'cljs' | 'clj' | 'cljc' | 'edn'
| 'gleam'
| 'swift'
| 'rescript' | 'res' | 'resi'
| 'reason' | 're' | 'rei'
| 'ocaml' | 'ml' | 'mli'
| 'tcl'
| 'wat' | 'wast' | 'webassembly' | 'wasm' | 'Binary'
| 'sql' | 'sqlite' | 'sqlite3'
| 'pg.sql' | 'pgsql.sql' | 'pgsql' | 'pg' | 'pglite' | 'pglite.sql'
| 'postgresql' | 'postgres' | 'postgre.sql' | 'postgresql.sql'
| 'prolog.pl' | 'prolog'
| 'minizinc' | 'mzn' | 'dzn'
| 'blockly' | 'blockly.xml' | 'xml'
| 'pintora';
TemplateName
Available starter templates.type TemplateName =
| 'blank'
| 'javascript' | 'typescript'
| 'react' | 'react-native'
| 'vue2' | 'vue' | 'angular'
| 'preact' | 'svelte' | 'solid' | 'lit' | 'stencil'
| 'mdx' | 'astro'
| 'riot' | 'malina'
| 'jquery' | 'backbone' | 'knockout'
| 'jest' | 'jest-react'
| 'bootstrap' | 'tailwindcss' | 'shadcn-ui' | 'daisyui'
| 'd3' | 'phaser'
| 'coffeescript' | 'livescript' | 'civet' | 'clio' | 'imba'
| 'rescript' | 'reason' | 'ocaml'
| 'python' | 'python-wasm'
| 'r' | 'ruby' | 'ruby-wasm'
| 'go' | 'go-wasm'
| 'php' | 'php-wasm'
| 'cpp' | 'cpp-wasm'
| 'java' | 'csharp-wasm'
| 'perl' | 'lua' | 'lua-wasm' | 'teal' | 'fennel'
| 'julia' | 'scheme' | 'commonlisp' | 'clojurescript'
| 'gleam' | 'tcl'
| 'markdown' | 'assemblyscript' | 'wat'
| 'sql' | 'postgresql' | 'prolog' | 'minizinc'
| 'blockly' | 'diagrams';
Processor
CSS processors.type Processor =
| 'postcss'
| 'postcssImportUrl'
| 'tailwindcss'
| 'windicss'
| 'unocss'
| 'tokencss'
| 'lightningcss'
| 'autoprefixer'
| 'postcssPresetEnv'
| 'cssmodules'
| 'purgecss'
| 'cssnano';
Event Types
WatchFn
The watch function type.type WatchFn =
| ((event: 'load', fn: () => void) => { remove: () => void })
| ((event: 'ready', fn: (data: { config: Config }) => void) => { remove: () => void })
| ((event: 'code', fn: (data: { code: Code; config: Config }) => void) => { remove: () => void })
| ((event: 'console', fn: (data: { method: string; args: any[] }) => void) => { remove: () => void })
| ((event: 'tests', fn: (data: { results: TestResult[]; error?: string }) => void) => { remove: () => void })
| ((event: 'destroy', fn: () => void) => { remove: () => void });
SDKEvent
Available event names.type SDKEvent = 'load' | 'ready' | 'code' | 'console' | 'tests' | 'destroy';
TestResult
Test result object.interface TestResult {
duration: number;
errors: string[];
status: 'pass' | 'fail' | 'skip';
testPath: string[];
}
Editor Types
EditorId
type EditorId = 'markup' | 'style' | 'script';
EditorConfig
interface EditorConfig {
editor: 'monaco' | 'codemirror' | 'codejar' | 'auto' | undefined;
theme: Theme;
themeColor: string | undefined;
editorTheme: EditorTheme[] | string | undefined;
fontFamily: string | undefined;
fontSize: number | undefined;
useTabs: boolean;
tabSize: number;
lineNumbers: boolean | 'relative';
wordWrap: boolean;
foldRegions: boolean;
closeBrackets: boolean;
minimap: boolean;
emmet: boolean;
editorMode: 'vim' | 'emacs' | undefined;
}
Theme
type Theme = 'light' | 'dark';
EditorTheme
type EditorTheme =
| MonacoTheme
| CodemirrorTheme
| CodejarTheme
| `${MonacoTheme}@${Theme}`
| `${CodemirrorTheme}@${Theme}`
| `${CodejarTheme}@${Theme}`
| `monaco:${MonacoTheme}`
| `codemirror:${CodemirrorTheme}`
| `codejar:${CodejarTheme}`
| `monaco:${MonacoTheme}@${Theme}`
| `codemirror:${CodemirrorTheme}@${Theme}`
| `codejar:${CodejarTheme}@${Theme}`;
Custom Settings Types
CustomSettings
type CustomSettings = Partial<{
[key in Language | Processor]: any;
} & {
template: {
data?: any;
prerender?: boolean;
};
scriptType: 'module' | 'application/javascript' | /* ... */;
mapImports: boolean;
imports: Record<string, string>;
convertCommonjs: boolean;
defaultCDN: CDN;
types: Types;
}>;
Types
Custom TypeScript type declarations.interface Types {
[key: string]:
| string
| {
url: string;
declareAsModule?: boolean;
declareAsGlobal?: boolean;
autoload?: boolean;
};
}
CDN
type CDN =
| 'jspm' | 'skypack'
| 'jsdelivr' | 'fastly.jsdelivr' | 'gcore.jsdelivr' | 'testingcf.jsdelivr'
| 'jsdelivr.b-cdn' | 'jsdelivr.gh' | 'fastly.jsdelivr.gh' | 'gcore.jsdelivr.gh'
| 'testingcf.jsdelivr.gh' | 'jsdelivr.b-cdn.gh'
| 'jsdelivr.esm' | 'fastly.jsdelivr.esm' | 'gcore.jsdelivr.esm'
| 'testingcf.jsdelivr.esm' | 'jsdelivr.b-cdn.esm'
| 'esm.run' | 'esm.sh' | 'esbuild' | 'bundle.run'
| 'unpkg' | 'npmcdn' | 'statically';
Tool Types
Tool
interface Tool {
name: 'console' | 'compiled' | 'tests';
title: string;
load: () => Promise<void>;
onActivate: () => void;
onDeactivate: () => void;
getEditor?: () => CodeEditor | undefined;
}
ToolsPaneStatus
type ToolsPaneStatus = 'closed' | 'open' | 'full' | 'none' | '';
Formatter Types
FormatterConfig
interface FormatterConfig {
useTabs: boolean;
tabSize: number;
semicolons: boolean;
singleQuote: boolean;
trailingComma: boolean;
}
App Types
AppLanguage
UI language for the app.type AppLanguage =
| 'auto'
| 'ar' | 'bn' | 'de' | 'en' | 'es' | 'fa' | 'fr'
| 'hi' | 'id' | 'it' | 'ja' | 'nl' | 'pt'
| 'tr' | 'ru' | 'ur' | 'zh-CN';
CssPresetId
type CssPresetId = '' | 'normalize.css' | 'reset-css';
React Component Types
React Props
interface Props extends EmbedOptions {
className?: string;
style?: Record<string, string>;
height?: string;
sdkReady?: (sdk: Playground) => void;
}
Vue Component Types
Vue Props
interface Props extends EmbedOptions {
height?: string;
}
// Emits
interface Emits {
sdkReady: (sdk: Playground) => void;
}
Usage Examples
Using Types in TypeScript
import { createPlayground } from 'livecodes';
import type {
Playground,
Config,
Code,
Language,
EmbedOptions,
TestResult,
} from 'livecodes';
// Fully typed configuration
const config: Partial<Config> = {
markup: {
language: 'html',
content: '<h1>Hello</h1>',
},
theme: 'dark',
autoupdate: true,
};
// Typed embed options
const options: EmbedOptions = {
config,
loading: 'eager',
};
// Typed playground instance
const playground: Playground = await createPlayground('#container', options);
// Typed code object
const code: Code = await playground.getCode();
const language: Language = code.script.language;
// Typed test results
const { results }: { results: TestResult[] } = await playground.runTests();
Type Guards
import type { Config, EmbedOptions } from 'livecodes';
function isConfigObject(config: Partial<Config> | string): config is Partial<Config> {
return typeof config === 'object';
}
const options: EmbedOptions = {
config: '{}',
};
if (isConfigObject(options.config)) {
// TypeScript knows config is an object here
console.log(options.config.markup?.language);
}
Generic Type Usage
import type { Language, Editor } from 'livecodes';
function createEditor<L extends Language>(
language: L,
content: string
): Editor {
return {
language,
content,
};
}
const htmlEditor = createEditor('html', '<h1>Hi</h1>');
const tsEditor = createEditor('typescript', 'const x = 42;');
Importing Types
// Import specific types
import type { Playground, Config, Code } from 'livecodes';
// Import all types
import type * as LiveCodes from 'livecodes';
// Use namespace
const config: LiveCodes.Config = { /* ... */ };
Type Utilities
LiveCodes exports some utility types:// Makes all nested properties optional
type Prettify<T> = {
[K in keyof T]: T[K] extends object ? Prettify<T[K]> : T[K];
} & {};
// Convert union to intersection
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
k: infer I
) => void
? I
: never;
// Unwrap Promise type
type Await<T> = T extends PromiseLike<infer U> ? U : T;
Next Steps
API Reference
Review the complete API reference
Methods
Explore all available methods
Events
Learn about the event system
Getting Started
Start building with LiveCodes