Embedded Playgrounds

Overview

LiveCodes playgrounds can be embedded in any web page. The playground can be prefilled with code in any supported language. This can be very useful in documentation websites, technical blogs, educational websites and others.

Demo:

show code

JS

import { createPlayground } from 'livecodes';

const options = {
  "template": "javascript"
};
createPlayground('#container', options);

TS

import { createPlayground, type EmbedOptions } from 'livecodes';

const options: EmbedOptions = {
  "template": "javascript"
};
createPlayground('#container', options);

React

import LiveCodes from 'livecodes/react';

export default function App() {
  const options = {
  "template": "javascript"
};
  return (<LiveCodes {...options} />);
}

Vue

<script setup>
import LiveCodes from "livecodes/vue";

const options = {
  "template": "javascript"
};
</script>
<template>
  <LiveCodes v-bind="options" />
</template>

Svelte

<script>
import LiveCodes from 'livecodes/svelte';

const options = {
  "template": "javascript"
};
</script>

<LiveCodes {...options} />

Solid

import LiveCodes from 'livecodes/solid';

export default function App() {
  const options = {
  "template": "javascript"
};
  return (<LiveCodes {...options} />);
}

Preact

import LiveCodes from 'livecodes/preact';

export default function App() {
  const options = {
  "template": "javascript"
};
  return (<LiveCodes {...options} />);
}

Web Components

<live-codes
  template="javascript"></live-codes>

<script type="module">
  import "livecodes/web-components";
</script>

The embedding web page can communicate with the playground using a powerful SDK (e.g. edit/format code, watch for code changes, get the compiled code or result page HTML, run tests, change layout, ...etc).

Create Embedded Playground

App Embed Screen

In the standalone app, the Embed Screen can be accessed from Project menu → Embed.

direct link

It shows a preview of the embedded playground, allows customizations of embed options and provides generated code that can be added to the web page that will embed the playground.

Note

Please note that the Embed Screen sends the project code to LiveCodes share service to generate a short URL for usage in the embed code.

The setting "Embed Type" allows selection from different variations of the generated code:

• Using the SDK from CDN.
• Using the SDK with a bundler (e.g. vite, parcel, webpack, etc).
• Using the React SDK.
• Using the Vue SDK.
• Using iframe and query params.
• Using HTML code that the SDK can use to auto-prefill the playground.

SDK

The LiveCodes SDK can be used to embed playgrounds and specify embed and configuration options. In addition, the SDK allows communication with the embedded playground with many SDK methods.

This method provides more control and allows advanced scenarios.

index.js

import { createPlayground } from 'livecodes';

createPlayground('#container', {
  // embed options
});

Embed via URL

LiveCodes playgrounds can be embedded in many websites and apps simply by pasting a LiveCodes link. This works on platforms that support oEmbed (e.g. Notion and many others).

To embed a playground in a supported platform, paste a LiveCodes URL (short share URL or a URL with query params). The platform will automatically resolve the embed.

Watch a video demo.

Medium

Medium supports embedding LiveCodes playgrounds by pasting a LiveCodes URL on its own line in the editor.

DEV

DEV supports embedding LiveCodes playgrounds using liquid tags:
{% embed https://livecodes.io/?x=id/zsrkkqxhw3i %}

WordPress

The official LiveCodes Embed plugin allows embedding playgrounds in WordPress, by pasting a LiveCodes URL on its own line in the Block editor or the classic editor. It also adds LiveCodes to the block inserter.

oEmbed

LiveCodes is registered on the oEmbed provider registry. Auto-discovery is also supported via <link> meta tags, so any platform that supports oEmbed discovery can automatically embed LiveCodes playgrounds.

Iframely

Iframely is a popular oEmbed proxy that many platforms use. LiveCodes is supported by Iframely out of the box.

Embedly

Embedly is a popular embed provider which supports embedding LiveCodes playgrounds.

Community Plugins

Obsidian

The Obsidian plugin Livecodes Playground (by gapmiss), allows embedding LiveCodes playgrounds in Obsidian.

Avoid Breaking Changes

To avoid breaking changes that would cause the embedded playgrounds to stop working as expected with later updates, follow these recommendations:

• Use a permanent URL to a pinned version of the LiveCodes app for EmbedOptions.appUrl. The code generated in the Embed screen uses that by default.
• Specify the version of the SDK used. The code generated in the Embed screen also does that.
• For project code, specify the versions of the imported packages and external resources. Custom import maps can be set to control the module import behavior.

Check the Permanent URL section for more details.

Self-Hosted Playgrounds

Self-hosted instances can be embedded using any of the following options:

• Using the SDK: Specify EmbedOptions.appUrl.
• Using oEmbed: The Docker setup provides an oEmbed service at /oembed.
• Using WordPress: The WordPress plugin allows embedding self-hosted instances. Example:

functions.php

add_filter( 'livecodes_embed_url_pattern', function () {
  return '!^https?://livecodes\.example\.com/.*$!i';
} );
add_filter( 'livecodes_embed_provider_endpoint', function () {
  return 'https://livecodes.example.com/oembed';
} );

Differences from Full App

Some of the features of the full standalone app are not available or shown by default in embedded playgrounds, either because of security reasons, being not useful when embedded or because of space limitations.

Features Not Available

• All features that require saving/loading from browser storage: e.g. projects, assets, code snippets, user settings, default template/language, recover unsaved, backup/restore.
• All features that require authentication: e.g. login/logout, sync, deploy, importing from private github repos.
• Broadcast.
• App menus.
• Some tools in tools pane: e.g. open result page in new window, broadcast status.
• Welcome screen.

Features Not Shown by Default

• External resources button (below the editor) and external resources screen are only shown if the loaded project has external resources (e.g. via EmbedOptions.config.stylesheets and EmbedOptions.config.scripts).
• Tests are not shown in tools pane unless the loaded project has tests (e.g. via EmbedOptions.config.tests). Test editor is not available.
• Loading starter templates can be achieved by the SDK (EmbedOptions.template), not from the UI.
• Importing from external sources can be achieved by the SDK (EmbedOptions.import), not from the UI.
• Getting a share URL can be achieved by the SDK (getShareUrl method), not from the UI.

Security

• All user code, result page and compilers run in sandboxed iframes with a unique origin.

• Embedded playgrounds do not have access to the parent page, or to sensitive data like user cookies and localstorage of the embedding page origin. Communications with the SDK occur by means of postMessage calls.

Related

• SDK
• Code prefill
• Configuration
• Embed options
• SDK methods
• Permanent URL
• Lite mode
• Read-only