code-run: a browser playground that compiles your CSS and TypeScript for you

A pure front end project, so the compilers have to run in the browser

The single most important architectural fact about this project is stated in the compiler update section: because the project is a pure front end application, preprocessor languages such as less, sass and typescript have to be compiled online, and that work is done by the compiler for each language. Those compilers live in a parsers directory under the public folder, and the documentation is candid about the maintenance consequence, saying they will fall behind their upstream versions over time and that getting a browser usable build of each one is not easy. The compiler update guide gives a recipe per language. For less, install the package and take the two UMD builds from its dist directory. For TypeScript, install the package and use the typescript.js file from the lib directory, which also works directly in a browser. CoffeeScript is the same pattern, with the browser compiler in a package directory. Babel points at the official standalone build, and postcss is expected to be bundled with Browserify or webpack into a single file. The sass entry names a specific third party project and notes it has not been updated in three years, and the LiveScript entry says its browser build has not been updated in two years.

The stack is Vue CLI, Vue 3, element-plus and Monaco

The main technologies section names four choices. The scaffold is Vue CLI, the framework is the Vue 3 stack used through script setup with the composition API, the UI library is element-plus, and the code editor is Monaco Editor. The package manifest confirms each of those and shows the shape of the result. The name is @wanglin1994/code-run at version 0.2.8, and the dependencies include vue at 3.3.4, vue-router and vuex, element-plus at a 1.1.0 beta, monaco-editor at 0.29.1, monaco-editor-textmate and monaco-textmate with onigasm for the TextMate grammar support that gives the editor its syntax highlighting, and vscode-theme-to-monaco-theme-web for the theme conversion. Two dependencies have an obvious purpose in the feature list, jszip and fflate for the zip export, and html2canvas for the code image generation that is described as producing output comparable to carbon. @octokit/core is there for the GitHub gist saving, and cropperjs, dayjs, loadjs, nprogress and eventemitter3 round out the list.

ES modules work by rewriting the import to an unpkg URL

The ES module support is the cleverest part of the project and it is worth understanding, because the mechanism is unusual. In the JavaScript, TypeScript, CoffeeScript, Vue 3 and Vue 2 modes, an ordinary import such as this is transformed before it reaches the preview.

import moment from 'moment'

It becomes a URL import through unpkg.

import moment from 'https://unpkg.com/moment?module'

The documentation explains why that is not always good enough. Some modules have no ES module build on unpkg, and sometimes the version unpkg returns is not the one you want. The example given is vue, where the runtime ESM bundler build that unpkg returns by default cannot run in a browser, while a specific browser ESM build is needed. The fix is to add an import map by hand to point the module at the source you want, and the project links to the import maps proposal for that. So the import rewriting is a convenience layer over unpkg, and the import map is the escape hatch when the layer guesses wrong.

VS Code themes migrate through a generated JSON file and two npm scripts

The theme system is a migration pipeline rather than a hand written set of Monaco themes, and the tutorial for it is one of the more concrete parts of the documentation. The process starts in your own editor. You install and activate the theme locally in VS Code, open the command palette with F1 or the Command or Control plus Shift plus P shortcut, and run the Developer: Generate Color Theme From Current Setting command, which makes VS Code produce a JSON file. You save that file into the project's vscodeThemes directory under scripts. Then you run the convertTheme command, which converts the VS Code theme file into a Monaco Editor theme file, and the result is written to the themes directory under public. A third command, createThemeList, generates the theme configuration from the list of theme files, and after that the themes appear in the settings panel where they can be switched. The feature list also says a large number of quality themes are already built in, so the pipeline is for adding more, and the same documentation notes that a large set of themes is included out of the box.

Layouts are Vue components, so adding one means writing a Vue file

The layout system is the most extensible part of the project, and it is built on a Drag and DragItem component pair. A layout is a single file component, and every layout decides how the editor, the console and the preview are shown, with the editor area containing js, css, html and vue editors whose visibility, order and draggability you can configure. The tutorial shows how a new layout gets registered. You create the component in the layouts directory, then edit the constants file, importing the component and adding an entry to both the layoutList and the layoutMap configuration objects, and the entry carries a name and a value that becomes the key in the map. The Drag component takes a number of items, a direction that is h for horizontal or v for vertical, and a config array giving the default and minimum size of each item, and the DragItem component takes an index, a disabled flag, a touch bar flag and a title. The documented Vue example wires a single vue editor on the left with the preview and console stacked on the right, and the preview expanded by default with the console minimised.

Sharing works three ways, including without any account

Three sharing paths are documented and they differ in what they require. With a GitHub account configured, the tool can save to a gist through the gist API, and the documentation says that changing that to save into your own storage system is simple. Without a gist configured, the tool can still save the changes into the URL, which the documentation says makes it convenient to share the link with someone else. Third, the export produces a zip file, so the whole thing can be downloaded and taken away. The embed mode is the fourth feature worth naming, and it exists so the tool can be dropped into a documentation site, which the documentation says makes document examples easier. Combined with the code image generation that mimics carbon, the intent is a set of small tools for sharing runnable fragments rather than a serious development environment.

Building it, and the two configuration values you will want to change

Getting the project running locally is four commands.

git clone https://github.com/wanglin2/code-run.git
cd code-run
npm i
npm run serve

The production build is a single script.

npm run build

The build section also names the two settings that decide where the finished application lives, and the defaults are worth changing before you deploy anything. The base path defaults to a code-run sub path, and to change it you edit the publicPath field in the vue.config.js file and the base field in the configuration file under src/config. The router mode defaults to hash mode, and switching to history mode means editing the routerMode field in that same configuration file, and the documentation adds that in history mode, if there are nested paths, you may also need to fix the path to the prettier JavaScript resource in the public index.html file. The npm scripts also show the other build steps, including one that compiles the console file to ES5 into a file that must not be edited by hand, one that repacks the Monaco Editor worker and has to be rerun when the editor version changes, and one that packs the Vue single file component compiler for Vue 3.

Editorial conclusion

code-run fits a team that wants a self hosted scratchpad for sharing runnable snippets, a demo for a library, or an embedded example in documentation, since the embed mode and the URL sharing without a GitHub account cover exactly those cases. It does not fit a project that needs a build pipeline for its own source, because the compilers run in the visitor's browser and are frozen at whatever version was committed, and it does not fit a team that expects a maintained Sass or LiveScript toolchain, since the bundled compilers are years behind. Before you deploy it, change the default base path and router mode in the configuration rather than shipping it under the default route, decide whether you want the browser compilers at all or whether you will precompile, and check that the versions of the compiler files in the parsers directory still match what your examples import.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. wanglin2/code-run on GitHub