Livecodes

LiveCodes Overview

LiveCodes is a feature-rich, open-source, client-side code playground that runs entirely in the browser. No server required. Supports 90+ languages/frameworks with a powerful SDK for embedding in any web application.

CRITICAL: LiveCodes runs CLIENT-SIDE. No server, no build step, no backend. Do not confuse with server-based playgrounds.

CRITICAL: All SDK methods are async (return Promises). Always await them or use .then().

Sub-Skills

Quick Decision Tree

Copy code
New to LiveCodes?
  → livecodes/getting-started

Need to embed a playground in your app?
  → livecodes/sdk-embedding

Need to control playground programmatically?
  → livecodes/sdk-methods

Need to configure project content (languages, theme, etc.)?
  → livecodes/configuration

Need to show code readonly or result-only?
  → livecodes/display-modes

Need to run playground without any UI?
  → livecodes/headless-mode

Need to use React/Vue/Svelte/etc.?
  → livecodes/framework-wrappers

Need to import npm packages or external modules?
  → livecodes/module-resolution

Need a specific language (Python, SASS, TypeScript)?
  → livecodes/language-support

Need to run tests in the playground?
  → livecodes/testing

Need to import code from GitHub/URL or export?
  → livecodes/import-export

Need to add playgrounds to markdown docs?
  → livecodes/markdown-integration

Need to host LiveCodes on your own server?
  → livecodes/self-hosting

Need to preview PR changes in playgrounds?
  → livecodes/gh-action

Minimal Working Example

CDN (quickest)

htmlCopy code
<!doctype html>
<html>
  <head>
    <title>LiveCodes Demo</title>
  </head>
  <body>
    <div id="container"></div>
    <script type="module">
      import { createPlayground } from 'https://cdn.jsdelivr.net/npm/livecodes';

      createPlayground('#container', {
        config: {
          markup: { language: 'html', content: '<h1>Hello LiveCodes!</h1>' },
          style: { language: 'css', content: 'h1 { color: blue; }' },
          script: { language: 'javascript', content: 'console.log("Hello!");' },
        },
      });
    </script>
  </body>
</html>

NPM

bashCopy code
npm install livecodes

javascriptCopy code
import { createPlayground } from 'livecodes';

const playground = await createPlayground('#container', {
  config: {
    markup: { language: 'html', content: '<h1>Hello!</h1>' },
  },
});

// SDK methods are async - always await
await playground.run();
const code = await playground.getCode();

React

jsxCopy code
import { useState } from 'react';
import LiveCodes from 'livecodes/react';

export default function App() {
  const [playground, setPlayground] = useState(null);

  return (
    <>
      <LiveCodes
        config={{ markup: { language: 'html', content: '<h1>Hello!</h1>' } }}
        sdkReady={setPlayground}
      />
      <button onClick={() => playground?.run()}>Run</button>
    </>
  );
}

Common Mistakes

HIGH: SDK methods return Promises - always await

javascriptCopy code
// WRONG - code is a Promise, not actual code
const code = playground.getCode();
console.log(code.markup); // undefined!

// CORRECT - await the Promise
const code = await playground.getCode();
console.log(code.markup.content); // '<h1>Hello!</h1>'

HIGH: Container must exist before createPlayground

javascriptCopy code
// WRONG - container doesn't exist yet
createPlayground('#container', { config }); // throws if #container not in DOM

// CORRECT - ensure container exists
const container = document.querySelector('#container');
if (container) {
  createPlayground('#container', { config });
}

// OR use headless mode if no UI needed
createPlayground({ headless: true, config });

HIGH: Config vs EmbedOptions confusion

javascriptCopy code
// WRONG - appUrl is not a config property
createPlayground('#container', {
  config: {
    appUrl: 'https://my-server.com', // ERROR: wrong place
  },
});

// CORRECT - appUrl is an EmbedOption, not config
createPlayground('#container', {
  appUrl: 'https://my-server.com', // EmbedOptions
  config: {
    // Config
    markup: { language: 'html', content: '<h1>Hi</h1>' },
  },
});

MEDIUM: Different CDN imports create separate module instances

javascriptCopy code
// WRONG - two different React instances
import React from 'react'; // esm.sh
import { createRoot } from 'skypack:react-dom/client'; // Different React!

// CORRECT - use same CDN consistently
import React from 'react';
import { createRoot } from 'react-dom/client'; // Both from esm.sh (default)