Node.js playgrounds

Page content:

A playground runs Node.js in the reader's browser, in a WebContainer: a real Node.js, with npm, a shell and a file system, on the page. The panel around it is laid out like a window of VS Code, with the project's files in an explorer, an editor, terminals, and a preview of what the project serves. Readers follow a tutorial for your CLI, your library or your server by doing each step, with nothing installed. Try it in your browser runs Postdoc itself that way.

This one is a small web server. Press Run: Node.js starts in the page, runs npm start, and the preview shows what the server sends back. Change the heading in server.js, and Node.js restarts the server: the reload button of the preview shows the change.

It takes a few seconds the first time, and nothing is kept when you leave the page.

Writing a playground

A playground is a ::: playground container. Its settings go in a YAML block at the start, and the text after them is shown above the panel. A tutorial is usually a folder of files, the commands that serve them, and the file the reader should start in:

md
::: playground
```yaml
title: Your first page
files: /tutorials/first-page
commands:
  - npm install
  - npm run dev
open: src/index.md
preview: /index.html
```

Change the heading of `src/index.md`, and the preview follows.
:::

All the settings are optional:

  • files are what the container starts with. The URL of a folder of your public files puts all of it in, as it is, without node_modules and .git: src/public/tutorials/first-page here. A map from each path to { url }, a file of the site, or to { content }, text written in the settings, does it file by file, as in the server above.
  • commands run one after the other, in the first terminal. cd changes the folder for the commands after it. A command that doesn't end, such as a dev server, comes last, and readers open more terminals beside it.
  • open is a file, or a list of files, to open in the editor as soon as it exists. What readers type is written to the container as they type, so a dev server picks the change up.
  • directory is the folder that the explorer shows: by default, the one that the commands end in.
  • preview is the page to show once something in the container listens on a port, such as /guide/index.html, or false for no preview. Until then, the preview lists the commands and ticks them off as they run.
  • title names the panel, and logo puts a picture in its place in the title bar, such as your project's logo: logo: /assets/logo-light.svg. The title is then the picture's text alternative.
  • editor: false leaves out the explorer and the editor, for a terminal and a preview, and shell: false leaves readers no shell after the commands.
  • coep is the Cross-Origin-Embedder-Policy that your pages are served with, if it's require-corp rather than credentialless.

A page boots one container, which its playgrounds share, so each tutorial is best on a page of its own.

What readers can do

The explorer, the preview and the terminal can be dragged to size, and hidden and shown with the buttons in the title bar. Expand puts the panel over the whole page, and Back to the page, Escape or the browser's back button returns to it. The terminal panel holds as many terminals as readers open with +, listed on its right; the first one runs the commands, and can't be killed while it does.

The context menus are VS Code's, on the right button or Shift+F10. In the explorer, files and folders are made, renamed (F2) and deleted (Delete, ⌘⌫ on a Mac), with their names typed in place. Tabs are closed one, all or all others, and terminals are opened and killed, their text copied, pasted and cleared.

The keys are VS Code's too, with Cmd on a Mac and Ctrl elsewhere:

Keys What they do
Ctrl+P Find a file by its name
Ctrl+S Write the file now (it's written as you type anyway)
Ctrl+Alt+← and → The previous and the next tab
Ctrl+B, Ctrl+J, Ctrl+Shift+Y Show and hide the explorer, the terminal, the preview
Ctrl+`, Ctrl+Shift+` (Ctrl on a Mac too) Go to the terminal, open one more
Ctrl+Shift+E, Ctrl+1 Go to the explorer, to the editor
Escape Return to the page from the expanded panel

Ctrl+W is the one key the panel can't have: browsers keep it for closing their own tab. A file's tab closes with its ×, with Delete when the tab has the focus, or from its menu, and the browser asks before the page is left while a playground runs, so a Ctrl+W out of habit doesn't lose the container.

Colours

The panel comes in the colours of VS Code's dark theme. A site gives it its own with CSS custom properties on .playground-panel, which the editor and the terminal follow too, and which Python notebooks share on .notebook: --playground-background, --playground-editor-background, --playground-border, --playground-text, --playground-text-dim, --playground-hover, --playground-selected, --playground-accent, --playground-button, --playground-button-hover, --playground-button-text, --playground-input, --playground-selection, --playground-line-numbers, --playground-error, --playground-font, --playground-code-font, --playground-radius, --playground-height, and --playground-syntax-keyword, -string, -number, -comment, -function, -type, -variable, -tag and -attribute for the code. Colours are hex. This site's are in its postdoc/public/css/playground.css: the green of the editor on the home page.

Hosting

A WebContainer needs a page that the browser isolates, which takes two headers from the server:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless

postdoc run sends them when your configuration has them:

postdoc.config.jsjs
export default {
  vite: {
    server: {
      headers: {
        'Cross-Origin-Opener-Policy': 'same-origin',
        'Cross-Origin-Embedder-Policy': 'credentialless'
      }
    }
  }
};

Netlify, Vercel and Cloudflare Pages set headers from a file in your project: _headers on Netlify and Cloudflare, vercel.json on Vercel. GitHub Pages can't set them, so a playground doesn't run there.

A WebContainer runs JavaScript and WebAssembly. A package with a native program in it doesn't run unless it has a WebAssembly build as well, and there's no browser in it for tests that need one. The WebContainer API is free for personal and open-source use, and StackBlitz licenses it for commercial use.

Edit this page on GitHub