txiki.js — The tiny JavaScript runtime

Overview

txikia (basque): small, tiny.

txiki.js is a small and powerful JavaScript runtime. It targets state-of-the-art ECMAScript and aims to be WinterCG compliant.

It's built on the shoulders of giants: it uses QuickJS-ng as its JavaScript engine and libuv as the platform layer.

See it in action here:

Getting started

First head over to building and build the runtime.

$ ./build/tjs eval "console.log('hello world')"
hello world
$

If you want to run a script you can use tjs run:

$ ./build/tjs run examples/hello_world.js
hello world
$

Explore all the options:

$ ./build/tjs --help

For TS support see @txikijs/types.

Features

Support for the ES2023 specification (almost complete).

WinterCG

txiki.js aims to be WinterCG compliant, you can track the progress here.

Web Platform APIs

• alert, confirm, prompt (1)
• Console
• Crypto (2)
• Encoding API
• EventTarget
• fetch
• JSON modules
• Performance
• setTimeout, setInterval
• Storage API
• Streams API
• URL
• URLPattern
• URLSearchParams
• WebAssembly (3)
• WebSocket
• Web Workers API

(1): All of them are async.

(2): No subtle support.

(3): No tables, globals or memory support.

Runtime features

• Standalone executables
• TCP and UDP sockets
• Unix sockets / named pipes
• Signal handling
• File operations
• Child processes
• WASI
• ...

See the full API documentation.

Other extras:

• Import directly from HTTP(S) URLs
• Import JSON files
• Builtin test runner

Standard library

The following modules compose the standard library:

• tjs:assert
• tjs:ffi
• tjs:getopts
• tjs:hashing
• tjs:ipaddr
• tjs:path
• tjs:sqlite
• tjs:uuid
• tjs:wasi

Supported platforms

• GNU/Linux
• macOS
• Windows (beta)
• Other Unixes (please test!)

Building

CMake is necessary.

NOTE: The txiki.js build depends on a number of git submodules (libffi, libuv and WAMR). If you didn't already clone this repository recursively, make sure you initialize these submodules with git submodule update --init before proceeding to the build.

GNU/Linux

Install dependencies (libcurl, build-essential, cmake, autoreconf, libtool, libltdl-dev):

# On Debian / Ubuntu
sudo apt install libcurl4-openssl-dev build-essential cmake autoconf texinfo libtool libltdl-dev

macOS

Install dependencies (cmake, autoconf):

brew install cmake autoconf automake libtool texinfo

Unix systems

# Get the code
git clone --recursive https://github.com/saghul/txiki.js --shallow-submodules && cd txiki.js
# Compile it!
make
# Run the REPL
./build/tjs

Windows

Building requires Visual Studio 2022 (or the Build Tools) and vcpkg.

Prerequisites

1. Install Visual Studio 2022 with the "Desktop development with C++" workload, or install the Build Tools for Visual Studio 2022.

2. Install and bootstrap vcpkg:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

3. Install the required dependencies:

.\vcpkg install curl[ssl] libffi

Build

Run these commands from a "Developer PowerShell for VS 2022" or "x64 Native Tools Command Prompt":

cmake -B build -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DUSE_EXTERNAL_FFI=ON
cmake --build build --config Release

The executable will be at build\Release\tjs.exe.

Running the tests

.\build\Release\tjs.exe test tests/

Customizing the build

If you are making a custom build and are modifying any of the JS files that are part of the runtime, you'll need to regenerate the C code for them, so your changes become part of the build.

# First install the JS dependencies
npm install
# Now bundle the code and compile it into C source files
make js

tjs compile - creating standalone executables

Creating standalone executables is possible with tjs compile. The resulting executable will bundle the given code and the txiki.js runtime. No compiler is needed.

NOTE: The resulting executable will have the same runtime dependencies as the tjs executable.

Assuming a bundle.js file with some JS code, the following command will create a standalone executable with it:

tjs compile bundle.js

The new executable will be called bundle on Unix platforms and bundle.exe on Windows. The output name can be customized by passing a second option:

tjs compile bundle.js myexe

The tjs compile command doesn't do any code bundling. If you need to bundle your app into a single JS file for use with tjs compile, esbuild can be a good option. Here is how to bundle an app into a single bundle.js file:

npx esbuild my-app/index.js \
    --bundle \
    --outfile=bundle.js \
    --external:tjs:* \
    --minify \
    --target=es2023 \
    --platform=neutral \
    --format=esm \
    --main-fields=main,module

Versioning

txiki.js uses calendar versioning with the form YY.MM.MICRO.

Built with ❤️ by saghul and these awesome contributors.