Dustin Boston

QuickJS is a tiny JavaScript engine written in C. Its author, Fabrice Bellard, created FFMPEG and QEMU. QuickJS can run outside of traditional browser environments. This includes packaging JavaScript applications for distribution.

As of writing, QuickJS supports ECMAScript 2023, so you can write modern JavaScript. It is also fast and well-tested.

One of the engine’s features is compiling JavaScript code into bytecode. Bytecode is a compact set of instructions that an interpreter can execute. It makes execution more efficient, which is perfect where performance is important. Additionally, the engine supports compilation of JavaScript into dependency-free standalone executables. We will use this feature to package JavaScript apps.

QuickJS’s small footprint is also suitable for embedded systems and resource-constrained environments.

Recently, Amazon announced its Low Latency Runtime (LLRT), built on QuickJS. According to Amazon, LLRT starts 10x faster and is 2x less expensive than other JS runtimes on AWS Lambda. That’s a pretty impressive use case.

Installation

Installing QuickJS in your development environment is straightforward. Here’s how to get started. Note that on Windows, you can use WSL with Linux.

Before jumping in, make sure you have Make and a C compiler like GCC or Clang.

The first step is to get a copy of the source code. You can download the source from the QuickJS website or by cloning it from the GitHub repository. We’ll download it from the website and untar the file:

wget https://bellard.org/quickjs/quickjs-2024-01-13.tar.xz
tar -xJf quickjs-2024-01-13.tar.xz

This command creates the directory quickjs-2024-01-13 with all the necessary source files. I’ll refer to this directory as quickjs from now on.

Compatibility

QuickJS does not rely on V8, WebKit, or Gecko. It is not compatible with NodeJS or Deno APIs. It does have access to the OS through its own APIs. To make sure your code is compatible with QuickJS, ensure the following:

• Your code uses ECMAScript 2023 or lower
• You are not using browser-specific APIs
• You are not using Node.js or Deno-specific APIs

QuickJS focuses on the core JavaScript language, so your code should be platform-agnostic.

Organization

For this simple Hello World app we’re putting our files into the quickjs directory. In a business context, you should keep your code separate from QuickJS. Otherwise, you can structure your project as you would any other JavaScript project. You can even use modules.

Building QuickJS

Once you have the source code, the next step is to compile it. This will convert the code into an executable you can run on your computer. Navigate to the quickjs directory with cd quickjs.

Finally, compile the source with the make command. QuickJS’s Makefile will detect your OS and choose the appropriate compiler and flags. Run:

make

On macOS, Make will use Clang as the default compiler, whereas on Linux, GCC is more common. Compilation will take a few moments. Once completed, several new files will be added to the quickjs directory. qjs is the command-line tool for executing JavaScript files. qjsc is a tool for compiling JavaScript into bytecode.

Testing QuickJS

You can run a simple JavaScript file to verify your installation. Create a file named hello.js with the following code:

console.log("Hello, QuickJS!");

Save the file into the quickjs directory and then execute it using the qjs binary:

./qjs hello.js

If QuickJS installed, you will see the message “Hello, QuickJS!” Now you have QuickJS set up and ready, it’s time to package an application.

Packaging JavaScript

To create a standalone executable, use the qjsc executable in the quickjs directory. You can execute it with these commands:

qjsc -o hello hello.js
./hello

If it works, you will see “Hello, QuickJS!” on your terminal. This is the file that we will distribute.

There are many flags that you can pass to qjsc. Try experimenting with each. For example, output bytecode instead of an executable. Or disable regular expressions to decrease binary size.

Package Size

The executable for this “Hello, World!” example is 4.6 MB. It may seem large for such a simple program. However, consider the alternatives. Using deno compile I get an executable that is 76 MB. Compiling the hello.js file using Node 21 produces a 98 MB file. So, In perspective 4.6 MB seems pretty good.

Distribution

You don’t need anything special to distribute a QuickJS-packaged application. Using the standalone executables, you have a range of distribution options.

QuickJS is portable. That means that it can run in many environments. When preparing for distribution, consider the target platforms. If you want your application to work on Windows, macOS, and Linux, you must build the app on each system.

Closing Thoughts

Whether you’re developing IoT devices or building server-side tools QuickJS is a stellar option. It’s easy to use, fast, and produces relatively tiny executables.

Try experimenting with it, push its boundaries, and see how it can be used in your projects. What has your experience with QuickJS been? I’d love to hear your stories, successes, and lessons learned.