Bynk

Bynk is a statically typed, architecture-first programming language for building services. The shape of a program — its contexts, services, agents, and the types that flow between them — is part of the language, not a convention layered on top. Bynk compiles to typed TypeScript and targets Cloudflare Workers.

⚠️ Bynk is pre-1.0 and under active development. The language evolves in small, spec-first increments. The Bynk Book documents what compiles today; planned features are marked as planned.

The idea in one example

context greet

service api from http {
  on GET("/ping") () -> Effect[HttpResult[String]] by v: Visitor {
    Ok("pong")
  }
}

Compiling this with bynkc produces TypeScript you can read, run, and deploy — the router, boundary validation, and the Worker entry point are generated for you.

What makes Bynk distinct

• Make illegal states unrepresentable. Refined types (types carrying a predicate), opaque types, and errors-as-values (Result, Ok/Some/ None) let whole classes of bug go unexpressed.
• Architecture in the language. Contexts, services, and stateful agents are first-class, and a context is the unit of deployment — it becomes one Cloudflare Worker.
• Honest effects and capabilities. Dependencies are declared in signatures (given Logger), supplied by the platform, and mockable in tests.
• Compiles to TypeScript. You get JavaScript-ecosystem interop and a natural fit for Cloudflare Workers, with a static type system in front of it.
• Testing is built in. suite/case blocks, expect, and Val[T] value fabrication ship with the language.

Install

Prebuilt binaries (bynkc, bynk and the bynkc-lsp language server) are published with every release for Linux (x86_64, aarch64), macOS (Intel, Apple silicon) and Windows (x86_64). No Rust toolchain is needed.

macOS and Linux:

curl -fsSL https://github.com/bynk-lang/bynk/releases/latest/download/install.sh | sh

Windows (PowerShell):

irm https://github.com/bynk-lang/bynk/releases/latest/download/install.ps1 | iex

The installer verifies the download against the release's SHA256SUMS, puts the binaries in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\bynk\bin) and tells you if that directory is not on your PATH. Pin a release with curl -fsSL …/install.sh | BYNK_VERSION=v0.434.0 sh (the variable goes on sh, not curl), or choose the directory with BYNK_INSTALL_DIR. The Linux binaries need a recent glibc; on musl (Alpine) use cargo. Then run bynk doctor.

If you already have Rust (stable, 2024 edition — see rustup):

cargo binstall bynkc bynk bynk-lsp   # prebuilt, via cargo-binstall
cargo install bynkc bynk bynk-lsp    # or compile from crates.io

To build from source (main moves on with every merged increment; check out a vX.Y.Z tag for a release):

git clone https://github.com/bynk-lang/bynk.git
cd bynk
cargo install --path bynkc
cargo install --path bynk
cargo install --path bynk-lsp   # optional: the language server

Before 1.0, a release is cut when a track of work retires (release discipline).

bynkc --help lists the four compiler commands (compile, check, fmt, test); bynk --help lists the driver's (doctor, dev, deploy, new, check, fmt, test, explain, mcp).

To let an AI agent ask the toolchain about Bynk (diagnostics, symbols, documentation, architecture, wire contracts), point its MCP client at bynk mcp, for example claude mcp add bynk -- bynk mcp. Set-up for other clients is in the bynk mcp page.

Quick start

Scaffold a complete, runnable project and serve it — three commands from nothing to a running service on http://localhost:8787:

bynk new hello       # scaffold bynk.toml + src/hello.bynk
cd hello
bynk dev             # compile and serve it locally

bynk new only writes files (no toolchain needed), and bynk dev serves what it wrote unmodified. Prefer a worked example? The bundled examples/hello-world is a complete project you can also bynkc check src, bynkc test ., and deploy.

See Start a new project or Compile your first program.

Repository layout

This is a Cargo workspace. The three user-facing tools — bynkc, bynk, and bynk-lsp — are front-ends over a layered set of library crates; every crate except bynk-wasm, bynk-testkit, tree-sitter-bynk's Rust binding, xtask, and fuzz is published to crates.io at each release. Each crate's README says where it sits in the layering.

Path	What it is	Published as
bynkc/	The bynkc compiler CLI (compile / check / fmt / test) — a thin front-end over the library crates.	crates.io
bynk/	The bynk driver — links the compiler in-process and orchestrates the Node toolchain (doctor / new / dev / deploy, plus check / fmt / test / explain).	crates.io
bynk-lsp/	The bynkc-lsp Language Server (diagnostics, hover, go-to-definition, …).	crates.io
bynk-syntax/, bynk-std/, bynk-project/, bynk-check/, bynk-ir/, , , , , , , ,

The VS Code extension lives in its own repository, bynk-lang/vscode-bynk; the playground does too.

Developing

Run the CI gates locally before you push — CI's critical path is the Windows test leg at roughly seven minutes, so a formatting slip caught here saves a full round trip:

cargo xtask ci          # formatting, clippy, and the test suite
cargo xtask ci --fast   # just the two gates that need no compile-and-link

--fast is what the opt-in pre-push hook runs. Enable it once per clone:

git config core.hooksPath .githooks

Note that --fast is not compile-free: clippy skips codegen and linking, not compilation. It is about three seconds on a warm cache, roughly a minute once every crate's fingerprint has changed, and several minutes on a fresh clone — so expect a wait the first time, and after a lockfile, toolchain or [profile] change. git push --no-verify skips the hook when that is not a good moment.

The gates lint your working tree, not the commits being pushed, so a push of an older branch or one made with dirty local edits checks something other than what lands. CI remains the authority — cargo xtask ci front-runs it, it does not replace it.

Documentation

The Bynk Book is the canonical guide and reference. It follows Diátaxis, grouped concern-first so each topic keeps its explanation, recipes, and reference together:

• Tutorials — learn Bynk by building.
• Guides — task-focused recipes, each section opening with the why before the how.
• Reference — exact behaviour, including the normative spec and CLI reference.

The online Book's source lives in site/. Build it locally with Astro: cd site && npm install && npm run dev.

A separate, print-first narrative manuscript, Architecture that compiles, is being developed in accuser/architecture-that-compiles. It draws on the documentation as research but does not share its prose or replace the online guide and reference. Its example programs are compile-tested against a published Bynk release, so a diagnostic rename here can invalidate a listing there — that repository's nightly gate is what reports it.

Status

Bynk is pre-1.0. Some designed features (events, sagas, storage kinds) are deferred, not missing, and land in later increments. See the status and roadmap.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.