{"id":21659562,"url":"https://github.com/bytecodealliance/cargo-component","last_synced_at":"2025-07-12T01:13:25.063Z","repository":{"id":43536668,"uuid":"480632339","full_name":"bytecodealliance/cargo-component","owner":"bytecodealliance","description":"A Cargo subcommand for creating WebAssembly components based on the component model proposal.","archived":false,"fork":false,"pushed_at":"2025-06-03T18:25:43.000Z","size":2136,"stargazers_count":537,"open_issues_count":56,"forks_count":64,"subscribers_count":31,"default_branch":"main","last_synced_at":"2025-07-05T01:07:02.370Z","etag":null,"topics":[],"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/bytecodealliance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-12T02:57:41.000Z","updated_at":"2025-07-01T16:14:55.000Z","dependencies_parsed_at":"2023-12-22T01:02:06.818Z","dependency_job_id":"c318efee-56d2-421a-8867-37adc4edcdb8","html_url":"https://github.com/bytecodealliance/cargo-component","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/bytecodealliance/cargo-component","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcargo-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcargo-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcargo-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcargo-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytecodealliance","download_url":"https://codeload.github.com/bytecodealliance/cargo-component/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fcargo-component/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263673192,"owners_count":23494345,"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":[],"created_at":"2024-11-25T09:31:14.980Z","updated_at":"2025-07-12T01:13:25.049Z","avatar_url":"https://github.com/bytecodealliance.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\u003ccode\u003ecargo component\u003c/code\u003e\u003c/h1\u003e\n\n\u003cstrong\u003eA \u003ca href=\"https://bytecodealliance.org/\"\u003eBytecode Alliance\u003c/a\u003e project\u003c/strong\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003eA cargo subcommand for building WebAssembly components according to the \u003ca href=\"https://github.com/WebAssembly/component-model/\"\u003ecomponent model proposal\u003c/a\u003e.\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/bytecodealliance/cargo-component/actions?query=workflow%3ACI\"\u003e\u003cimg src=\"https://github.com/bytecodealliance/cargo-component/workflows/CI/badge.svg\" alt=\"build status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://crates.io/crates/cargo-component\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/cargo-component.svg?style=flat-square\" alt=\"Crates.io version\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://crates.io/crates/cargo-component\"\u003e\u003cimg src=\"https://img.shields.io/crates/d/cargo-component.svg?style=flat-square\" alt=\"Download\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://bytecodealliance.github.io/cargo-component/\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square\" alt=\"docs.rs docs\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## Overview\n\n`cargo component` is a `cargo` subcommand for creating [WebAssembly components](https://github.com/WebAssembly/component-model)\nusing Rust as the component's implementation language.\n\n### Notice\n\n`cargo component` is considered to be experimental and is _not_ currently\nstable in terms of the code it supports building.\n\nUntil the component model stabilizes, upgrading to a newer `cargo component`\nmay cause build errors for existing component projects.\n\n## Requirements\n\n1. The `cargo component` subcommand is written in Rust, so you'll want the\n  [latest stable Rust installed](https://www.rust-lang.org/tools/install).\n2. `cargo component` requires a working OpenSSL install on Linux. See the installation instructions [here](https://docs.rs/openssl/0.10.64/openssl/index.html#automatic).\n3. `cargo component` also requires a working C toolchain. Make sure to have a\nworking `cc` command (or equivalent) for your environment.\n\n## Installation\n\nTo install the `cargo component` subcommand from source, run the following\ncommand:\n\n```\ncargo install cargo-component --locked\n```\n\nIf you have the [cargo-binstall](https://github.com/cargo-bins/cargo-binstall)\nutility installed, `cargo component` can also be installed via a prebuilt\nrelease artifact, saving time on the installation:\n\n```\ncargo binstall cargo-component\n```\n\n## Motivation\n\nToday, developers that target WebAssembly typically compile a monolithic\nprogram written in a single source language to a WebAssembly module. The\nWebAssembly module can then be used in all sorts of places: from web\nbrowsers to cloud compute platforms. WebAssembly was intentionally designed\nto provide the portability and security properties required for such\nenvironments.\n\nHowever, WebAssembly modules are not easily _composed_ with other modules\ninto a single program or service. WebAssembly only has a few primitive\nvalue types (integer and floating point types) and those are inadequate\nto describe the complex types that developers would desire to exchange\nbetween modules.\n\nTo make things even more challenging, WebAssembly modules typically define\ntheir own local linear memories, meaning one module can't access the\n(conceptual) _address space_ of another. Something must sit between the\ntwo modules to facilitate communication when pointers are passed around.\n\nWhile it is possible to solve these challenges with the existing\nWebAssembly standard, doing so is burdensome, error-prone, and requires\nforeknowledge of how the WebAssembly modules are implemented.\n\n## WebAssembly Component Model\n\nThe WebAssembly component model proposal provides a way to\nsimplify the process of building WebAssembly applications and services\nout of reusable pieces of functionality using a variety of source\nlanguages, all while still maintaining the portability and\nsecurity properties of WebAssembly.\n\nAt its most fundamental level, WebAssembly components may be used to\nwrap a WebAssembly module in a way that describes how its _interface_,\na set of functions using complex value types (e.g. strings, variants,\nrecords, lists, etc.), is translated to and from the lower-level\nrepresentation required of the WebAssembly module.\n\nThis enables WebAssembly runtimes to know specifically how they must\nfacilitate the exchange of data between the discrete linear memories\nof components, eliminating the need for developers to do so by hand.\n\nAdditionally, components can describe their dependencies in a way\nthat modules simply cannot today; they can even control how their\ndependencies are _instantiated_, enabling a component to\n_virtualize_ functionality needed by a dependency. And because\ndifferent components might have a shared dependency, hosts may even\nshare the same implementation of that dependency to save on host\nmemory usage.\n\n## Cargo Component\n\nA primary goal of `cargo component` is to try to imagine what\nfirst-class support for WebAssembly components might look like for Rust.\n\nThat means being able to reference WebAssembly components via\n`Cargo.toml` and have WebAssembly component dependencies used in the\nsame way as Rust crate dependencies:\n\n* add a dependency on a WebAssembly component to `Cargo.toml`\n* reference it like you would an external crate (via `bindings::\u003cname\u003e::...`) in\n  your source code\n* build using `cargo component build` and out pops your component!\n\nTo be able to use a WebAssembly component from any particular\nprogramming language, _bindings_ must be created by translating\na WebAssembly component's _interface_ to a representation that\na specific programming language can understand.\n\nTools like [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen)\nexist to generate those bindings for different languages,\nincluding Rust.\n\n`wit-bindgen` even provides procedural macros to generate the\nbindings \"inline\" with the component's source code.\n\nUnlike `wit-bindgen`, `cargo component` generates bindings directly into your\nproject at `src/bindings.rs` so that bindings are generated based on the\nresolved dependencies from `Cargo.toml` rather than parsing a local definition\nof the component's interface.\n\nThe hope is that one day (in the not too distant future...) that\nWebAssembly components might become an important part of the Rust\necosystem such that `cargo` itself might support them.\n\nUntil that time, there's `cargo component`!\n\n## WASI Support\n\nCurrently `cargo component` uses the `wasm32-wasip1` target to produce core\nWasm modules, and then adapts them into WASIp2 aka \"preview2\" components.\n\nThe adaptation is automatically performed when `wasm32-wasip1` is targeted using\na built-in WASI adapter snapshotted out of the Wasmtime repository.\n\nYou may override the built-in adapter `cargo component` uses by setting the\n`adapter` setting in the `[package.metadata.component]` table in `Cargo.toml`\nto the path to the adapter module to use.\n\nTo build the adapter module, clone the [Wasmtime repository](https://github.com/bytecodealliance/wasmtime)\nand run the following commands:\n\n```bash\n# Add the wasm32-unknown-unknown target if you haven't already\nrustup target add wasm32-unknown-unknown\n\ngit checkout $REV\n\ngit submodule update --init\n\ncargo build -p wasi-preview1-component-adapter --target wasm32-unknown-unknown --release\n\ncp target/wasm32-unknown-unknown/release/wasi_snapshot_preview1.wasm $PROJECT\n```\n\nwhere `$REV` is the Wasmtime commit hash you want to use and `$PROJECT` is the\npath to your component project.\n\nNext, edit `Cargo.toml` to point at the adapter:\n\n```toml\n[package.metadata.component]\nadapter = \"wasi_snapshot_preview1.wasm\"\n```\n\nThe Rust compiler now has an [upstream Rust wasm32-wasip2] target that produces\ncomponents. In the future, we hope to update `cargo component` to use it directly.\n\n[upstream Rust wasm32-wasip2 target]: https://blog.rust-lang.org/2024/11/26/wasip2-tier-2.html\n\n## Relationship with wasm32-wasip2\n\nAs of Rust 1.82, there is now an [upstream Rust wasm32-wasip2 target], which\nproduces components using plain `cargo`, and doesn't use `cargo-component`.\nPrograms using this target can access WASI by using [the `wasi` crate].\n\nThis may be easier to use than `cargo component` in some situations, however\nit doesn't yet support all things that cargo-component does, so at this time,\nit's not a complete replacement.\n\nSo for now, if you only need WASI interfaces, then the wasm32-wasip2 target\nand the `wasi` crate should work. If you have non-WASI WIT interfaces, whether\nthird-party WIT interfaces or your own custom WIT interfaces, then use\n`cargo component`.\n\n[the `wasi` crate]: https://docs.rs/wasi\n[upstream Rust wasm32-wasip2 target]: https://blog.rust-lang.org/2024/11/26/wasip2-tier-2.html\n\n## Getting Started\n\nUse `cargo component new --lib \u003cname\u003e` to create a new library (reactor)\ncomponent.\n\nA library component doesn't have a `run` (i.e. `main` in Rust) function\nexported and is meant to be used as a library rather than a command that runs\nand exits. Without the `--lib` flag, `cargo component` defaults to creating\na command component.\n\nThis will create a `wit/world.wit` file describing the world that the\ncomponent will target:\n\n```wit\npackage my-org:my-component;\n\n/// An example world for the component to target.\nworld example {\n    export hello-world: func() -\u003e string;\n}\n```\n\nThe component will export a `hello-world` function returning a string.\n\nThe implementation of the component will be in `src/lib.rs`:\n\n```rust\n#[allow(warnings)]\nmod bindings;\n\nuse bindings::Guest;\n\nstruct Component;\n\nimpl Guest for Component {\n    /// Say hello!\n    fn hello_world() -\u003e String {\n        \"Hello, World!\".to_string()\n    }\n}\n\nbindings::export!(Component with_types_in bindings);\n```\n\nThe `bindings` module contains the the types and traits that correspond to the\nworld targeted by the component; it is automatically generated by\n`cargo component`.\n\n## Usage\n\nThe `cargo component` subcommand has some analogous commands to cargo itself:\n\n* `cargo component new` — creates a new WebAssembly component Rust project.\n* `cargo component add` — adds a component interface dependency to a cargo\n  manifest file.\n* `cargo component update` — same as `cargo update` but also updates the\n  dependencies in the component lock file.\n* `cargo component publish` - publishes a WebAssembly component to a [warg](https://github.com/bytecodealliance/registry/)\n  component registry.\n\nUnrecognized commands are passed through to `cargo` itself, but only after the\nbindings information for component packages has been updated.\n\nSome examples of commands that are passed directly to `cargo` are: `build`,\n`check`, `doc`, `clippy` and extension commands such as `expand` from\n`cargo-expand`.\n\nCertain command line options, like `--target` and `--release`, are detected by\n`cargo component` to determine what output files of a `build` command should be\ncomponentized.\n\n## Using `rust-analyzer`\n\n[rust-analyzer](https://github.com/rust-analyzer/rust-analyzer) is an extremely\nuseful tool for analyzing Rust code and is used in many different editors to\nprovide code completion and other features.\n\nrust-analyzer depends on `cargo metadata` and `cargo check` to discover\nworkspace information and to check for errors.\n\nTo ensure that rust-analyzer is able to discover the latest bindings\ninformation, rust-analyzer must be configured to use `cargo component check` as\nthe check command.\n\nTo configure rust-analyzer to use the `cargo component` executable, set the\n`rust-analyzer.check.overrideCommand` setting to the following:\n\n```json\n{\n    \"rust-analyzer.check.overrideCommand\": [\n        \"cargo\",\n        \"component\",\n        \"check\",\n        \"--workspace\",\n        \"--all-targets\",\n        \"--message-format=json\"\n    ],\n}\n```\n\nBy default, `cargo component new` will configure Visual Studio Code to use\n`cargo component check` by creating a `.vscode/settings.json` file for you. To\nprevent this, pass `--editor none` to `cargo component new`.\n\nPlease check the documentation for rust-analyzer regarding how to set settings\nfor other IDEs.\n\n## Contributing to `cargo component`\n\n`cargo component` is a [Bytecode Alliance](https://bytecodealliance.org/)\nproject, and follows the Bytecode Alliance's [Code of Conduct](CODE_OF_CONDUCT.md)\nand [Organizational Code of Conduct](ORG_CODE_OF_CONDUCT.md).\n\n### Getting the Code\n\nYou'll clone the code via `git`:\n\n```\ngit clone https://github.com/bytecodealliance/cargo-component\n```\n\n### Testing Changes\n\nWe'd like tests ideally to be written for all changes. Test can be run via:\n\n```\ncargo test\n```\n\nYou'll be adding tests primarily to the `tests/` directory.\n\n### Submitting Changes\n\nChanges to `cargo component` are managed through pull requests (PRs). Everyone\nis welcome to submit a pull request! We'll try to get to reviewing it or\nresponding to it in at most a few days.\n\n### Code Formatting\n\nCode is required to be formatted with the current Rust stable's `cargo fmt`\ncommand. This is checked on CI.\n\n### Continuous Integration\n\nThe CI for the `cargo component` repository is relatively significant. It tests\nchanges on Windows, macOS, and Linux.\n\n### Publishing\n\nPublication of this crate is entirely automated via CI. A publish happens\nwhenever a tag is pushed to the repository, so to publish a new version you'll\nwant to make a PR that bumps the version numbers (see the `ci/publish.rs`\nscript), merge the PR, then tag the PR and push the tag. That should trigger\nall that's necessary to publish all the crates and binaries to crates.io.\n","funding_links":[],"categories":["Rust","WASM/WASI 🕸️"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fcargo-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytecodealliance%2Fcargo-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fcargo-component/lists"}