Skip to main content

AI Guide

This guide is specifically designed for AI Large Language Models (LLMs) and autonomous agents to effectively use the LiveCodes library for creating and embedding code playgrounds.

llms.txt​

For optimal context when working with LiveCodes, use these specially formatted documentation files:

📄 llms.txt - Concise overview of the library, installation, basic usage, and key concepts

📄 llms-full.txt - Complete documentation including all guides, API reference, and examples

These files are specifically structured for AI consumption with:

  • Clear API signatures and type definitions
  • Code examples with expected outputs
  • Language and framework reference lists
  • Best practices and common patterns

See https://llmstxt.org/ for more information about llms.txt standards.

Skills​

LiveCodes provides skills for enhanced AI-assisted development.

Installation for AI Agents​

# Add skills into your project
npx skills add live-codes/livecodes

Available Skills​

SkillDescription
livecodes/getting-startedQuick start, installation, first playground
livecodes/sdk-embeddingcreatePlayground, EmbedOptions, containers
livecodes/sdk-methodsrun, getCode, setConfig, watch, format
livecodes/configurationConfig object, query params, processors
livecodes/display-modesfull, simple, lite, editor, result modes
livecodes/headless-modeRun without visible UI
livecodes/import-exportGitHub, gists, URLs, files, ZIP, HTML
livecodes/language-support90+ languages, compilers, CSS processors
livecodes/module-resolutionnpm, jsr, GitHub imports, CDN resolution
livecodes/testingJest and Testing Library in the browser
livecodes/framework-wrappersReact, Vue, Svelte, Solid, Preact wrappers
livecodes/markdown-integrationDocusaurus, Astro, VitePress, Next.js
livecodes/self-hostingStatic servers, GitHub Pages, Docker
livecodes/gh-actionPreview PRs in LiveCodes

Using Skills​

AI agents can load relevant skills automatically based on context:

  • Creating a new embedded playground → loads sdk-embedding
  • Configuring languages or processors → loads language-support
  • Using React/Vue/Svelte wrappers → loads framework-wrappers
  • Running tests in the playground → loads testing
  • Importing npm packages → loads module-resolution
  • Self-hosting LiveCodes → loads self-hosting

Key Concepts for AI Agents​

1. Creating a Playground​

import { createPlayground } from 'livecodes';

// Always await createPlayground - it returns a Promise
const playground = await 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!");' },
  },
});

2. SDK Methods Are Async​

All SDK methods return Promises. Always await them.

// Run the playground
await playground.run();

// Get current code
const code = await playground.getCode();

// Set new configuration
await playground.setConfig({ /* ... */ });

// Format code
await playground.format();

3. Configuration​

const playground = await createPlayground('#container', {
  // Default view
  view: 'split', // 'split' | 'editor' | 'result'

  // Readonly mode
  readonly: false,

  // Configuration for code editors
  config: {
    markup: { language: 'html', content: '<div>Hello</div>' },
    style: { language: 'css', content: 'div { color: red; }' },
    script: { language: 'typescript', content: 'console.log("Hello");' },
  },
});

4. Language Support​

LiveCodes supports 90+ languages. Use the language property in editor config:

const config = {
  markup: { language: 'markdown', content: '# Title' },
  style: { language: 'scss', content: '$color: blue; div { color: $color; }' },
  script: { language: 'python', content: 'print("Hello")' },
}

5. Module Resolution​

Import npm packages directly without a bundler:

// In the script editor
import confetti from 'canvas-confetti';

Common Patterns​

React Integration​

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

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

  const runCode = async () => {
    if (playground) {
      await playground.run();
    }
  };

  return (
    <>
      <LiveCodes
        sdkReady={setPlayground}
        config={{
          markup: { language: 'html', content: '<h1>Hello React!</h1>' },
          script: { language: 'javascript', content: 'console.log("Hello");' },
        }}
      />
      <button onClick={runCode}>Run</button>
    </>
  );
}

Headless Mode (No UI)​

import { createPlayground } from 'livecodes';

const playground = await createPlayground({
  headless: true,
  config: {
    markup: { language: 'markdown', content: '# Hello LiveCodes!' },
  }
});

// Compile and get output without visible UI
await playground.run();
const result = await playground.getCode();

Common Mistakes to Avoid​

Forgetting Async/Await​

// ❌ Wrong: Not awaiting
const playground = createPlayground('#container', {});
await playground.run(); // Error! playground is a Promise

// ✅ Correct: Always await createPlayground
const playground = await createPlayground('#container', {});
await playground.run();

Server-Side Assumptions​

// ❌ Wrong: Assuming server-side rendering
import { createPlayground } from 'livecodes';
// This won't work in Node.js without a DOM

// ✅ Correct: LiveCodes is client-side only
// Use in browser environments or frameworks that hydrate client-side

Confusing Display Mode and Default View​

// ❌ Wrong: Using 'code' instead of 'editor'
const playground = await createPlayground('#container', {
  view: 'codeblock', // Invalid view
});

// ✅ Correct: Use valid default view
const playground = await createPlayground('#container', {
  view: 'editor', // 'split' | 'editor' | 'result'
});

Best Practices for AI Generation​

  1. Always await createPlayground - it returns a Promise
  2. Use descriptive configuration for better maintainability
  3. Choose appropriate display modes based on use case
  4. Import only needed languages to optimize loading
  5. Handle async operations properly with await or .then()
  6. Load relevant skills for enhanced guidance on specific tasks
  7. Remember client-side only - no server-side rendering

Resources​

Sponsors