livecodes-self-hosting

name	livecodes/self-hosting
description	Deploy LiveCodes to static servers, GitHub Pages, or Docker. Configure SDK appUrl, BASE_URL for subdirectories, and handle share/broadcast services. Load this skill when self-hosting LiveCodes or using a custom app URL.
type	composition
library	livecodes
library_version	0.13.0
requires	["sdk-embedding"]
sources	["live-codes/livecodes:docs/docs/features/self-hosting.mdx"]

This skill requires sdk-embedding. Read it first for foundational concepts.

LiveCodes — Self-Host LiveCodes

LiveCodes runs entirely client-side. Host it on any static file server or CDN.

Deployment Options

Download Release

1. Download from GitHub releases
2. Extract the build folder
3. Serve from any static host

# Files to serve
build/
├── index.html
├── livecodes/
│   ├── assets/
│   └── ...
└── docs/ (optional)

Build from Source

git clone https://github.com/live-codes/livecodes.git
cd livecodes
npm install
npm run build      # Build to build/ directory
npm run serve      # Local preview at http://localhost:8080
npm run deploy      # Build + deploy to GitHub Pages

GitHub Pages (Built-in)

# Setup
npm install
npm run deploy      # Deploys to gh-pages branch

Configure CNAME file for custom domain if needed.

Docker

docker-compose up -d

Docker setup includes:

• HTTPS with auto-certificates
• Share service (short URLs)
• Broadcast server
• Open Graph meta tags
• Custom 404 page

# docker-compose.yml
# See: docs/docs/advanced/docker.mdx for customization

Other Static Hosts

• Cloudflare Pages: Connect repo, npm run build, serve build/
• Netlify: Connect repo, npm run build, serve build/
• Firebase Hosting: firebase init hosting, deploy build/

Configure SDK for Self-Hosted App

import { createPlayground } from 'livecodes';

createPlayground('#container', {
  appUrl: 'https://playground.example.com',
  template: 'react',
});

The appUrl tells the SDK where to load the playground iframe from.

Custom Build

Subdirectory Hosting

By default, LiveCodes expects to be at the root of a domain. For subdirectories:

# Host at https://example.com/playground/
npx cross-env BASE_URL="/playground/" npm run build

This sets <base href="/playground/"> and adjusts all asset paths.

Skip Building Docs

To link documentation to livecodes.io instead of building locally:

npx cross-env DOCS_BASE_URL=null npm run build:app

Docs links will point to https://livecodes.io/docs/ instead of local docs.

Services

Self-hosted apps use fallback services:

Service	Default Hosted	Self-Hosted
Share (short URLs)	dpaste.com (365 days)	dpaste.com or Docker setup
Broadcast	LiveCodes server	Docker setup required
GitHub Integration	LiveCodes OAuth	Your GitHub App

Docker for Full Services

Docker setup provides all services:

docker-compose up -d
# Serves at https://livecodes.localhost

See docs/docs/advanced/docker.mdx for configuration.

Permanent URL for Stable Embeds

Use versioned URLs to prevent breaking changes:

// Version-specific URL (never changes)
createPlayground('#container', {
  appUrl: 'https://v48.livecodes.io',
  template: 'react',
});

// Pin SDK version
import { createPlayground } from 'livecodes@0.13.0';
// or
import { createPlayground } from 'https://cdn.jsdelivr.net/npm/livecodes@0.13.0';

Permanent URLs format: https://v{VERSION}.livecodes.io

Common Mistakes

MEDIUM Not configuring BASE_URL for subdirectories

Wrong:

# Build default, serve at /playground/
npm run build
# Results in broken asset paths

Correct:

# Set BASE_URL for subdirectory
npx cross-env BASE_URL="/playground/" npm run build

Without BASE_URL, the app expects to be at root (/) and asset paths will be wrong.

Source: docs/docs/features/self-hosting.mdx — Custom Build section

MEDIUM Self-hosted share URLs expire

// dpaste.com deletes share URLs after 365 days
// For permanent self-hosted share:
// 1. Use Docker setup for own share service
// 2. Or use permanent URL pattern for embeds

The default dpaste.com service deletes shared URLs after one year. For permanent sharing, use Docker setup with your own share service.

Source: docs/docs/features/self-hosting.mdx — Services section

Examples

GitHub Pages

# Fork live-codes/livecodes
# Enable GitHub Pages in repo settings
npm install
npm run deploy

# Access at https://your-username.github.io/livecodes/

Cloudflare Pages

# Build command: npm run build:app
# Output directory: build
# Environment: NODE_VERSION=18

# Access at https://your-subdomain.pages.dev/

Docker VPS

git clone https://github.com/live-codes/livecodes.git
cd livecodes
docker-compose up -d

# Access at https://livecodes.localhost
# Configure domain in docker-compose.yml