Skip to main content

JavaScript/TypeScript SDK

This is the core SDK on which others (React & Vue SDKs) are build on top. It is a lightweight library (less than 3kb gzipped) that allows creating, embedding and communication with LiveCodes playgrounds.

Installation​

Please refer to the SDK installation section.

info

In the full standalone app, the JavaScript SDK is accessible via the global variable livecodes, which can be interacted with in the browser console.

TypeScript Types​

TypeScript types are documented here and can be imported from the library.

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

createPlayground​

Type: (container: string | Element, options?: EmbedOptions) => Promise<Playground>

The library exports the function createPlayground which takes 2 arguments:

  • container (required): HTMLElement or a string representing a CSS selector.
  • options (optional): an object with embed options (EmbedOptions).

The createPlayground function return a promise which resolves to an object that exposes the SDK methods (Playground).

import { createPlayground, EmbedOptions } from 'livecodes';

const options: EmbedOptions = {
  // appUrl: ...
  // config: ...
  // import: ...
  // lite: ...
  // loading: ...
  // params: ...
  // template: ...
  // view: ...
};

createPlayground('#container', options).then((playground) => {
  // `playground` object exposes the SDK methods
  // e.g. playground.run()
});

Embed Options​

Type: EmbedOptions

The secong argument of the createPlayground function is an optional object with the following optional properties:

appUrl​

Type: string

Default: "https://livecodes.io/"

Allows the library to load the playground from a custom URL (e.g. hosted app).

config​

Type: string | Partial<Config>

Default: {}

A configuration object or a URL to a JSON file representing a configuration object to load.

import​

Type: string

A URL to import.

lite​

Type: boolean

Default: false

If true, the playground is loaded in lite mode.

loading​

Type: "eager" | "lazy" | "click"

Default: "lazy"

"eager": The playground loads immediately.

"lazy": A playground embedded low down in the page will not load until the user scrolls so that it approaches the viewport.

"click": The playground does not load automatically. Instead, a "Click-to-load" screen is shown.

params​

Type: UrlQueryParams

An object that represents URL Query parameters.

These 2 snippets produce similar output:

import { createPlayground } from 'livecodes';

// use config
createPlayground('#container1', {
  config: {
    markup: {
      language: 'markdown',
      content: '# Hello World!',
    },
  },
});

// use params
createPlayground('#container2', { params: { md: '# Hello World!' } });

template​

Type: TemplateName

A starter template to load.

view​

Type: "editor" | "result" | "split"

Default: "split"

The default view for the playground.

SDK Methods​

Type: (Playground)

load​

Type: () => Promise<void>

When the embed option loading is set to click, the playground is not loaded automatically. Instead, a screen is shown with "Click to load" button. Calling the SDK method load() allows loading the playground.

If the playground was not loaded, calling any other method will load the playground first before executing.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  await playground.load();
  // playground loaded
});

run​

Type: () => Promise<void>

Runs the result page (after any required compilation for code).

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  await playground.run();
  // new result page is displayed
});

format​

Type: (allEditors?: boolean) => Promise<void>

Formats the code.

By default, the code in all editors (markup, style and script) is formatted. If you wish to format only the active editor, pass the value false as an argument.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  await playground.format();
  // code in editors is formatted
});

getShareUrl​

Type: (shortUrl?: boolean) => Promise<string>

Gets a share url.

By default, the url is has a long query string representing the compressed config object. If the argument shortUrl was set to true, a short url is generated.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  const longUrl = await playground.getShareUrl();
  const shortUrl = await playground.getShareUrl(true);
});

getConfig​

Type: (contentOnly?: boolean) => Promise<Config>

Gets a config object representing the playground state. This can be used to restore state if passed as embed option property on creating playground, or can be manipulated and loaded in run-time using setConfig method.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  const config = await playground.getConfig();
});

setConfig​

Type: (config: Partial<Config>) => Promise<Config>

Loads a new project using the passed configuration object.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  const config = {
    markup: {
      language: 'html',
      content: 'Hello World!',
    },
  };
  const newConfig = await playground.setConfig(config);
  // new project loaded
});

getCode​

Type: () => Promise<Code>

Gets the playground code (including source code, source language and compiled code) for each editor (markup, style, script), in addition to result page HTML.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  const code = await playground.getCode();

  // source code, language and compiled code are available
  const { content, language, compiled } = code.script;

  // result page HTML
  const result = code.result;
});

show​

Type: (panel: EditorId | Lowercase<Tool['title']> | 'result', options?: { full?: boolean; line?: number; column?: number; zoom?: 1 | 0.5 | 0.25 }) => Promise<void>

Shows the selected panel, which is either:

  • Editor: markup, style or script
  • Tool: console, compiled or tests
  • Result page: result

The second optional argument is an object:

  • It may have the boolean property full, which If true, selected editor or result page will take the full vertical and horizontal space of the playground, while tools will take the full vertical and half the horizontal space, leaving some space for the active editor.

  • The optional properties line and column allow scrolling to line/column number in the shown editor.

  • The optional property zoom sets the result page zoom level (the selected panel must be result).

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  const delay = (duration) =>
    new Promise((resolve) => {
      setTimeout(resolve, duration);
    });

  await playground.show('style');
  await delay(2000);
  await playground.show('result', { full: true });
  await delay(2000);
  await playground.show('script');
  await delay(2000);
  await playground.show('result', { zoom: 0.5 });
  await delay(2000);
  await playground.show('console', { full: true });
});

runTests​

Type: () => Promise<{ results: TestResult[] }>

Runs project tests (if present) and gets test results.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  const { results } = await playground.runTests();
});

onChange​

Type: (fn: ChangeHandler) => { remove: () => void }

Allows to watch the playground for changes. It takes a callback function that will be called on every change.

The callback function will be called with an object that has 2 properties: code and config, representing the current codes and configuration objects (see getCode and getConfig).

The onChange method returns an object with a single method remove, which when called will remove the callback from watching changes.

import { createPlayground } from 'livecodes';

createPlayground('#container').then((playground) => {
  const watcher = playground.onChange(({ code, config }) => {
    // this will run on every code change
    console.log('code:', code);
    console.log('config:', config);
  });

  // then later
  watcher.remove();
  // changes are no longer watched
});

exec​

Type: (command: APICommands, ...args: any[]) => Promise<{ output: any } | { error: string }>

Execute custom commands, including:

// in browser console of full app (e.g. https://livecodes.io)
await livecodes.exec('setBroadcastToken', 'my-token');
  • "showVersion": Logs current LiveCodes version and commitSHA in the browser console.
// in browser console of full app (e.g. https://livecodes.io)
await livecodes.exec('showVersion');

destroy​

Type: () => Promise<void>

Destoys the playground instance, and removes event listeners. Further call to any SDK methods throws an error.

import { createPlayground } from 'livecodes';

createPlayground('#container').then(async (playground) => {
  await playground.destroy();
  // playground destroyed
  // any further SDK call throws an error
});

Styles​

Default Styles​

By default, the container element is styled when the SDK is initialized (including width, height, border, etc.). To disable default styles, set the container element attribute data-default-styles to "false" before initializing.

Example:

<div id="container" data-default-styles="false" class="custom"></div>
<script type="module">
  import { createPlayground } from 'livecodes';
  createPlayground('#container');
</script>

Height​

By default, the playground container height is set to "300px". To change the height, either disable the default styles and override them, or simply set the data-height attribute to a number (in pixels) or any valid CSS value (e.g. "100%" to take the full height of its parent element).

Example:

<div id="container" data-height="500"></div>
<script type="module">
  import { createPlayground } from 'livecodes';
  createPlayground('#container');
</script>
Sponsors