{"id":13637067,"url":"https://github.com/koute/cargo-web","last_synced_at":"2025-05-14T20:04:09.865Z","repository":{"id":17300508,"uuid":"81644132","full_name":"koute/cargo-web","owner":"koute","description":"A Cargo subcommand for the client-side Web","archived":false,"fork":false,"pushed_at":"2023-11-29T04:25:09.000Z","size":887,"stargazers_count":1107,"open_issues_count":108,"forks_count":78,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-30T10:04:27.363Z","etag":null,"topics":["asmjs","emscripten","rust","web","webasm","webassembly"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-02-11T09:49:08.000Z","updated_at":"2025-03-26T16:09:10.000Z","dependencies_parsed_at":"2024-04-10T05:38:43.516Z","dependency_job_id":"95b9936c-918c-4df3-9352-352337284760","html_url":"https://github.com/koute/cargo-web","commit_stats":{"total_commits":445,"total_committers":25,"mean_commits":17.8,"dds":"0.12134831460674156","last_synced_commit":"2ddd9bbb567b8d4893e923cba8ad03806d383d80"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koute%2Fcargo-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koute%2Fcargo-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koute%2Fcargo-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koute%2Fcargo-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koute","download_url":"https://codeload.github.com/koute/cargo-web/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471516,"owners_count":20944158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asmjs","emscripten","rust","web","webasm","webassembly"],"created_at":"2024-08-02T00:01:10.019Z","updated_at":"2025-04-06T11:05:38.916Z","avatar_url":"https://github.com/koute.png","language":"Rust","readme":"[![Build Status](https://api.travis-ci.org/koute/cargo-web.svg)](https://travis-ci.org/koute/cargo-web)\n\n# A cargo subcommand for the client-side Web\n\nThis cargo subcommand aims to make it easy and convenient to build, develop\nand deploy client-side Web applications written in Rust.\n\n## Donate\n\n[![Become a patron](https://koute.github.io/img/become_a_patron_button.png)](https://www.patreon.com/koute)\n\n## Patrons\n\nThis software was brought to you thanks to these wonderful people:\n  * Embark Studios\n  * Joe Narvaez\n  * Eduard Knyshov\n  * Anselm Eickhoff\n  * Johan Andersson\n  * Stephen Sugden\n  * is8ac\n\nThank you!\n\n## Features\n\nCurrently it supports the following features:\n\n  * `cargo web build` - will build your project using one of Rust's three Web backends:\n    * [WebAssembly] using Rust's native WebAssembly backend (when you pass `--target=wasm32-unknown-unknown`; default)\n    * [WebAssembly] using Emscripten (when you pass `--target=wasm32-unknown-emscripten`)\n    * [asm.js] using Emscripten (when you pass `--target=asmjs-unknown-emscripten`)\n  * `cargo web check` - will typecheck your project\n  * `cargo web test` - will run your tests either under:\n    * Under a headless instance of Google Chrome (default)\n    * Under [Node.js] (when you pass `--nodejs`)\n  * `cargo web start` - will build your project, start an embedded webserver and will continuously\n    rebuild it if necessary; supports automatic reloading with `--auto-reload`.\n  * `cargo web deploy` - will build your project and emit all of the necessary files so that\n    you can easily serve them statically.\n  * Will automatically download and install Emscripten for you (if necessary) on the following platforms:\n    * Linux x86-64\n    * Linux x86\n  * Will automatically install the relevant Rust target through `rustup`\n\n[asm.js]: https://en.wikipedia.org/wiki/Asm.js\n[WebAssembly]: https://en.wikipedia.org/wiki/WebAssembly\n[Node.js]: https://nodejs.org/en/\n\nIt's also highly recommended that you check out the [stdweb] crate if you want\nto interact with the JavaScript world in your project. (In fact, `cargo-web`\nis what makes it possible to use `stdweb`'s `js!` macro on Rust's native WebAssembly\nbackend.)\n\n[stdweb]: https://github.com/koute/stdweb\n\n## Installation\n\n    $ cargo install cargo-web\n\nTo upgrade:\n\n    $ cargo install --force cargo-web\n\nOr clone and build with `$ cargo build --release` then place in your $PATH.\n\nOn Linux the installation can fail with a message that it can't find OpenSSL,\nin which case you most likely need to install the `-dev` package for OpenSSL\nfrom your distribution's repositories. (On Ubuntu it's called `libssl-dev`.)\n\n## `Web.toml`\n\n`cargo-web` has its own configuration file which you can put next to `cargo`'s [`Cargo.toml`].\n\nHere's an example configuration showing every supported key:\n\n```toml\n# The default value of `--target` used when building this crate\n# in cases where it's not specified on the command line.\ndefault-target = \"wasm32-unknown-unknown\"\n\n# This will prepend a given JavaScript file to the resulting `.js` artifact.\n# You can put any initialization code here which you'd like to have executed\n# when your `.js` file first loads.\n#\n# This accepts either a string (as shown here), or an array of strings,\n# in which case it will prepend all of the specified files in their\n# order of appearance.\nprepend-js = \"src/runtime.js\"\n\n[cargo-web]\n# Asserts the minimum required version of `cargo-web` necessary\n# to compile this crate; supported since 0.6.0.\nminimum-version = \"0.6.0\"\n\n# These will only take effect on *-emscripten targets.\n[target.emscripten]\n# You can have a target-specific `prepend-js` key.\nprepend-js = \"src/emscripten_runtime.js\"\n# This will enable Emscripten's SDL2 port. Consult Emscripten's documentation\n# for more details.\nlink-args = [\"-s\", \"USE_SDL=2\"]\n\n# You can also specify the target by its full name.\n[target.wasm32-unknown-unknown]\nprepend-js = \"src/native_runtime.js\"\n```\n\nIf you use any external crates which have a `Web.toml` then `cargo-web`\n**will** load it and use it.\n\nA few restrictions concerning the `Web.toml`:\n\n  * You can't have overlapping `prepend-js` keys. You can either define\n    a single global `prepend-js`, or multiple per-target ones.\n  * The `link-args` currently can't have any spaces in them.\n  * The order in which `cargo-web` will process the `Web.toml` files\n    from multiple crates is deterministic yet unspecified. This means\n    that you shouldn't depend on this order in any way.\n\n[`Cargo.toml`]: https://doc.rust-lang.org/cargo/reference/manifest.html\n\n## Static files\n\nAny static files you'd like to have served when running `cargo web start` or deployed\nwhen running `cargo web deploy` can be put in a directory called `static` in the root\nof your crate. No static artifacts are required by default; an `index.html` file will\nbe automatically generated for you if it's missing. You can, of course, put your own `static/index.html`\nfile, in which case it will be used instead of the autogenerated one.\n\n## Detecting `cargo-web` during compilation\n\nIf during compilation you'd like to detect that your project is being built with `cargo-web`\nyou can check the `COMPILING_UNDER_CARGO_WEB` environment variable, which will be set to `1`.\n\n## Using `cargo-web` on Travis\n\n### Precompiled binaries\n\nYou can use the following script to download and install the latest `cargo-web`:\n\n```shell\nCARGO_WEB_RELEASE=$(curl -L -s -H 'Accept: application/json' https://github.com/koute/cargo-web/releases/latest)\nCARGO_WEB_VERSION=$(echo $CARGO_WEB_RELEASE | sed -e 's/.*\"tag_name\":\"\\([^\"]*\\)\".*/\\1/')\nif [ \"$(uname -s)\" == \"Darwin\" ]; then\n  CARGO_WEB_HOST_TRIPLE=\"x86_64-apple-darwin\"\nelse\n  CARGO_WEB_HOST_TRIPLE=\"x86_64-unknown-linux-gnu\"\nfi\nCARGO_WEB_URL=\"https://github.com/koute/cargo-web/releases/download/$CARGO_WEB_VERSION/cargo-web-$CARGO_WEB_HOST_TRIPLE.gz\"\n\n\necho \"Downloading cargo-web from: $CARGO_WEB_URL\"\ncurl -L $CARGO_WEB_URL | gzip -d \u003e cargo-web\nchmod +x cargo-web\n\nmkdir -p ~/.cargo/bin\nmv cargo-web ~/.cargo/bin\n```\n\n### Running tests under headless Chrome\n\nBy default `cargo web test` will run your tests under headless Chrome. To be able to use this on Travis\nyou need to add something like this to your `.travis.yml`:\n\n```yaml\naddons:\n  chrome: stable\n```\n\n## Custom runtime (`wasm32-unknown-unknown`-only)\n\nWhen building a project by default `cargo-web` generates a standalone runtime\nruntime for you. What this means is that the `.js` file which is generated\ncan be immediately put inside of a `\u003cscript\u003e` tag or launched with Node.js\nwithout having to load it manually or do anything extra, however this does\nlimit you when it comes to customizability.\n\nIf you'd like to have a little more control on how your module is loaded\nthen you can tell `cargo-web` to generate a non-standalone, library-like\nmodule for you with the `--runtime library-es6` option. This will result\nin a `.js` file which exports a factory function with the following interface:\n\n```js\nexport default function() {\n    return {\n        imports: { ... },\n        initialize: function( instance ) { ... }\n    };\n}\n```\n\nHere you have to instantiate the WebAssembly module yourself; in this\ncase you have to pass `imports` as its imports, and then immediately\nafter instantiating it call `initialize`.\n\nFor example, assuming you'll name your module generated by the `cargo-web`\nas `my-module.mjs` and `my-module.wasm` you can instantiate it like this from Node.js:\n\n```js\nimport fs from \"fs\";\nimport factory from \"my-module.mjs\";\n\n// We read in the `.wasm` module.\nconst bytecode = fs.readFileSync( \"my-module.wasm\" );\nconst wasm = new WebAssembly.Module( bytecode );\n\n// We instantiate it.\nconst instance = factory();\nconst compiled = new WebAssembly.Instance( wasm, instance.imports );\n\n// This will initialize the module and call your `main`, if you have one.\nconst exports = instance.initialize( compiled );\n\n// In the object it returns you can find any functions which\n// you've exported with `stdweb`'s `#[js_export]` macro.\nconsole.log( exports.add( 1, 2 ) );\n```\n\nThen you can run it with `node --experimental-modules run.mjs`.\n\nThis is useful if you want to load your `.wasm` file from a custom URL or\nyou want to integrate the output with a JavaScript bundler, or anything\nelse which requires you to load the module yourself.\n\n## Changelog\n   * `0.6.26`\n      * The `--no-default-features` flag was fixed\n      * The `mime-guess` crate is now being used to guess the mime types by the embedded webserver\n   * `0.6.25`\n      * `cargo web start` will now try to not trigger superfluous rebuilds when the project's\n        files are modified in quick succession\n      * The vendored OpenSSL copy was updated to the newest version\n   * `0.6.24`\n      * Conditional dependencies of form `[target.'cfg(...)'.dependencies]` are now properly supported\n      * You can now use `cfg(cargo_web)` to detect whenever your crate is being compiled under `cargo-web`\n      * Artifacts matching `target/wasm32-unknown-unknown/*/deps/*.wasm` are now ignored; this should prevent\n        `cargo-web` from processing superfluous `.wasm` artifacts generated due to dependencies also being `cdylib`s\n      * `cargo-web` is now available as a library through a `structopt`-based interface\n   * `0.6.23`\n      * New subcommand: `cargo web check`\n      * The `wasm32-unknown-unknown` target is now the default\n   * `0.6.22`\n      * Running tests through Chrome should now work out-of-box on macOS\n      * The `deploy` subcommand can now be told where to deploy using the `-o`/`--output` parameter\n      * Static files with spaces in their names are now properly served\n      * `Access-Control-Allow-Origin: *` is now always sent by the embedded webserver\n      * Debug builds on `wasm32-unknown-unknown` are now supported provided a recent enough `stdweb` is used\n   * `0.6.21`\n      * Emscripten was updated to `1.38.19`; the Emscripten-based targets should now work again on nightly\n      * Broken output redirection in the test runner is now fixed\n      * The generated JS snippets and imports under `wasm32-unknown-unknown` are now sorted\n      * Compatibility with *really* old nightlies was removed for `wasm32-unknown-unknown`\n   * `0.6.20`\n      * Installation through `cargo install` should now work again\n      * Most of the dependencies were updated to newer versions\n      * `deploy` should not panic when it doesn't find a valid target\n   * `0.6.19`\n      * `cargo install` should now compile instead of failing in some environments\n      * Minimum required Rust version is now `1.26.2`\n   * `0.6.18`\n      * Default `index.html` doesn't have a newline before its doctype anymore\n   * `0.6.17`\n      * OpenSSL is now vendored; this should fix the compilation in some environments\n      * Minimum required Rust version is now `1.25.0`\n   * `0.6.16`\n      * The runtime for `wasm32-unknown-unknown` now uses `WebAssembly.instantiateStreaming` when available\n      * Running tests under headless Chromium is now supported for the `wasm32-unknown-unknown` target\n      * Color codes are no longer emitted when the output of `cargo-web` is redirected\n      * Improved coloring; a lot more messages should now be colored\n      * Initial experimental support for asynchronous tests\n\n## License\n\nLicensed under either of\n\n  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","funding_links":["https://www.patreon.com/koute"],"categories":["Libraries","Rust","Tooling"],"sub_categories":["Web programming","Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoute%2Fcargo-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoute%2Fcargo-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoute%2Fcargo-web/lists"}