R2D2: Replete's mascot Replete

What is it?

A tool that lets you run JavaScript directly from your text editor. You select some code, then press a keyboard shortcut to run it. Anything from the merest expression to a whole module may be evaluated at a time.

Replete can evaluate JavaScript in many environments:

It integrates with several text editors:

It supports JavaScript's module syntax (ESM). It does not support CommonJS (and never will).

It is free and open source.

Why is it useful?

Being able to easily run code in isolation helps with application development, casual scripting, and learning about the language.

Traditionally, JavaScript code is only ever executed as part of an application or test suite. Buried deep within an application, code is difficult to exercise and debug. Bugs are a natural consequence of such code because it is not well understood.

Replete makes it possible to reach into a codebase and begin interacting with its code immediately. Removing the execution barrier shortens the feedback loop, improves understanding of the code, and encourages experimentation. Code written in this way tends to have fewer bugs and is more fun to work with.

Replete is designed for everyday use by JavaScripters of all kinds. It is suitable for writing code for the browser, for the server, or both. Running the same code in multiple browsers and runtimes is trivial with Replete, making it easier to produce portable code.

Constant vigilance

Do you know what 0/0 evaluates to? How about new Date().getYear()? Nobody can be expected to remember every booby trap in JavaScript, or the idiosyncrasies of the many environments in which our code is expected to run. When in doubt, ask the runtime. Many hazards can be avoided by evaluating dubious code fragments before baking them into your application.

Whole modules

Evaluating a fragment of code is all well and good, but things really start cooking when you evaluate an entire file at once. A conventional JavaScript module does nothing useful when evaluated in this way, but a whole module gives a demonstration of its own correctness. This makes it possible to test without leaving the file you are working in (or even saving it to disk!)

Consider the following whole module, double.js.

function double(x) {
    return 2 * x;
}
if (import.meta.main) {
    if (double(3) !== 6) {
        throw new Error("FAIL");
    }
}
export default double;

The code within the outer if clause is the demo. Here the demo is a unit test that fails by throwing an exception, but it could be anything.

Replete evaluates import.meta.main as true, so the test will run during evaluation. Likewise, running double.js from the command line with deno run double.js will also run the test, with the exit code of the process indicating success or failure.

When double.js is imported, however, import.meta.main will be false or undefined, so the test will not run. For optimal performance, demos should be removed from production code prior to minification. This can be handled by a capable bundler or collapse.js.

Web server

Replete runs a local web server, whose primary purpose is to serve up modules when import statements are evaluated in the browser. In addition to modules, however, it can serve other kinds of files such as stylesheets, fonts, images, and HTML documents.

Consider how an image might be added to the page:

const img = document.createElement("img");
img.src = import.meta.resolve("./background.svg");
document.body.append(img);

Notice how import.meta.resolve is used to resolve the image's URL relative to the current module. The same idea can be applied to stylesheets, fonts, and other web assets. By leveraging web standards in this way, sophisticated web applications can be developed using only a text editor and Replete. Such web applications can often be deployed to a static file server without a build step.

By default, Replete listens only on localhost. However, specifying --browser_hostname=0.0.0.0 opens Replete up to the local network, making it possible to evaluate code on and serve files to mobile browsers.

Other languages

Languages that transpile to JavaScript, such as Microsoft's TypeScript, are also supported. It just takes some extra configuration.

How do I use it?

There is a Playground where you can try Replete without installing anything. It contains a basic tutorial and many examples, as well as a fun surprise.

The easiest way to get Replete running in your text editor is to first install Deno, then install a text editor plugin (video). At this point you should be able to begin evaluating code in the browser and Deno (video).

To evaluate code in other runtimes, such as Node.js, you will first need to configure the plugin by supplying --which_node=node or similar. Basic configuration options are listed here and expanded upon here.

If you do not wish to install Deno, Replete also runs on Node.js and Bun. This requires that the Replete repository be cloned locally and the plugin be configured appropriately.

Who made this?

My name is James Diacono and I'm a full-time Web programmer. You can:

The source code for Replete lives at github.com/jamesdiacono/Replete.