brioche - v0.2.0

Brioche

Opinionated Gleam bindings over Bun API.

Brioche fills the gap between Gleam and a part of the JavaScript ecosystem, by providing easy-to-use, opinionated, gleamy bindings on Bun. Writing Gleam JavaScript & Bun code has never been easier, and no bindings are required for main features for Bun.

Brioche is still not production-ready, and as such, is not in 1.x.y version! Brioche is used at Steerlab, but not guarantee can be provided. Use it at your own risk.

Opinions

While Bun is a JavaScript runtime, Brioche does no try to provide 1:1 API. Instead, Brioche tries to provide idiomatic Gleam bindings on top of Bun, while leveraging the performance and the efficiency of the Bun runtime. Brioche takes inspiration in existing major Gleam packages in the ecosystem (Wisp, Glen, Pog, and so on), and provides similar API for a unified experience across the different Gleam targets. Brioche does not try to substitute to any of those, but tries to provide an alternative to those solutions if you’re looking for something different.

Brioche tries to use as much standard, official packages as possible from the Gleam ecosystem, while being dependent on almost no package. Brioche is a binding on top of Bun on which you can build or bring your own framework.

Wisp continues to be the de facto default web server in Gleam, and unless you know what you’re doing, and you’re ready to handle all the JavaScript promises and asynchronicity, you should use Wisp instead.

Glen is also a more mature, production-ready framework that proved to be efficient in case you’re targetting another runtime that Bun. You can also use Glen with Brioche freely, so if any code you’re looking for is already using Glen, use it!

Getting Started

Gleam & Bun are required to run. Bun is the runtime for Brioche. Brioche will not run on anything else than Bun.

Installing Brioche

# Install brioche.
gleam add brioche

# Install the other core packages. While those are transitive dependencies, they
# should be added in your `gleam.toml` to avoid any inconsistencies.
gleam add gleam_javascript gleam_http gleam_fetch gleam_json

Setting your gleam.toml

Setting your gleam.toml with target = "javascript", and the [javascript] section is a simple way to use Bun without hassle. At the end, your gleam.toml should look like this.

name = "your_project"
version = "1.0.0"
target = "javascript"

[javascript]
typescript_declarations = true
runtime = "bun"

[dependencies]
brioche = ">= 1.0.0 and < 2.0.0"
gleam_stdlib = ">= 0.44.0 and < 2.0.0"
gleam_javascript = ">= 1.0.0 and < 2.0.0"
gleam_http = ">= 4.0.0 and < 5.0.0"
gleam_fetch = ">= 1.2.0 and < 2.0.0"
gleam_json = ">= 2.0.0 and < 3.0.0"

[dev-dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

Documentation

Every Brioche modules are documented in their own modules. Complete documentation can be found on HexDocs.

Features

Brioche tries to implements all major features from Bun, with proper tests. Some still remain to be implemented. To stay stable, Brioche will not implement experimental features as they are subject to changes. In those cases, discretion is left to developer to implement missing features with the Gleam FFI. Below is the list of implemented features, with their state. Any help is welcome for non-implemented features.

Features already-made, documented, tested, and usable

Features made, but untested

Features remaining to implement

Experimental API, waiting for stabilisation before implementation

Contributing

Any Pull Request is welcome! Feel free to open a Pull Request with your desired changes to start the discussion, or open an issue first.

✨ Search Document