Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/boa-dev/boa

Boa is an embeddable and experimental Javascript engine written in Rust. Currently, it has support for some of the language.
https://github.com/boa-dev/boa

ecmascript hacktoberfest interpreter javascript javascript-engine javascript-interpreter parser runtime rust rust-crate wasm webassembly

Last synced: about 21 hours ago
JSON representation

Boa is an embeddable and experimental Javascript engine written in Rust. Currently, it has support for some of the language.

Awesome Lists containing this project

README 

        
# Boa





  

    

      

      

      Boa logo

    

    




This is an experimental Javascript lexer, parser and interpreter written in Rust.

Currently, it has support for some of the language.



[![Build Status][build_badge]][build_link]

[![codecov](https://codecov.io/gh/boa-dev/boa/branch/main/graph/badge.svg)](https://codecov.io/gh/boa-dev/boa)

[![Crates.io](https://img.shields.io/crates/v/boa_engine.svg)](https://crates.io/crates/boa_engine)

[![Docs.rs](https://docs.rs/boa_engine/badge.svg)](https://docs.rs/boa_engine)

[![Discord](https://img.shields.io/discord/595323158140158003?logo=discord)](https://discord.gg/tUFFk9Y)

[![Matrix](https://img.shields.io/matrix/boa:matrix.org)](https://matrix.to/#/#boa:matrix.org)



[build_badge]: https://github.com/boa-dev/boa/actions/workflows/rust.yml/badge.svg?event=push&branch=main

[build_link]: https://github.com/boa-dev/boa/actions/workflows/rust.yml?query=event%3Apush+branch%3Amain



## Live Demo (WASM)



Try out the engine now at the live WASM playground [here](https://boajs.dev/playground)!



Prefer a CLI? Feel free to try out `boa_cli`!



## Boa Crates



Boa currently publishes and actively maintains the following crates:



- **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree

- **`boa_cli`** - Boa's CLI && REPL implementation

- **`boa_engine`** - Boa's implementation of ECMAScript builtin objects and

  execution

- **`boa_gc`** - Boa's garbage collector

- **`boa_interner`** - Boa's string interner

- **`boa_parser`** - Boa's lexer and parser

- **`boa_profiler`** - Boa's code profiler

- **`boa_icu_provider`** - Boa's ICU4X data provider

- **`boa_runtime`** - Boa's WebAPI features

- **`boa_string`** - Boa's ECMAScript string implementation.



Please note: the `Boa` and `boa_unicode` crates are deprecated.



## Boa Engine Example



To use `Boa` simply follow the below.



Add the below dependency to your `Cargo.toml`:



```toml

[dependencies]

boa_engine = "0.19.0"

```



Then in `main.rs`, copy the below:



```rust

use boa_engine::{Context, Source, JsResult};



fn main() -> JsResult<()> {

  let js_code = r#"

      let two = 1 + 1;

      let definitely_not_four = two + "2";



      definitely_not_four

  "#;



  // Instantiate the execution context

  let mut context = Context::default();



  // Parse the source code

  let result = context.eval(Source::from_bytes(js_code))?;



  println!("{}", result.display());



  Ok(())

}



```



Now, all that's left to do is `cargo run`.



Congrats! You've executed your first `JavaScript` using `Boa`!



## Documentation



For more information on `Boa`'s API. Feel free to check out our documentation.



[**API Documentation**](https://docs.rs/boa_engine/latest/boa_engine/)



## Conformance



To know how much of the _ECMAScript_ specification does Boa cover, you can check out results

running the _ECMASCript Test262_ test suite [here](https://boajs.dev/conformance).



## Contributing



Please, check the [CONTRIBUTING.md](CONTRIBUTING.md) file to know how to

contribute in the project. You will need Rust installed and an editor. We have

some configurations ready for VSCode.



### Debugging



Check [debugging.md](./docs/debugging.md) for more info on debugging.



### Web Assembly



This interpreter can be exposed to JavaScript!

You can build the example locally with:



```shell

npm run build

```



In the console you can use `window.evaluate` to pass JavaScript in.

To develop on the web assembly side you can run:



```shell

npm run serve

```



then go to `http://localhost:8080`.



## Usage



- Clone this repo.

- Run with `cargo run -- test.js` in the project root directory where `test.js` is a path to an existing JS file with any valid JS code.

- If any JS doesn't work then it's a bug. Please raise an [issue](https://github.com/boa-dev/boa/issues/)!



### Example



![Example](docs/img/latestDemo.gif)



## Command-line Options



```txt

Usage: boa [OPTIONS] [FILE]...



Arguments:

  [FILE]...  The JavaScript file(s) to be evaluated



Options:

      --strict                        Run in strict mode

  -a, --dump-ast []           Dump the AST to stdout with the given format [possible values: debug, json, json-pretty]

  -t, --trace                         Dump the AST to stdout with the given format

      --vi                            Use vi mode in the REPL

  -O, --optimize

      --optimizer-statistics

      --flowgraph []          Generate instruction flowgraph. Default is Graphviz [possible values: graphviz, mermaid]

      --flowgraph-direction   Specifies the direction of the flowgraph. Default is top-top-bottom [possible values: top-to-bottom, bottom-to-top, left-to-right, right-to-left]

      --debug-object                  Inject debugging object `$boa`

  -m, --module                        Treats the input files as modules

  -r, --root                    Root path from where the module resolver will try to load the modules [default: .]

  -h, --help                          Print help (see more with '--help')

  -V, --version                       Print version

```



## Roadmap



See [Milestones](https://github.com/boa-dev/boa/milestones).



## Benchmarks



See [Benchmarks](https://boajs.dev/benchmarks).



## Profiling



See [Profiling](./docs/profiling.md).



## Changelog



See [CHANGELOG.md](./CHANGELOG.md).



## Communication



Feel free to contact us on [Matrix](https://matrix.to/#/#boa:matrix.org) if you have any questions.

Contributor discussions take place on the same Matrix Space if you're interested in contributing.

We also have a [Discord](https://discord.gg/tUFFk9Y) for any questions or issues.



## License



This project is licensed under the [Unlicense](./LICENSE-UNLICENSE) or [MIT](./LICENSE-MIT) licenses, at your option.