Writing policies in TypeScript/JavaScript

note

TypeScript/JavaScript support for WebAssembly is rapidly evolving. This page was last revised in September 2025.

As stated on the official website:

TypeScript extends JavaScript by adding types.

By understanding JavaScript, TypeScript saves you time catching errors and providing fixes before you run code.

Kubewarden uses Javy (a Bytecode Alliance project) to build WebAssembly binaries from JavaScript and TypeScript.

Javy takes your JavaScript code and executes it in a WebAssembly context.

It features an embedded QuickJS engine compiled to WebAssembly that can execute JavaScript.

The project provides both a CLI and a set of APIs for embedding and customizing the behavior when running JavaScript in WebAssembly.

The Kubewarden project currently uses Javy for these reasons:

• Mature JavaScript engine (QuickJS) compiled to WebAssembly.
• Support for WASI interface through custom host functions.
• Smaller binary sizes compared to other JavaScript-to-WebAssembly solutions.
• Active development and maintenance by the Bytecode Alliance.

Javy limitations

Javy runs JavaScript in a sandboxed WebAssembly environment with certain constraints:

• WASI environment only: Access limited to stdin/stdout/stderr and explicitly provided host capabilities.
• No Node.js APIs: Standard Node.js modules like fs, http, or crypto aren't available.
• Limited standard library: Only core JavaScript features and explicitly enabled APIs are accessible.
• Single-threaded execution: No support for Web Workers or multi-threading.
• STDOUT restrictions: Writing to STDOUT breaks policies - use STDERR for logging instead.

Despite these limitations, Javy provides sufficient capabilities for writing effective Kubewarden validation policies through the hosts capabilities system.

Tooling

Writing Kubewarden policies requires:

• Node.js: Version 18 or higher.
• npm: For dependency management.
• TypeScript: Recommended for type safety (optional).

warning

Ensure you're using Node.js 18 or higher. Older versions may not be compatible with the compilation toolchain.

These TypeScript/JavaScript libraries are useful when writing a Kubewarden policy:

• Kubewarden JavaScript SDK: Provides structures and functions reducing the amount of code necessary. It also provides test helpers and access to all host capabilities.
• Kubernetes TypeScript types: Provides TypeScript definitions for all Kubernetes resources, enabling type-safe policy development.

The Kubewarden project provides a template JavaScript/TypeScript policy project you can use to create Kubewarden policies.

Getting the toolchain

The easiest way to get the complete toolchain is by using the Kubewarden JavaScript SDK, which includes the Javy compilation plug-in:

npm install kubewarden-policy-sdk

The Javy plug-in binary is automatically included and you can find it at:

node_modules/kubewarden-policy-sdk/plugin/javy-plugin-kubewarden.wasm

Tutorial prerequisites

During this tutorial you need these tools on your development machine:

• Node.js: Version 18 or higher with npm for dependency management.
• bats: Used to write the tests and automate their execution.
• kwctl: CLI tool provided by Kubewarden to run its policies outside of Kubernetes, among other actions. It's covered in the testing policies section of the documentation.