livecodes/configuration

LiveCodes — Configure Playground

LiveCodes uses configuration objects to define project content and behavior. Config can be passed to createPlayground or set via URL parameters.

Setup

import { createPlayground } from 'livecodes';

// Full config object
createPlayground('#container', {
  config: {
    title: 'My Project',
    markup: { language: 'html', content: '<h1>Hello</h1>' },
    style: { language: 'css', content: 'h1 { color: blue; }' },
    script: { language: 'javascript', content: 'console.log("hi")' },
    activeEditor: 'script',
  },
});

// Query params (simpler syntax)
createPlayground('#container', {
  params: {
    html: '<h1>Hello</h1>',
    css: 'h1 { color: blue; }',
    js: 'console.log("hi")',
    console: 'open',
  },
});

Core Patterns

Configure each editor

const config = {
  markup: {
    language: 'markdown',
    content: '# Title\n\nParagraph',
    contentUrl: 'https://example.com/content.md', // Alternative to content
  },
  style: {
    language: 'scss',
    content: '$color: blue; h1 { color: $color; }',
  },
  script: {
    language: 'typescript',
    content: 'const x: number = 1;',
    hiddenContent: 'export function helper() {}', // Hidden but evaluated
  },
};

Enable CSS processors

const config = {
  style: { language: 'css', content: '...' },
  processors: ['tailwindcss', 'autoprefixer'], // Processors run in order
};

Add external resources

const config = {
  stylesheets: ['https://cdn.jsdelivr.net/npm/tailwindcss@3/dist/tailwind.min.css'],
  scripts: ['https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js'],
};

Configure tests

const config = {
  tests: {
    language: 'typescript',
    content: `
      import { sum } from './script';
      test('sums numbers', () => {
        expect(sum(1, 2)).toBe(3);
      });
    `,
  },
};

Set display mode

const config = {
  mode: 'simple', // 'full' | 'focus' | 'simple' | 'lite' | 'editor' | 'codeblock' | 'result'
  view: 'result', // 'split' | 'editor' | 'result'
  readonly: true, // Read-only mode
};

Configure editor settings

const config = {
  editor: 'monaco', // 'monaco' | 'codemirror' | 'codejar' | 'auto'
  theme: 'dark', // 'light' | 'dark'
  editorTheme: 'vs-dark', // See themes in docs
  fontFamily: 'Fira Code',
  fontSize: 14,
  useTabs: false,
  tabSize: 2,
  lineNumbers: true,
  wordWrap: false,
  emmet: true,
  editorMode: 'vim', // 'vim' | 'emacs' | undefined
};

Add custom imports

const config = {
  imports: {
    'my-lib': 'https://my-cdn.com/lib.js',
    'my-lib/submodule': 'https://my-cdn.com/sub.js',
  },
};

Use URL query parameters

URL: https://livecodes.io/?js=console.log("Hello")&console=open&theme=light

// Equivalent in createPlayground
createPlayground('#container', {
  params: {
    js: 'console.log("Hello")',
    console: 'open',
    theme: 'light',
  },
});

Hidden content for embedded playgrounds

const config = {
  script: {
    language: 'javascript',
    content: 'export function myFunc() { return 42; }',
    hiddenContent: '// Hidden helper\nfunction helper() { return 1; }',
  },
  tests: {
    language: 'javascript',
    content: "import { myFunc } from './script';\ntest('works', () => expect(myFunc()).toBe(42))",
  },
};

Common Mistakes

HIGH Confusing Config with EmbedOptions

Wrong:

createPlayground('#container', {
  config: {
    appUrl: 'https://my-server.com', // Wrong: appUrl belongs in EmbedOptions
    template: 'react', // Wrong: template belongs in EmbedOptions
  },
});

Correct:

createPlayground('#container', {
  // EmbedOptions (SDK-level settings)
  appUrl: 'https://my-server.com',
  template: 'react',
  loading: 'lazy',
  headless: false,

  // Config (Project content)
  config: {
    title: 'My Project',
    markup: { language: 'html', content: '<h1>Hello</h1>' },
    style: { language: 'css', content: '...' },
    script: { language: 'javascript', content: '...' },
  },
});

EmbedOptions controls how the playground is embedded (appUrl, template, loading, headless). Config controls the project content (languages, code, processors).

Source: docs/docs/sdk/js-ts.mdx — EmbedOptions section

MEDIUM Params overriding config unexpectedly

Wrong:

createPlayground('#container', {
  config: {
    markup: { language: 'html', content: '<h1>A</h1>' },
  },
  params: {
    html: '<h1>B</h1>', // This overrides config.markup!
  },
});

Correct:

// Use one source or understand precedence:
// params > config > import > template

createPlayground('#container', {
  params: {
    html: '<h1>B</h1>',
  },
  // No config needed for simple cases
});

// Or use config only
createPlayground('#container', {
  config: {
    markup: { language: 'html', content: '<h1>A</h1>' },
  },
});

When both config and params are provided, params takes precedence. Use one or the other for clarity.

Source: docs/docs/sdk/js-ts.mdx — Multiple Sources section

MEDIUM Using incorrect language name

Wrong:

const config = {
  script: { language: 'react.js', content: '...' }, // Invalid
};

Correct:

// Use language name, extension, or alias
const config = {
  script: { language: 'react', content: '...' }, // Language name
  // or
  script: { language: 'jsx', content: '...' }, // Extension
  // or
  script: { language: 'react-jsx', content: '...' }, // Alias
};

Language names must match supported values. See languages reference for all options.

Source: src/sdk/models.ts — Language type

Config Reference

Project Content

Editor Content (markup, style, script, tests)

Each editor config object supports:

External Resources

Module Resolution

App Settings

User Settings

Editor Settings

EmbedOptions Reference

Query Parameters

Many config options can be set via URL parameters:

https://livecodes.io/?template=react&theme=light&console=open

Boolean params: ?lite, ?autoupdate=false Array params: ?processors=tailwindcss,autoprefixer Custom settings: ?customSettings.template.prerender=false