Interactive JavaScript Sandbox

Common errors

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

  cause Attempting to use `Playground` component without a correct import in a React application.
  fix Ensure `import Playground from 'javascript-playgrounds'` is used, as `Playground` is a default export.

• Sandbox content not loading or displaying 'Page Not Found' in iframe.

  cause Incorrect `src` URL for the iframe, especially if modifying `unpkg.com` or using a custom `baseURL`.
  fix Verify the `src` URL points to the correct `index.html` file within the `public` directory of the `javascript-playgrounds` package, e.g., `//unpkg.com/javascript-playgrounds@^1.0.0/public/index.html`.

• Parameters passed to iframe are not reflected in the sandbox (e.g., initial code or preset not applied).

  cause Configuration parameters in the `iframe` `src` are not correctly JSON-encoded and then URI-encoded, or the `#data=` prefix is missing/malformed.
  fix Double-check the encoding: `const encoded = encodeURIComponent(JSON.stringify({ code: 'console.log("Hello");' })); const src = `//unpkg.com/.../index.html#data=${encoded}`;`

Warnings

• breaking Older versions (v1.x) had specific documentation and behavior tailored for React Native. The current main branch (v2+) has refactored aspects, and users specifically targeting legacy React Native integrations should refer to the `v1` branch.
  Fix: For legacy React Native projects, consider staying on `javascript-playgrounds@1.x` or carefully review the `v1` branch documentation for migration if upgrading is necessary. New projects should follow current `v2+` documentation.
• gotcha When using the sandbox directly via an `iframe`, all configuration parameters must be JSON-encoded and then URI-encoded before being appended to the URL hash. Incorrect encoding will lead to parameters not being parsed correctly by the sandbox.
  Fix: Ensure parameters are correctly encoded: `const hashString = '#data=' + encodeURIComponent(JSON.stringify(parameters))`.
• gotcha The `baseURL` prop/parameter defaults to `unpkg.com` for loading the sandbox assets. If your application has strict Content Security Policy (CSP) rules or you require self-hosting for reliability/offline support, you must configure a custom `baseURL`.
  Fix: Set the `baseURL` prop on the React component or the `src` of the `iframe` to your custom hosted path: `<Playground baseURL="https://my-cdn.com/playgrounds" />` or `src="https://my-cdn.com/playgrounds/public/index.html#data="`.
• gotcha The `style` and `className` props on the React `<Playground>` component apply to the wrapping `div`, not directly to the `iframe` itself. The `iframe` inside the wrapper will take `100%` width and height of this wrapping `div`.
  Fix: Apply dimensions and other styles to the wrapping `div` via the `style` or `className` prop. If direct `iframe` styling is needed, consider using the raw `iframe` method or CSS selectors targeting the `iframe` within the component.

Install

• npm install javascript-playgrounds npm
• yarn add javascript-playgrounds yarn
• pnpm add javascript-playgrounds pnpm

Imports

• Playground
  wrong:

  const Playground = require('javascript-playgrounds')

  correct:

  import Playground from 'javascript-playgrounds'

  The primary way to use this library as a React component. The package ships ESM and CJS; prefer ESM imports in modern applications.
• JSX usage

  <Playground style={{ width: 800, height: 500 }} />

  When using the Playground component in a React application, it acts as a wrapper for an iframe, handling parameter encoding automatically. Style and className props apply to the wrapping div.
• Iframe direct usage

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

  For non-React environments, embed directly as an iframe. Configuration parameters must be manually URI-encoded JSON in the hash. The example shows a base iframe without parameters.

Quickstart

This quickstart demonstrates embedding the `Playground` React component with initial code and a React preset.

import Playground from 'javascript-playgrounds';
import React from 'react';

// This component provides an interactive JavaScript sandbox.
// It defaults to a basic JavaScript environment.
// To configure with specific code or presets, pass props.
export default function App() {
  // Example: Setting initial code
  const initialCode = `
const message = 'Hello from the sandbox!';
console.log(message);

function greet(name) {
  return 'Hello, ' + name + '!';
}

console.log(greet('World'));
`;

  return (
    <div style={{ padding: '20px' }}>
      <h1>My Interactive Sandbox</h1>
      <Playground
        style={{ width: '100%', height: '600px', border: '1px solid #ddd' }}
        code={initialCode}
        preset="react" // Example: use the React preset
        // You can also specify a custom base URL if needed, e.g.,
        // baseURL="https://my-cdn.com/javascript-playgrounds"
      />
      <p>Experiment with JavaScript, React, or other presets directly in this embedded editor.</p>
    </div>
  );
}