avril

a v8 runtime i like

<small>(aka: apostate v8 runtime for infrastructure lesbians)</small>

software you can love. the world's number 1 (alphabetically) typescript-first runtime

avril is heavily, heavily inspired by Deno. it's a love letter, really. i'll miss Deno so much

avril as a web citizen

i love the open web. avril is for web-centric infrastructure: i will use it for my static-site generator; i will write web application backends in it; i will use it as a comptime runtime for javascript code which ends up on the web.

avril's package management is open-web-first: you can add an https:// URL to your avril.conf deps, and you're good to go. this nets us decentralized package management, patched dependencies as easy as swapping out the URL, and inspectable self-contained scripts.

unlike Deno, avril's https dependencies can be full packages, with their own contextual import map: in my opinion the biggest benefit of jsr-first packaging in Deno 2.0 is shaking free from the ergonomic headache that is _deps.ts, but this costs you a centralized package repository. of course, avril supports importing code from jsr: and npm: specifiers, too, but https is just as good!

as table stakes, avril is ECMA-429 compliant. this is the Minimum common web API, defining everything a runtime-agnostic piece of JavaScript can safely expect in its environment. this means avril is compatible with all reasonably-agnostic code! :D

avril also additionally implements the Web Storage API (for sessionStorage and persistent localStorage), WebSockets (both outgoing and incoming!), and Web Workers.

avril as a sandbox

avril supports running in -0 ("zero-by-default") mode, which opts out of all capabilities (akin to Deno's security model). you may then pass --allow-{net,read,write,run,…}=<scope> to build up capabilities required for doing your useful application work. unlike Deno, you pass multiple --allow flags to allow multiple resources of the same category - this solves e.g. allowing read access to a directory whose name contains a comma

without -0, you can also pass --deny-* flags to do denylist-based capabilities, which may be convenient in some situations. because of Deno's lack of convenience, everyone just uses -A anyway, so this is a sort of remedy.

avril also supports pledge(..) in avril:std, an API for reducing the exposed capability surface area after initialization: this lets you, for example, read a secrets file and then deny future reads, or listen on a port and then deny further networking.

avril's Web Workers implementation allows you to define the worker's capabilities (via [avril]: { caps: { ... } } in WorkerOptions, provided you import { avril } from "avril:std".)

avril as modern infrastructure

i'm so lucky to have such a better Rust+ECMAScript ecosystem around me than Deno did in 2018/2019 ^-^

• we use rusty_v8, as Cloudflare pledge to continue rusty_v8
• we use cap-std for capability-based security "all the way down"
• we use the Oxc family of projects for analyzing and transpiling TypeScript
• we use redb for localStorage and avril:kv

usage

compiling the runtime

you will need:

• latest stable rust (via rustup is good)
• a C compiler toolchain
• curl (to fetch prebuilt V8 binaries)
  • OR a python3 + C++ build tools (gn, ninja, clang) for building v8 via V8_FROM_SOURCE=1
  • see rusty_v8 <3

you can build the runtime like so:

cargo build --release --locked -p avril-cli --bin avril
./target/release/avril --help

you can also use cargo install --locked --path cli --bin avril to install to cargo's binary dir

tests

cargo nextest run --workspace
cargo test --workspace --doc # run doctests

tests requiring the native TypeScript backend (lsp, check) will be skipped unless the AVRIL_TEST_TYPESCRIPT environment var is defined

setting up VS Code

build the patched TypeScript compiler from the avril repository root, with Go on PATH:

typescript_src=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/microsoft/TypeScript.git "$typescript_src"
git -C "$typescript_src" checkout --detach b5c34ba0c61a756c8abaf133236dddf982c27f45
bash lib/lsp/typescript/build.sh "$typescript_src" "/absolute/path/to/avril-tsc"

package the extension (Node.js 22.13+, npm, pnpm 11.27.0, VS Code 1.90+):

cd editors/vscode
pnpm install --frozen-lockfile --prod=false --ignore-scripts
pnpm run package
code --install-extension avril.vsix --force

in your user settings, set the actual absolute paths:

{
  "avril.lsp.executable": "/absolute/path/to/avril",
  "avril.lsp.backend": "/absolute/path/to/avril-tsc"
}

keep VS Code's built-in TypeScript extension enabled. the avril language server should auto start if there's an avril.conf in your workspace root.

docs

• config format
• friendly JSON

there are also several more ai generated docs (sorry) in the docs directory.