Node.js playgrounds
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:
::: 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:
filesare what the container starts with. The URL of a folder of your public files puts all of it in, as it is, withoutnode_modulesand.git:src/public/tutorials/first-pagehere. 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.commandsrun one after the other, in the first terminal.cdchanges 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.openis 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.directoryis the folder that the explorer shows: by default, the one that the commands end in.previewis the page to show once something in the container listens on a port, such as/guide/index.html, orfalsefor no preview. Until then, the preview lists the commands and ticks them off as they run.titlenames the panel, andlogoputs 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: falseleaves out the explorer and the editor, for a terminal and a preview, andshell: falseleaves readers no shell after the commands.coepis theCross-Origin-Embedder-Policythat your pages are served with, if it'srequire-corprather thancredentialless.
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: credentiallesspostdoc run sends them when your configuration has them:
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.