Skip to main content
Get QuickJS-ng running on your system and execute your first JavaScript code.

​
Installation

1

Install QuickJS-ng

Choose your preferred installation method:
git clone https://github.com/quickjs-ng/quickjs.git
cd quickjs
make
2

Verify Installation

Check that QuickJS is installed correctly:
qjs --version
You should see output like:
QuickJS version 2024.01.13+ng

​
Your First Script

1

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);
2

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.
1

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;
2

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
3

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:
1

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;
}
2

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

Make sure the QuickJS binaries are in your PATH:
export PATH=$PATH:/path/to/quickjs
Or install to a system directory:
sudo make install
When importing modules, use relative paths starting with ./ or ../:
// Correct
import { foo } from './module.js';

// Incorrect (won't work)
import { foo } from 'module.js';
If you encounter build errors on macOS, ensure you have Command Line Tools installed:
xcode-select --install

Build docs developers (and LLMs) love

Get started for freeTalk to us