Skip to content

Home

Jump to bottom
Walter Perdan edited this page Jun 4, 2026 · 18 revisions

Welcome to the jsartoolkitNFT wiki!

Build instructions

You need to build the library if you make changes to the C++ core (emscripten folder) or the TypeScript API (src folder). Before building, you need to clone the repository and fetch the submodules.

Clone the repository

  1. Clone this repository: 
    git clone https://github.com/webarkit/jsartoolkitNFT.git
cd jsartoolkitNFT
  2. Initialize and update the WebARKitLib submodule: 
    git submodule update --init
    If you already cloned WebARKitLib to a different directory, you can either:
    • Create a symlink in the emscripten/ directory pointing to WebARKitLib (emscripten/WebARKitLib) (Linux and macOS only).
    • Set the WEBARKITLIB_ROOT environment variable to point to your WebARKitLib clone.
    • Modify the WEBARKITLIB_ROOT path in tools/makem.js to point to your clone.

Build the project

There are three ways to build the project:

1. Build using Dev Containers (Recommended for VS Code users)

If you use Visual Studio Code, you can build and develop inside a pre-configured Docker container automatically.

  1. Ensure Docker Desktop is installed and running.
  2. Install the VS Code Dev Containers extension.
  3. Open the repository in Visual Studio Code.
  4. When prompted, click Reopen in Container (or open the Command Palette Ctrl+Shift+P / Cmd+Shift+P and choose Dev Containers: Reopen in Container).
  5. VS Code will build the Docker container and configure all dependencies (EMSDK, CMake, Ninja, Node.js).
  6. Once open, run the following in the integrated terminal: 
    npm run build

2. Build using Manual Docker Scripts

If you prefer running Docker manually from the command line, you can use the built-in cross-platform helper scripts:

  1. Start the background Docker container: 
    npm run setup-docker
    (This starts a persistent background container named emscripten-jsartoolkitnft and automatically resolves the host workspace path, working seamlessly on Windows, macOS, and Linux).
  2. Compile the build files inside the container: 
    npm run build-docker
    (Or run npm run build-docker-no-libar if you want to skip rebuilding libar.o).
  3. Stop and clean up the container (when you are done): 
    docker stop emscripten-jsartoolkitnft
docker rm emscripten-jsartoolkitnft

3. Build Natively on Host (Windows, macOS, Linux)

You can compile natively on your host machine if you have the proper tools configured.

Prerequisites:
  • Node.js (v18+)
  • Emscripten SDK (v4.0.17+) available in your PATH (e.g. source <path-to-emsdk>/emsdk_env.sh).
  • CMake (v3.5+) and Ninja (recommended, especially on Windows: choco install ninja or winget install MSBuild.Ninja).
Building:
  1. Run npm install to install dependencies.
  2. Run the build command: 
    npm run build
    (Or run npm run build-no-libar if you don't need to rebuild libar.o).
  3. To rebuild the TypeScript/ES6 distributions, run: 
    npm run build-ts

During development, you can run npm run watch. It will watch the ./js/ directory and rebuild the library automatically whenever you change API or worker files.

Build Artifacts

All build outputs are saved to the /build and /dist directories:

  • /build/artoolkitNFT.debug.js (debug build with symbols)
  • /build/artoolkitNFT.min.js (optimized build)
  • /build/artoolkitNFT_wasm.js (WebAssembly build)
  • /dist/ARToolkitNFT.js (compiled UMD distribution)

Clone this wiki locally