{"id":21659554,"url":"https://github.com/bytecodealliance/wasm-pkg-tools","last_synced_at":"2026-02-06T20:06:57.396Z","repository":{"id":238913845,"uuid":"791818838","full_name":"bytecodealliance/wasm-pkg-tools","owner":"bytecodealliance","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-03T21:23:58.000Z","size":524,"stargazers_count":92,"open_issues_count":33,"forks_count":22,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-07-12T00:44:56.392Z","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":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-25T12:38:06.000Z","updated_at":"2025-06-26T02:15:31.000Z","dependencies_parsed_at":"2024-05-08T21:25:17.461Z","dependency_job_id":"d6bfe012-2695-413c-92bf-128ee414e973","html_url":"https://github.com/bytecodealliance/wasm-pkg-tools","commit_stats":null,"previous_names":["bytecodealliance/wasm-pkg-tools"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/bytecodealliance/wasm-pkg-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwasm-pkg-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwasm-pkg-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwasm-pkg-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwasm-pkg-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytecodealliance","download_url":"https://codeload.github.com/bytecodealliance/wasm-pkg-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwasm-pkg-tools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264922908,"owners_count":23683705,"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:13.533Z","updated_at":"2025-10-10T03:15:19.803Z","avatar_url":"https://github.com/bytecodealliance.png","language":"Rust","readme":"# wasm-pkg-tools\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eA \u003ca href=\"https://bytecodealliance.org/\"\u003eBytecode Alliance\u003c/a\u003e project\u003c/strong\u003e\n\u003c/div\u003e\n\nTools to package up [Wasm Components](https://github.com/webassembly/component-model)\n\nThis repo contains several Rust crates that can be used for fetching and publishing Wasm Components\nto OCI or Warg registries. It is also the home of the `wkg` command line tool, which exposes all the\nfunctionality of the libraries. The first (but not only) focus of this project is allow for fetching\nof Wit Interfaces stored as components for use in creating components. It can also be used to fetch\nand publish component \"libraries\" to/from a registry.\n\n## Installation\n\nRight now installation of `wkg` is manual. You can either clone the repo and build from source, or\ndownload a pre-built binary from the [releases\npage](https://github.com/bytecodealliance/wasm-pkg-tools/releases) and add it to your `PATH`. In the\nfuture we will add this tool to various package managers. If this is something you'd like to help\nwith, please feel free to open some PRs!\n\nIf you have a Rust toolchain installed, you can also install `wkg` with one of the following\noptions:\n\n```sh\ncargo install wkg\n```\n\nIf you have [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) installed, you can also\ninstall `wkg` with a pre-built binary:\n\n```sh\ncargo binstall wkg\n```\n\n## Configuration\n\nTo quickly set the default registry:\n```\nwkg config --default-registry {REGISTRY_DOMAIN}\n```\n\nFor the complete configuration options, you can edit the config file with your default\neditor (set with env var `$EDITOR`):\n```\nwkg config --edit\n```\n\nThe `wkg` tool and libraries use a configuration file to store settings. This config file is still\nsubject to change but we will try to keep it backwards compatible as we continue to develop the\ntool. This config file is meant to be used by both `wkg` and also any other language-specific\ncomponent tooling that wants to fetch from registries. This should allow for a single configuration\nfile that can be used by all tooling, whether that be `wkg` or some other tool that isn't written in\nRust.\n\nThe default location is `$XDG_CONFIG_HOME/wasm-pkg/config.toml` on unix-like systems and\n`{FOLDERID_RoamingAppData}\\wasm-pkg\\config.toml` on Windows but this can be overridden with the\n`--config` flag. Examples of this are found below:\n\n| Platform | Path                                  |\n| -------- | ------------------------------------- |\n| Linux    | `/home/\u003cusername\u003e/.config`            |\n| macOS    | `/home/\u003cusername\u003e/.config`            |\n| Windows  | `C:\\Users\\\u003cusername\u003e\\AppData\\Roaming` |\n\nThe configuration file is TOML and can be edited manually.\n\nBelow is an annotated example of a configuration file that shows all the available options.\n\n```toml\n# The default registry to use when none is specified. Generally this is wasi.dev, but can be set\n# for cases when a company wants to use a private/internal registry.\ndefault_registry = \"acme.registry.com\"\n\n# This section contains a mapping of namespace prefixes (i.e. the \"wasi\" part of \"wasi:http\") to\n# registries. This is used to determine which registry to use when fetching or publishing a\n# component. If a namespace is not listed here, the default registry will be used.\n[namespace_registries]\nwasi = \"wasi.dev\"\nexample = \"example.com\"\n# An example of providing your own registry mapping. For large and/or public registries, we\n# recommend creating a well-known metadata file that can be used to determine the registry to use\n# (see the section on \"metadata\" below). But many times you might want to override mappings or\n# provide something that is used by a single team. The registry name does not matter, but must be\n# parsable to URL authority. This name is purely used for mapping to registry config and isn't\n# actually used as a URL when metadata is provided \nanother = { registry = \"another\", metadata = { preferredProtocol = \"oci\", \"oci\" = {registry = \"ghcr.io\", namespacePrefix = \"webassembly/\" } } }\n\n# This overrides the default registry for a specific package. This is useful for cases where a \n# package is published to multiple registries. \n[package_registry_overrides]\n\"example:foo\" = \"example.com\"\n# Same as namespace_registries above, but for a specific package.\n\"example:bar\" = { registry = \"another\", metadata = { preferredProtocol = \"oci\", \"oci\" = {registry = \"ghcr.io\", namespacePrefix = \"webassembly/\" } } }\n\n# This section contains a mapping of registries to their configuration. There are currently 3\n# supported types of registries: \"oci\", \"warg\", and \"local\". The \"oci\" type is the default. The\n# example below shows a use case that isn't yet super common (registries that speak multiple protocols)\n# but is included for completeness.\n[registry.\"acme.registry.com\"]\n# This field is only required if more that one protocol is supported. It indicates which protocol\n# to use by default. If this is not set, then the fallback (oci) will be used.\ndefault = \"warg\"\n[registry.\"acme.registry.com\".warg]\n# A path to a valid warg config file. If this is not set, the `wkg` CLI (but not the libraries) \n# will attempt to load the config from the default location(s).\nconfig_file = \"/a/path\"\n# An optional authentication token to use when authenticating with a registry.\nauth_token = \"an-auth-token\"\n# An optional key for signing the component. Ideally, you should just let warg use the keychain\n# or programmatically set this key in the config without writing to disk. This offers an escape\n# hatch for when you need to use a key that isn't in the keychain.\nsigning_key = \"ecdsa-p256:2CV1EpLaSYEn4In4OAEDAj5O4Hzu8AFAxgHXuG310Ew=\"\n[registry.\"acme.registry.com\".oci]\n# The auth field can either be a username/password pair, or a base64 encoded `username:password` \n# string. If no auth is set, the `wkg` CLI (but not the libraries) will also attempt to load the\n# credentials from the docker config.json. This field is also optional and if not set, anonymous\n# auth will be used. If you're just pulling from a public registry, this is likely not required.\n# If you're using a private registry and/or publishing, you'll almost certainly need to set this.\nauth = { username = \"open\", password = \"sesame\" }\n# This is an optional field that tells the OCI client to use a specific http protocol. If this is\n# not set or not one of the accepted values of \"http\" or \"https\", then the default (https) will\n# be used.\nprotocol = \"https\"\n[registry.\"acme.registry.com\".local]\n# This is a required field that specifies the root directory on a filesystem where the components\n# are stored. This is mostly used for local development and testing.\nroot = \"/a/path\"\n\n# If a registry only has a config section for one protocol, then that protocol is automatically\n# the default. The following is equivalent to:\n# [registry.\"example.com\"]\n# default = \"warg\"\n# [registry.\"example.com\".warg]\n# config_file = \"/a/path\"\n[registry.\"example.com\".warg]\nconfig_file = \"/a/path\"\n\n# Configuration for the \"another\" registry defined above.\n[registry.\"another\".oci]\nauth = { username = \"open\", password = \"sesame\" }\n```\n\n### Well-known metadata\n\nFor well-used or public registries, we recommend creating a well-known metadata file that is used by\nthe tool chain to simplify configuration and indicate to a client which protocols and mappings to\nuse (although this can be set directly in config as well). The `wkg` tool and libraries expect a\n`registry.json` file to be present at a specific location to indicate to the tooling where the\ncomponents are stored. For example, if a registry was `example.com`, then the tooling will attempt\nto find a `registry.json` file at `https://example.com/.well-known/wasm-pkg/registry.json`. \n\nA full example of what this `registry.json` file should look like is below:\n\n```json\n{\n  \"preferredProtocol\":\"warg\",\n  \"warg\": {\"url\":\"https://warg.example.com\"},\n  \"oci\": {\"registry\": \"ghcr.io\", \"namespacePrefix\": \"webassembly/\"}\n}\n```\n\nThe `preferredProtocol` field is optional and specifies which protocol the registry expects you to\nuse in the case where it supports both OCI and Warg. If both `warg` and `oci` config is in the\n`registry.json` it is _highly recommended_ that this field be set. \n\nFor the `oci` config, the `registry` field is the base URL of the OCI registry, and the\n`namespacePrefix` field is the prefix that is used to store components in the registry. So in the\nexample above (which is for wasi.dev), the components will be available at\n`ghcr.io/webassembly/$NAMESPACE/$PACKAGE:$VERSION` (e.g. `ghcr.io/webassembly/wasi/http:0.2.1`).\n\nFor the `warg` config, the `url` field is the base URL of the Warg registry used when connecting the\nclient. Namespacing for warg is built in to the protocol.\n\nPlease note that for backwards compatibility, with previous tooling and versions of the `wkg` tool,\nyou may also encounter a `registry.json` file that looks different. These files are still supported,\nbut should be considered deprecated.\n\nFor OCI registries, the JSON looks like this:\n\n```json\n{\n        \"ociRegistry\": \"ghcr.io\",\n        \"ociNamespacePrefix\": \"webassembly/\"\n}\n```\n\n\n\nFor Warg registries, the JSON looks like this:\n\n```json\n{\n  \"wargUrl\": \"https://warg.wa.dev\"\n}\n```\n\n### Conventions for storing components in OCI\n\nAstute observers will note that OCI requires a specific structure for how those components are\nstored. To be clear, this does not apply to deployable artifacts (such as those used by various\nruntimes), but only to WIT components or library components. Based on the information in the\n`registry.json` file, the base URL and namespace prefix will be joined together with the namespace\nand package name to form the full URL. So if you have a custom company namespace called `acme`. Then\na package called `acme:foo` should be stored with the name `acme/foo`. If we use the `registry.json`\nfile from the example above, then the component will be stored at\n`ghcr.io/webassembly/acme/foo:0.1.0`. Please note that the tag _MUST_ be a valid semantic version or\nthe tooling will ignore it when pulling.\n\n## `wkg.toml` and `wkg.lock`\n\nWhenever `wkg` is used to fetch dependencies or build a wit package, it will automatically create a\n`wkg.lock` file. This lock file is the other standardized file that can be used by any other tooling\nintegrating in with package tooling. Because components are cross language, this file will be the\nsame for all languages. An example of this file is below:\n\n```toml\nversion = 1\n\n[[packages]]\nname = \"wasi:cli\"\nregistry = \"wasi.dev\"\n\n[[packages.versions]]\nrequirement = \"=0.2.0\"\nversion = \"0.2.0\"\ndigest = \"sha256:e7e85458e11caf76554b724ebf4f113259decf0f3b1ee2e2930de096f72114a7\"\n\n[[packages]]\nname = \"wasi:clocks\"\nregistry = \"wasi.dev\"\n\n[[packages.versions]]\nrequirement = \"=0.2.0\"\nversion = \"0.2.0\"\ndigest = \"sha256:51911098e929732f65d1d84f8dc393299f18a9e8de632d854714f37142efe97b\"\n\n[[packages]]\nname = \"wasi:io\"\nregistry = \"wasi.dev\"\n\n[[packages.versions]]\nrequirement = \"=0.2.0\"\nversion = \"0.2.0\"\ndigest = \"sha256:c33b1dbf050f64229ff4decbf9a3d3420e0643a86f5f0cea29f81054820020a6\"\n\n[[packages]]\nname = \"wasi:random\"\nregistry = \"wasi.dev\"\n\n[[packages.versions]]\nrequirement = \"=0.2.0\"\nversion = \"0.2.0\"\ndigest = \"sha256:5d535edc544d06719cf337861b7917c3d565360295e5dc424046dceddb0a0e42\"\n```\n\nOn the other hand, the `wkg.toml` file is used to configure various parts of the tooling and _is\nentirely optional_. Projects are not required to use this file. Currently, it serves two purposes:\nadding additional metadata and overriding versions/dependencies. The most common usage will be to\npoint to a local dependency:\n\n```toml\n[overrides]\n\"my:local-dep\" = { path = \"../local-dep/wit\" }\n```\n\nThere is also a `[metadata]` section that can be used to add additional metadata when building a WIT\npackage (or can be used by other language tooling). For OCI, this metadata is also used to populate\ncommon OCI annotations when publishing a package. A full example of all fields are below:\n\n```toml\n[metadata]\nauthors = [\"WasmPkg \u003cwasm-pkg@bytecodealliance.org\u003e\"]\ncategories = [\"wasm-pkg\"]\ndescription = \"WASI HTTP interface\"\nlicense = \"Apache-2.0\"\ndocumentation = \"https://docs.foobar.baz\"\nhomepage = \"https://foobar.baz\"\nrepository = \"https://github.com/bytecodealliance/wasm-pkg-tools\"\n```\n\n### OCI Annotation Mapping\n\nWhen publish to OCI via `wkg publish`, it will load the metadata from the wasm binary (which is\nautomatically added to the WIT package with `wkg wit build` if the metadata is present in the\n`wkg.toml` file). The metadata is mapped to the following OCI annotations:\n\n| `wkg.toml` Metadata Field | OCI Annotation                         |\n| ------------------------- | -------------------------------------- |\n| `description`             | `org.opencontainers.image.description` |\n| `license`                 | `org.opencontainers.image.licenses`    |\n| `homepage`                | `org.opencontainers.image.url`         |\n| `repository`              | `org.opencontainers.image.source`      |\n\nAdditionally, the `org.opencontainers.image.version` annotation is set to the version of the package being published.\n\n## Contributing\nWant to join us? Check out our [\"Contributing\" guide][contributing] and take a look at some of these\nissues:\n\n- [Issues labeled \"good first issue\"][good-first-issue]\n- [Issues labeled \"help wanted\"][help-wanted]\n\n[contributing]: https://github.com/bytecodealliance/wasm-pkg-tools/blob/master.github/CONTRIBUTING.md\n[good-first-issue]: https://github.com/bytecodealliance/wasm-pkg-tools/labels/good%20first%20issue\n[help-wanted]: https://github.com/bytecodealliance/wasm-pkg-tools/labels/help%20wanted\n\n## License\n\n\u003csup\u003e Licensed under \u003ca href=\"LICENSE\"\u003eApache-2.0 WITH LLVM-exception\u003c/a\u003e \u003c/sup\u003e\n\n\u003cbr/\u003e\n\n\u003csub\u003e Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion\nin this crate by you, as defined in the Apache-2.0 license with LLVM-exception, shall be licensed as\nabove, without any additional terms or conditions. \u003c/sub\u003e\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fwasm-pkg-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytecodealliance%2Fwasm-pkg-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fwasm-pkg-tools/lists"}