Creating Native C Modules

QuickJS supports native ES6 modules written in C that can be dynamically or statically linked. This allows you to expose C functionality to JavaScript while maintaining the ES6 module interface.

Module Structure

Every native module must export a js_init_module function that QuickJS calls when loading the module:

JS_MODULE_EXTERN JSModuleDef *js_init_module(JSContext *ctx, const char *module_name);

The JS_MODULE_EXTERN macro ensures proper symbol visibility on Windows and other platforms.

Simple Function Module

Here’s a complete example from examples/fib.c that exports a Fibonacci function:

Signatures:

JS_EXTERN JSModuleDef *JS_NewCModule(JSContext *ctx, const char *name_str,
                                     JSModuleInitFunc *func);
JS_EXTERN int JS_AddModuleExportList(JSContext *ctx, JSModuleDef *m,
                                      const JSCFunctionListEntry *tab, int len);
JS_EXTERN int JS_SetModuleExportList(JSContext *ctx, JSModuleDef *m,
                                      const JSCFunctionListEntry *tab, int len);

Module with Classes

The examples/point.c example demonstrates creating a module with a custom class:

Signatures for class API:

JS_EXTERN JSClassID JS_NewClassID(JSRuntime *rt, JSClassID *pclass_id);
JS_EXTERN int JS_NewClass(JSRuntime *rt, JSClassID class_id, const JSClassDef *class_def);
JS_EXTERN void JS_SetClassProto(JSContext *ctx, JSClassID class_id, JSValue obj);
JS_EXTERN int JS_SetOpaque(JSValueConst obj, void *opaque);
JS_EXTERN void *JS_GetOpaque2(JSContext *ctx, JSValueConst obj, JSClassID class_id);

Building Modules

Dynamic Module (Shared Library)

Using CMake (from CMakeLists.txt):

add_library(fib MODULE examples/fib.c)
set_target_properties(fib PROPERTIES PREFIX "")
target_link_libraries(fib PRIVATE qjs_module_lib)

if(APPLE)
    target_link_options(fib PRIVATE -undefined dynamic_lookup)
endif()

Using gcc/clang directly:

# Linux
gcc -shared -fPIC -o fib.so fib.c -I/path/to/quickjs

# macOS
gcc -dynamiclib -undefined dynamic_lookup -o fib.so fib.c -I/path/to/quickjs

# Windows (MinGW)
gcc -shared -o fib.dll fib.c -I/path/to/quickjs -lqjs

On Windows, you must define QUICKJS_NG_MODULE_BUILD and link against the QuickJS library.

Static Linking

Compile the module source with your application:

gcc -o myapp myapp.c fib.c -lqjs -lm -lpthread

extern JSModuleDef *js_init_module_fib(JSContext *ctx, const char *name);

// In your initialization code:
js_init_module_fib(ctx, "fib");

Using Modules in JavaScript

Dynamic Module

import { fib } from './fib.so';

console.log(fib(10)); // 55

Class Module

import { Point } from './point.so';

const p = new Point(3, 4);
console.log(p.x);      // 3
console.log(p.y);      // 4
console.log(p.norm()); // 5

p.x = 5;
p.y = 12;
console.log(p.norm()); // 13

Function List Entry Macros

QuickJS provides convenient macros for defining exports:

// Simple function
JS_CFUNC_DEF("name", argc, c_func)

// Function with magic number
JS_CFUNC_MAGIC_DEF("name", argc, c_func, magic)

// Getter/setter
JS_CGETSET_DEF("prop", getter, setter)
JS_CGETSET_MAGIC_DEF("prop", getter, setter, magic)

// Constants
JS_PROP_INT32_DEF("NAME", value, flags)
JS_PROP_DOUBLE_DEF("PI", 3.14159, JS_PROP_CONFIGURABLE)
JS_PROP_STRING_DEF("VERSION", "1.0.0", JS_PROP_CONFIGURABLE)

Advanced: GC Mark Function

If your opaque data contains JSValue references, provide a GC mark function:

typedef struct {
    JSValue callback;
    void *user_data;
} MyData;

static void js_mydata_gc_mark(JSRuntime *rt, JSValueConst val,
                              JS_MarkFunc *mark_func)
{
    MyData *data = JS_GetOpaque(val, js_mydata_class_id);
    if (data) {
        JS_MarkValue(rt, data->callback, mark_func);
    }
}

static JSClassDef js_mydata_class = {
    "MyData",
    .finalizer = js_mydata_finalizer,
    .gc_mark = js_mydata_gc_mark,
};

Signature:

typedef void JSClassGCMark(JSRuntime *rt, JSValueConst val,
                           JS_MarkFunc *mark_func);

Next Steps

Memory Management - Understand memory allocation in modules
Performance - Optimize native module performance
Embedding - Integrate modules with embedded runtime

Overview

Core Concepts

CLI Tools

Standard Library

Advanced Topics

Platform Support

Creating Native C Modules

Creating Native C Modules

Module Structure

Simple Function Module

Module with Classes

Building Modules

Dynamic Module (Shared Library)

Static Linking

Using Modules in JavaScript

Dynamic Module

Class Module

Function List Entry Macros

Advanced: GC Mark Function

Next Steps

​Creating Native C Modules

​Module Structure

​Simple Function Module

​Module with Classes

​Building Modules

​Dynamic Module (Shared Library)

​Static Linking

​Using Modules in JavaScript

​Dynamic Module

​Class Module

​Function List Entry Macros

​Advanced: GC Mark Function

​Next Steps

Creating Native C Modules

Module Structure

Simple Function Module

Module with Classes

Building Modules

Dynamic Module (Shared Library)

Static Linking

Using Modules in JavaScript

Dynamic Module

Class Module

Function List Entry Macros

Advanced: GC Mark Function

Next Steps