live-codes 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
awaitthem or use.then().
Sub-Skills
| Task | Sub-Skill |
|---|---|
| Quick start for beginners | livecodes/getting-started/SKILL.md |
| Create embedded playgrounds | livecodes/sdk-embedding/SKILL.md |
| Use SDK methods (run, getCode, setConfig, watch) | livecodes/sdk-methods/SKILL.md |
| Compress/decompress config utilities | livecodes/sdk-embedding/SKILL.md |
| Configure via Config object, query params | livecodes/configuration/SKILL.md |
| Choose display mode (full, simple, result, etc.) | livecodes/display-modes/SKILL.md |
| Run playgrounds without visible UI | livecodes/headless-mode/SKILL.md |
| Import/export code (GitHub, gists, files) | livecodes/import-export/SKILL.md |
| Work with 90+ languages and processors | livecodes/language-support/SKILL.md |
| Import npm packages without bundler | livecodes/module-resolution/SKILL.md |
| Write and run tests in the playground | livecodes/testing/SKILL.md |
| Use with React, Vue, Svelte, Solid, Preact | livecodes/framework-wrappers/SKILL.md |
| Integrate with docs sites (Docusaurus, Astro) | livecodes/markdown-integration/SKILL.md |
| Self-host on your own server | livecodes/self-hosting/SKILL.md |
| Preview PRs in LiveCodes (GitHub Action) | livecodes/gh-action/SKILL.md |
Quick Decision Tree
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)
<!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
npm install livecodes
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
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 => playground?.run()}>Run</button>
</>
);
}
Common Mistakes
HIGH: SDK methods return Promises - always await
// 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
// 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
// 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
// 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)