# codapi-js: turning documentation code blocks into runnable playgrounds

> codapi-js is the client side of Codapi, a system that converts static code examples in documentation into small playgrounds that readers can run and edit. Most snippets execute on a Codapi server, cloud hosted or self hosted, while JavaScript and Fetch run entirely in the browser.

**nalgeon/codapi-js** — Interactive code examples for documentation, education and fun.

- Repository: https://github.com/nalgeon/codapi-js
- Website: https://codapi.org
- Stars: 620 · Forks: 37
- Language: JavaScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/nalgeon-codapi-js

## Static examples become mini playgrounds

The idea is simple enough to describe in a sentence and awkward enough to need a server. Codapi takes the code examples you already have in your documentation and turns them into small interactive playgrounds, so a reader can run a snippet, edit it and see the result without leaving the page. The stated use cases are documentation, education and fun, and the project highlights that the examples are converted automatically, which is the part that matters: the code blocks in your Markdown or HTML do not have to be rewritten, they just have to be found. The client library you install is the widget that appears in the page, and the job of executing the code belongs to a Codapi server, either the cloud service at codapi.org or one you run yourself.

## Most playgrounds need a server, two do not

This is the detail that decides the deployment. Most playgrounds, the documentation gives Go and PostgreSQL as examples, run the code on the Codapi server, which means your readers are executing code on a machine that someone has to operate, secure and pay for. There are two exceptions, and they are exceptions by design rather than by accident: the JavaScript and Fetch playgrounds work completely in the browser with no Codapi server required. The repository structure shows how that is arranged, with separate engine entry points for PGlite and for a WASI based runner, each built into an IIFE and an ES module bundle, so the in-browser path is a different engine rather than a special case in the same one. If your documentation is about JavaScript or about fetching a URL, you can run the whole thing client side and skip the server question entirely.

## Installing the widget

The package is published under the `@antonz` scope, and installation is a normal npm operation:
```bash
npm install @antonz/codapi
```
If you would rather not build anything, the same files are on a CDN, and the documentation pins a specific version in the URL:
```html
<script src="https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.js"></script>
```
The stylesheet is optional, since the widget is unstyled by default and you are expected to bring your own look:
```html
<link rel="stylesheet" href="https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.css" />
```
The unstyled default is a deliberate choice, and it cuts both ways. A documentation site that already has a design system can match the widget to it without fighting the library's CSS, and a site with no styling at all gets a bare but functional control. The version in the URL is fixed at 0.20.0 in the example, which means the snippet script on the page does not move under you, and also that it will not pick up fixes without an edit.

## Output modes, templates and code cells

The project lists several features that go beyond a simple code playground, and each one changes what a reader can do. Output modes extend the result area to display images, HTML fragments and interactive DOM, which is what turns an example from a console transcript into something a front end developer can poke at. Templates hide parts of the code behind the scenes, so the visible snippet can be short while the executed code is complete, which is a good fit for a library example that needs a helper function the reader should not have to read. Multi-file playgrounds are supported for examples that need more than one file, custom actions let the surrounding page add its own buttons, and code cells give a notebook-like experience where the reader runs pieces separately. The practical question for an integrator is which of these the server you point at actually enables, since the client library is only half of the system.

## The widget structure you can style yourself

The documentation spells out the DOM the widget creates, and the shape is simple enough to target with your own CSS. The top level element is `codapi-snippet`, which carries the sandbox and editor attributes, and it contains a `codapi-toolbar` holding a Run button, one or more action links and a `codapi-status` bar, plus a `codapi-output` element that holds the result, normally a preformatted code block. The `sandbox` attribute is where the language goes, and the `editor` attribute selects the editing experience, with the documented example using a basic editor. Because the elements are custom elements with predictable names, a theme can restyle the toolbar and the output area without any configuration from the library, and the status bar is the natural place to hook a busy indicator, since it is the element that reports the state of a run.

## A one-person project, built with esbuild

The project describes itself as mostly a one-man project, not backed by a venture fund, and the repository reflects that. The build is a small Makefile that runs esbuild over a handful of entry points, producing both an IIFE bundle and an ES module for each of them, with a target of es2021 and the version string injected at build time through a define flag. The entry points are the snippet script, a settings script, and the two engine bundles for PGlite and the WASI runner, and the CSS is passed through the same build. The package publishes only the `dist` folder, has esbuild as its single development dependency, and carries a version of 0.20.1 in the manifest, one patch above the 0.20.0 release named in the release list, with the previous releases at 0.19.10 in December 2024 and 0.19.8 in August 2024. The last push was on 2026-08-21. On licensing, the manifest and the licence field for the repository both say MIT, while the highlight list in the documentation describes the project as using the permissive Apache-2.0 licence, so the LICENSE file is the one to read before you rely on either.

## Conclusion

codapi-js fits a documentation site whose examples are currently dead text, particularly a course or a product guide where readers would benefit from running a snippet without leaving the page, since adding the script and a sandbox attribute is most of the work. It is the wrong choice if you cannot run or reach a Codapi server, because only the JavaScript and Fetch playgrounds avoid that dependency, and it is the wrong choice if you want the examples to be authoritative, since a reader running arbitrary code against a shared server is a different proposition from a screenshot. Before deploying it, decide between the hosted service and your own instance of the server, check that the licence matches what you expect, since the package manifest and the licence field in the repository say MIT while the project description in the documentation mentions Apache-2.0, and pin the version of the script you load from a CDN, because the documented URLs carry a fixed version number that will otherwise age badly.

## FAQ

### How do I install codapi-js?

Install the npm package with npm install @antonz/codapi, or load the built script from a CDN with a script tag pointing at the dist/snippet.js file. A stylesheet is optional, since the widget is unstyled by default.

### Do I need to run my own Codapi server?

You need a working Codapi server, either the cloud service at codapi.org or a self-hosted instance, unless you use one of the in-browser playgrounds. The JavaScript and Fetch playgrounds work completely in the browser with no server required.

### Which documentation platforms have guides?

There are guides for HTML and Markdown, Docusaurus, Docsify, WordPress and Notion, plus Sphinx through a separate sphinxcontrib-coderun extension, and a guide for platforms such as Dev.to, Medium and Substack that do not allow JavaScript embeds, which uses code links instead.

### What can a Codapi example output?

Besides plain program output, the output modes cover images, HTML fragments and interactive DOM. Other documented features include templates that hide parts of the code, multi-file playgrounds, custom actions and code cells for a notebook-like experience.

### What licence is codapi-js released under?

The package manifest and the licence field for the repository both state MIT. The documentation describes the project as using the permissive Apache-2.0 licence, so the LICENSE file in the repository is the authoritative text to check.

## Sources

- [License: MIT](https://github.com/nalgeon/codapi-js/blob/main/LICENSE)
- [nalgeon/codapi-js on GitHub](https://github.com/nalgeon/codapi-js)
- [Project website](https://codapi.org)
- [README](https://github.com/nalgeon/codapi-js/blob/main/README.md)
- [Releases](https://github.com/nalgeon/codapi-js/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nalgeon-codapi-js