* Add vendor script for quickjs-ng and update to v0.12.1 amalgam - Add scripts/vendor-quickjs-ng.sh to download release amalgam zip - Update vendor/quickjs-ng to v0.12.1 amalgamated build - Update Variant.mk to use quickjs-amalgam.o for quickjs-ng variants - Fix c/interface.c compatibility with quickjs-ng: - Remove cutils.h include (not in amalgam) - Add BOOL compatibility define (quickjs-ng uses C99 bool) - Add QTS_JS_IsBigInt macro (different signatures) Note: Some quickjs-ng tests are failing due to API differences in promise handling. This needs further investigation. * Fix quickjs-ng build and test failures - Add forward declaration for js_std_dump_error (needed for debug builds) - Add -DQJS_BUILD_LIBC to enable libc functions in quickjs-ng amalgam - Disable JS_DetectModule for quickjs-ng: it parses code as a module and returns true if parsing succeeds, but any valid JS expression is valid module syntax, so it incorrectly detects non-modules as modules - Regenerate variant Makefiles with the updated template All tests pass. * rebuild * Update vendor-quickjs-ng.sh to auto-fetch latest release When no version argument is provided, the script now queries the GitHub API to get the latest release tag and uses that version. * Simplify vendor:ng:pull to use vendor-quickjs-ng.sh Remove vendor:ng:subtree and vendor:ng:add scripts since we now vendor quickjs-ng from release amalgam instead of git subtree. * Link quickjs-ng docs to release tag instead of commit SHA Add CLibraryUsesTagVersion to indicate which libraries should link to their VERSION file as a release tag instead of using git subtree SHA. quickjs-ng now links to releases/tag/v0.12.1 instead of commit/SHA. * fix variant links for quickjs-ng --------- Co-authored-by: Hanzo Dev <[email protected]>
82 KiB
quickjs-emscripten-core
This package is part of quickjs-emscripten, a Javascript interface for QuickJS compiled to WebAssembly via Emscripten.
This package (quickjs-emscripten-core) contains only Javascript code - no WebAssembly. To use this package, you'll need to install one or more variants of the QuickJS WebAssembly build, see available variants below.
// 1. Import a QuickJS module constructor function from quickjs-emscripten-core
import { newQuickJSWASMModuleFromVariant } from "quickjs-emscripten-core"
// 2. Import a variant suitable for your use case. For example, if you only care to
// target with the fastest execution speed, import the release build variant
import releaseVariant from "@jitl/quickjs-singlefile-cjs-release-sync"
// 3. Create the "QuickJS" module that presents the quickjs-emscripten API.
// Export and use in other files, or consume directly.
const QuickJS = await newQuickJSWASMModuleFromVariant(releaseVariant)
What's a variant?
A variant describes how to load a QuickJS WebAssembly build and how to call the low-level C API functions used by the higher-level abstractions in quickjs-emscripten-core. A variant is an object with the following properties:
const variant = {
// This should be `async` if the variant is built with ASYNCIFY
// so that the WebAssembly module execution can be suspended.
//
// Otherwise, this should be `sync`.
type: "sync",
// This should be a function that resolves to a QuickJSFFI class.
importFFI: () => import("something/ffi.ts").then((mod) => mod.QuickJSFFI),
// This should be a function that resolves to a Emscripten-shaped WASM module factory.
importModuleLoader: () => import("something/emscripten-module.ts"),
}
You can provide your own variant to control exactly how the large WebAssembly object is loaded. quickjs-emscripten-core will call your variant's importXYZ methods during newQuickJSWASMModuleFromVariant or newQuickJSAsyncWASMModuleFromVariant.
Environment-specific variants
You can use subpath imports in package.json to select the appropriate variant for a runtime. This is how the main quickjs-emscripten package picks between browser, Node ESM and Node CommonJS variants.
// in your package.json
{
"imports": {
"#my-quickjs-variant": {
"types": "@jitl/quickjs-wasmfile-release-sync",
// In the browser, use the singlefile variant that doesn't need an external file
"browser": "@jitl/quickjs-singlefile-browser-release-sync",
// Otherwise, use the wasmfile variant, compatible with all environments
"default": "@jitl/quickjs-wasmfile-release-sync"
}
}
}
// In your code
import { newQuickJSWASMModuleFromVariant } from "quickjs-emscripten-core"
import variant from "#my-quickjs-variant"
const QuickJS = await newQuickJSWASMModuleFromVariant(variant)
Available variants
@jitl/quickjs-wasmfile-debug-sync
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-wasmfile-debug-asyncify
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-wasmfile-release-sync
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-wasmfile-release-asyncify
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-ng-wasmfile-debug-sync
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs-ng | quickjs-ng is a fork of quickjs that tends to add features more quickly. Version v0.12.1 vendored to quickjs-emscripten. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-ng-wasmfile-debug-asyncify
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs-ng | quickjs-ng is a fork of quickjs that tends to add features more quickly. Version v0.12.1 vendored to quickjs-emscripten. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-ng-wasmfile-release-sync
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs-ng | quickjs-ng is a fork of quickjs that tends to add features more quickly. Version v0.12.1 vendored to quickjs-emscripten. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-ng-wasmfile-release-asyncify
Docs | Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs-ng | quickjs-ng is a fork of quickjs that tends to add features more quickly. Version v0.12.1 vendored to quickjs-emscripten. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | wasm | Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant. |
| exports | require import browser workerd | Has these package.json export conditions |
@jitl/quickjs-singlefile-cjs-debug-sync
Docs | Variant with the WASM data embedded into a universal (Node and Browser compatible) CommonJS module.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | require | Has these package.json export conditions |
@jitl/quickjs-singlefile-cjs-debug-asyncify
Docs | Variant with the WASM data embedded into a universal (Node and Browser compatible) CommonJS module.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | require | Has these package.json export conditions |
@jitl/quickjs-singlefile-cjs-release-sync
Docs | Variant with the WASM data embedded into a universal (Node and Browser compatible) CommonJS module.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | require | Has these package.json export conditions |
@jitl/quickjs-singlefile-cjs-release-asyncify
Docs | Variant with the WASM data embedded into a universal (Node and Browser compatible) CommonJS module.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | require | Has these package.json export conditions |
@jitl/quickjs-singlefile-mjs-debug-sync
Docs | Variant with the WASM data embedded into a NodeJS ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | import | Has these package.json export conditions |
@jitl/quickjs-singlefile-mjs-debug-asyncify
Docs | Variant with the WASM data embedded into a NodeJS ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | import | Has these package.json export conditions |
@jitl/quickjs-singlefile-mjs-release-sync
Docs | Variant with the WASM data embedded into a NodeJS ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | import | Has these package.json export conditions |
@jitl/quickjs-singlefile-mjs-release-asyncify
Docs | Variant with the WASM data embedded into a NodeJS ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | import | Has these package.json export conditions |
@jitl/quickjs-singlefile-browser-debug-sync
Docs | Variant with the WASM data embedded into a browser ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | browser | Has these package.json export conditions |
@jitl/quickjs-singlefile-browser-debug-asyncify
Docs | Variant with the WASM data embedded into a browser ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | debug | Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | browser | Has these package.json export conditions |
@jitl/quickjs-singlefile-browser-release-sync
Docs | Variant with the WASM data embedded into a browser ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | browser | Has these package.json export conditions |
@jitl/quickjs-singlefile-browser-release-asyncify
Docs | Variant with the WASM data embedded into a browser ESModule.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | asyncify | Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs. |
| emscriptenInclusion | singlefile | The WASM runtime is included directly in the JS file. Use if you run into issues with missing .wasm files when building or deploying your app. |
| exports | browser | Has these package.json export conditions |
@jitl/quickjs-asmjs-mjs-release-sync
Docs | Compiled to pure Javascript, no WebAssembly required.
| Variable | Setting | Description |
|---|---|---|
| library | quickjs | The original bellard/quickjs library. Version 2025-09-13+f1139494 vendored to quickjs-emscripten on 2026-02-15. |
| releaseMode | release | Optimized for performance; use when building/deploying your application. |
| syncMode | sync | The default, normal build. Note that both variants support regular async functions. |
| emscriptenInclusion | asmjs | The C library code is compiled to Javascript, no WebAssembly used. Sometimes called "asmjs". This is the slowest possible option, and is intended for constrained environments that do not support WebAssembly, like quickjs-for-quickjs. |
| exports | import | Has these package.json export conditions |