Overview

This project provides a quick, visual way to experiment with JavaScript code. It's designed to be loaded as an iframe for easy inclusion in any webpage.

There are a variety of configuration options, including a React preset and a React Native preset.

I use this sandbox in my free educational guides:

• JavaScript Express
• TypeScript Express
• React Express
• React Native Express

Usage

The sandbox may be included on your site in one of two ways:

• as a React component
• directly as an iframe

For legacy React Native-specific docs, see the v1 branch

As a React Component

If you're using React:

npm install --save javascript-playgrounds

# or

yarn add javascript-playgrounds

Then:

import Playground from 'javascript-playgrounds'

export default function App() {
  return <Playground style={{ width: 800, height: 500 }} />
}

This component is a wrapper around the iframe that handles encoding parameters for you. While it passes most props along to the iframe, it has a few extra props:

| Title | Description | Default | | --------------- | --------------------------------------------------------------------------------------------- | --------------------------------- | | style | The style of the div which wraps the iframe (the iframe has 100% width and height). | undefined | | className | The className of the div which wraps the iframe | undefined | | baseURL | Optionally, specify a custom url to load the player from. This url should not include a hash. | unpkg.com (see unpkg) |

As an iframe

If you're not using React, include the sandbox in an iframe.

<iframe
  width="880"
  height="425"
  frameborder="0"
  src="//unpkg.com/javascript-playgrounds@^1.0.0/public/index.html"
></iframe>

Configuration parameters should be passed as part of the hash string, after #data=. They should be JSON-encoded and then URI-encoded:

const parameters = { code: `console.log('Hello, world!')` }
const hashString = '#data=' + encodeURIComponent(JSON.stringify(parameters))

When used as an iframe, the easiest way to set the code parameter is to edit the code in the sandbox and copy and paste the url when you're done (the url updates automatically as you type).

For convenience, you may optionally pass the preset parameter in the url string directly, e.g. #preset=react&data=....

Parameters

The sandbox accepts the following props/parameters.

| Title | Description | Default | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | preset | This sets reasonable defaults for other parameters. Options are javascript, react, and react-native. Experimental options are html and python (make sure to lock down your javascript-playgrounds library version when using experimental presets). | 'javascript' | | title | An optional title for the editor pane. | '' | | code | The code to show/run in the player. | The sample app | | files | A map of { [filename]: code }. This will take precedence over code if given. | undefined | | entry | The filename of the file that runs first. This is only relevant when showing multiple files with the files parameter. Defaults to index.js, or index.tsx if TypeScript is enabled. | 'index.js' or 'index.tsx' | | initialTab | The filename of the tab to show by default. This is only relevant when showing multiple files with the files parameter. Defaults to the value of entry. | entry | | modules | An array of external modules to make available to the sandbox. Each object in the array should be an object containing a name and url. As a shorthand, pass a string name to load a module from unpkg (https://unpkg.com/${name}). More detail below. | [] | | registerBundledModules | Should the player share its bundled React, React DOM, and React Native implementations with the running app? Disable this if you plan to pass a react, react-dom or react-native module url. | true | | css | An optional CSS string to apply within the workspace iframe. | '' | | styles | An map of inline style objects, applied to various elements to customize the style of the UI. Example: { header: { backgroundColor: 'red' } } | {} | | strings | A map of strings that appear in the UI. Example: { loading: 'Loading dependencies...' } | {} | | sharedEnvironment | This affects how the iframes share data with one another, mainly for the "playgrounds" feature. When true, iframes will pass JavaScript objects back and forth, while when false, they'll pass serialized JSON. | false | | detectDependencies | Should the player scan code files for imports and try to fetch them from unpkg? Only modules imported in the initial code are fetched (not those added while typing in the sandbox). | true | | fullscreen | Show a button to enable fullscreen editing (in most configurations of panes). Note that the iframe must have the allowfullscreen attribute for this to work. | false | | compiler | Settings for Babel | {} | | compiler.maxLoopIterations | Throw an error if a loop iterates more than a certain amount of times. Set to 0 to disable. | 1000 | | playground | Settings for playgrounds (inline widgets that display runtime values) | {} | | playground.enabled | Turn on playgrounds? | false | | playground.renderReactElements | Render React elements? If false, will print the React element object, e.g. { type, props, key }, rather than render it. | true | | playground.debounceDuration | How frequently widgets update. A little delay helps keep the UI feeling smoother. | 200 (milliseconds) | | typescript | TypeScript settings | {} | | typescript.enabled | Turn on TypeScript hover tooltip info? Defaults to false | false | | typescript.libs | An array of default libraries to include, e.g. 'dom' and 'es2015'. We don't include some newer/esoteric ones by default, to reduce download size. | See source code | | typescript.types | An array of additional type files to download. Each should be an object { name, url }. | [] | | workspaces | Add a tutorial-like sequence of sets of files, highlighting changes between each set. Each object in this array can contain: { title, description, workspace: { title, files, entry, initialTab } }. Properties in the workspace object will override those given as top level parameters. | [] | | panes | An array of UI panes to display. To display a pane without options, use a string. Otherwise, use an object with a type property. The available panes are: 'stack', 'editor', 'transpiler', 'player', 'workspaces', 'console'. Note that there must be a player pane for any code to run. For pane options, see below. | ['editor', 'player'] | | responsivePaneSets | An array of { maxWidth, panes } objects to show at different responsive breakpoints. The iframe will use the first set where the maxWidth is greater than the current window width. The top-level panes parameter has maxWidth: Infinity so that it's used by default if there's no matching set of panes. | [] | | targetOrigin | If passed, the sandbox will call parent.postMessage(JSON.stringify(data), targetOrigin) on code changes. | undefined |

Examples of loading modules:

• To load a CommonJS require-style module, the name is the require(name) name, and the second is the source url. E.g. to load moment.js: set modules to the value [{ name: 'moment', url: 'https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.14.1/moment.min.js' }]
• To load a component as a property on window, also pass a globalName, which will be the window property name (e.g. window.moment). E.g. to load moment.js this way: set modules to the value [{ name: 'moment', globalName: 'moment', url: 'https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.14.1/moment.min.js' }]

Pane options

All panes support the following options:

| Title | Description | Default | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | | style | The inline styles for this specific pane, merged with those passed in the top-level styles object if given. | undefined | | title | An optional title for this pane. If used on an 'editor' pane, this will override a top-level title, if one was given. | '' |

Each pane additionally supports pane-specific options. For more detail:

• player
• console
• stack
• editor
• transpiler
• workspaces

The player pane

Display the running app, optionally with the image of a phone around it.

| Title | Description | Default | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | platform | One of ios, android, or web. When web, no phone image is displayed. | 'ios' | | width | The width of the device. This has no effect if the platform is web. | 210px | | scale | Zoom the device screen. This has no effect if the platform is web. | 1 | | assetRoot | Specifies the root url for asset requires. E.g. to require http://localhost:8080/images/hello.png, you could set assetRoot to 'http://localhost:8080/' and write require('./images/hello.png') in your code. | '' | | css | An optional CSS string to apply within the player's iframe. | '' | | styleSheet | One of reset or none. When reset, the meyerweb CSS reset is applied to the player's iframe. | 'reset' | | statusBarHeight | Display a rectangle at the top of the phone screen, mimicking a status bar. | 0px | | statusBarColor | The color of the fake status bar. | 'black' | | prelude | JavaScript code that runs before the entry file. | '' | | modules | Pane-specific modules, in addition to those passed at the top level. | [] | | console | Display an embedded console in this pane. See the console options below. Additionally, the embedded version of the console has the following properties... | {} | | console.visible | Show the console? | false | | console.maximized | Show the console over the entire player? | false | | console.collapsible | Allow collapsing the console via a toggle button. | true |

The console pane

Show the output console.log, similar to the Chrome inspector. This can be a separate pane, or embedded in the player pane.

| Title | Description | Default | | ------------------------- | ---------------------------------------------------------- | ------- | | showFileName | Show the file name containing the console.log. | false | | showLineNumber | Show the line number of the console.log. | true | | renderReactElements | Render React elements, instead of displaying element JSON. | false |

The stack pane

A nested stack of panes.

| Title | Description | Default | | -------------- | ------------------------------------------------------------- | ------- | | children | An array of panes, just like the top level panes parameter. | [] |

The editor pane

None at the moment.

The transpiler pane

None at the moment.

The workspaces pane

None at the moment.

Hosting

This project contains static assets that run standalone in the browser. You don't need a server, unless you want to host the assets yourself.

unpkg

The recommended host is https://unpkg.com, which is a CDN that serves content from the npm registry. The examples in this README all point to:

<iframe
  width="880"
  height="425"
  frameborder="0"
  src="//unpkg.com/javascript-playgrounds@^1.0.0/public/index.html"
></iframe>

Note that unpkg resolves semver versions in the url

Examples

These examples were created by loading the demo page and running roughly the following JS in the console:

location.href.slice(0, location.href.indexOf('#')) +
  '#data=' +
  encodeURIComponent(
    JSON.stringify({
      title: 'Custom title',
      panes: [
        'editor',
        { type: 'player', platform: 'android', modules: ['moment'] },
      ],
    })
  )

• React
• React Native
• Custom code
• Load external library via URL

Development

Run

yarn
yarn dev
# => localhost:8080

Build

yarn build

Contributing

Contributions are welcome, but if you're planning to add features, I recommend opening an issue describing the change first.

I maintain this project specifically for my educational guides, so if it's a feature I wouldn't use, I might not want to maintain it. It also may take me a little while to get to reviewing.

License

3-Clause BSD

https://opensource.org/licenses/BSD-3-Clause