Quickstart

Get QuickJS-ng running on your system and execute your first JavaScript code.

Installation

Install QuickJS-ng

Choose your preferred installation method:

From Source
Pre-built Binaries
Using jsvu

git clone https://github.com/quickjs-ng/quickjs.git
cd quickjs
make

npm install -g jsvu
jsvu --engines=quickjs

Verify Installation

Check that QuickJS is installed correctly:

qjs --version

You should see output like:

QuickJS version 2024.01.13+ng

Your First Script

Create a JavaScript file

Create a file called hello.js:

hello.js

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

// QuickJS supports modern JavaScript
const greet = (name) => `Hello, ${name}!`;
console.log(greet("World"));

// ES2023+ features
const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2);
console.log(doubled);

Run the script

Execute your script with the qjs command:

qjs hello.js

Output:

Hello from QuickJS!
Hello, World!
[ 2, 4, 6, 8, 10 ]

Interactive REPL

QuickJS includes an interactive Read-Eval-Print Loop (REPL) for experimenting with JavaScript:

qjs

Try some expressions in the REPL:

> 2 + 2
4
> Math.sqrt(144)
12
> [1, 2, 3].map(x => x * x)
[ 1, 4, 9 ]
> const obj = { name: "QuickJS", version: 2024 }
undefined
> obj.name
QuickJS
> .exit  // Exit the REPL

Press Ctrl+D or type .exit to exit the REPL.

Using Modules

QuickJS supports ES6 modules out of the box.

Create a module

Create math.js:

math.js

export function add(a, b) {
    return a + b;
}

export function multiply(a, b) {
    return a * b;
}

export const PI = 3.14159;

Import and use the module

Create app.js:

app.js

import { add, multiply, PI } from './math.js';

console.log(add(5, 3));        // 8
console.log(multiply(4, 7));   // 28
console.log(PI);                // 3.14159

Run as a module

qjs --module app.js

Output:

8
28
3.14159

QuickJS automatically detects modules when you use import or export syntax, so the --module flag is optional in most cases.

Embedding QuickJS in C

QuickJS is designed to be embedded in C/C++ applications. Here’s a minimal example:

Create a C file

Create embed.c:

embed.c

#include <quickjs.h>
#include <stdio.h>
#include <string.h>

int main(int argc, char **argv) {
    JSRuntime *rt = JS_NewRuntime();
    JSContext *ctx = JS_NewContext(rt);
    
    const char *code = "console.log('Hello from embedded QuickJS!'); 2 + 2";
    JSValue result = JS_Eval(ctx, code, strlen(code), "<input>", JS_EVAL_TYPE_GLOBAL);
    
    if (JS_IsException(result)) {
        JSValue exception = JS_GetException(ctx);
        const char *str = JS_ToCString(ctx, exception);
        fprintf(stderr, "Error: %s\\n", str);
        JS_FreeCString(ctx, str);
        JS_FreeValue(ctx, exception);
    } else {
        int32_t val;
        JS_ToInt32(ctx, &val, result);
        printf("Result: %d\\n", val);
    }
    
    JS_FreeValue(ctx, result);
    JS_FreeContext(ctx);
    JS_FreeRuntime(rt);
    
    return 0;
}

Compile and run

# Make sure you're in the QuickJS source directory
gcc embed.c -o embed -I. -L. -lquickjs -lm -lpthread
./embed

Output:

Hello from embedded QuickJS!
Result: 4

For simpler embedding, use qjs -c to create standalone executables. See Standalone Executables.

Using the Standard Library

QuickJS includes optional standard library modules for file I/O and system operations:

import * as std from 'qjs:std';
import * as os from 'qjs:os';

// File operations
const content = std.loadFile('data.txt');
console.log(content);

// Current directory
const [cwd, err] = os.getcwd();
console.log('Current directory:', cwd);

// Environment variables
console.log('HOME:', std.getenv('HOME'));

Run with the --std flag to enable these modules:

qjs --std script.js

The standard library modules are not loaded by default to keep the engine lightweight. Use --std when you need file I/O or OS features.

Next Steps

Core Concepts

Learn about runtimes, contexts, and memory management

API Reference

Explore the complete C API documentation

CLI Tools

Master the qjs and qjsc command-line tools

Examples

See practical examples and tutorials

Common Issues

Command not found: qjs

Make sure the QuickJS binaries are in your PATH:

export PATH=$PATH:/path/to/quickjs

Or install to a system directory:

sudo make install

Module not found errors

When importing modules, use relative paths starting with ./ or ../:

// Correct
import { foo } from './module.js';

// Incorrect (won't work)
import { foo } from 'module.js';

Compilation errors on macOS

If you encounter build errors on macOS, ensure you have Command Line Tools installed:

xcode-select --install

Overview

Core Concepts

CLI Tools

Standard Library

Advanced Topics

Platform Support

Installation

Your First Script

Interactive REPL

Using Modules

Embedding QuickJS in C

Using the Standard Library

Next Steps

Core Concepts

API Reference

CLI Tools

Examples

Common Issues

​Installation

​Your First Script

​Interactive REPL

​Using Modules

​Embedding QuickJS in C

​Using the Standard Library

​Next Steps

Core Concepts

API Reference

CLI Tools

Examples

​Common Issues

Installation

Your First Script

Interactive REPL

Using Modules

Embedding QuickJS in C

Using the Standard Library

Next Steps

Common Issues