CosmJS: a Cosmos SDK client split into pick-and-choose packages

Why a Cosmos client would not write its own codec

Working with a Cosmos SDK chain from JavaScript is not a matter of posting JSON to an endpoint. A client has to encode a message, sign it with a key, submit the transaction, and decode the result, and every one of those steps has sharp edges that are easy to get subtly wrong. CosmJS exists to put those edges in a library. The README describes it as the tool to power JavaScript based client solutions, and the range it names is telling: web apps and explorers, browser extensions, and server side clients such as faucets and scrapers. The ecosystem it targets is the Cosmos one, where a chain exposes a Stargate endpoint and the transaction format follows the SDK's Protobuf based rules rather than the older Amino encoding. The project is developed in TypeScript, and the name is explained in the README as Cosm for Cosmos and JS for runs everywhere. The point of that naming is the constraint: the same code has to work in a Node script, in a browser tab, and inside an extension, which is why the supported environment list and the WebAssembly detail below matter as much as the API surface does.

What each package in the @cosmjs namespace does

CosmJS is a monorepo, and the README is careful to call it that: many smaller npm packages published under the @cosmjs namespace, from which a user picks a subset. The table in the README gives the shape of the whole thing. The stargate package is a client library for Cosmos SDK 0.40 and later, which is the Stargate generation of the SDK, and it is the package most projects start with. The cosmwasm package is a client for Stargate chains that have the CosmWasm module enabled, so it adds contract specific handling on top of the Stargate base. The crypto package covers the cryptography a blockchain project needs: hashing with SHA-2, Keccak256 and Ripemd160, signing with secp256k1 and ed25519, HD key derivation under BIP-39 and SLIP-0010, and key derivation and symmetric encryption functions including PBKDF2, Argon2 and XChaCha20Poly1305. The encoding package holds encoding helpers, the math package offers safe integers and decimals for financial amounts, and the faucet package is a faucet application for node.js, which is the one member of the set that is an application rather than a library.

Adding the packages to a project and taking a first step

The packages are published to npm under the @cosmjs namespace, so consuming them means depending on the one or two you actually need, and the README links the whole namespace for that list. For working on the library itself, the repository is a Yarn workspace whose root package.json declares the workspace globs.

  "workspaces": [
    "packages/*"
  ],

The root scripts then fan out across those workspaces in topological order, so a single command at the root runs the same task everywhere.

    "build": "yarn workspaces foreach --all --topological-dev --parallel --verbose run build",
    "test": "yarn workspaces foreach --all --topological-dev --parallel --verbose run test",
    "lint": "eslint --max-warnings 0 .",

For a first real use, the README does not give a quick start script, so the practical entry points are the guided tour gist, which walks through Stargate usage against Cosmos SDK 0.41 applications such as gaia 4, and the spec files, one of which the README links as packages/stargate/src/signingstargateclient.spec.ts for an example of real client usage. Start with a chain you can query freely, keep the first call read only, and check the Node.js version before anything else, because the supported environment list starts at Node.js 20 and the whole crypto path depends on WebAssembly support being present in the runtime.

Modularity is a dependency decision, not a packaging preference

The README is explicit that the modularity and the clean dependency tree in the monorepo are deliberate, and that the point is to let users pick exactly what they need. The dependency graph is published as an image, one that shows only the @cosmjs packages and another that adds application runtime dependencies, and the comment in the README shows those images are produced with a tool called depsight from the npm packages. A clean tree matters more here than in most libraries because of what the crypto package drags in. Signing code, key derivation and WebAssembly binaries are a large dependency surface, and a project that only needs to format an address or convert a decimal should not have to install them. The math package makes that point concretely, since safe integers and decimal handling for financial amounts is the kind of code a small script needs and a project should not write itself. The alternative to this approach is the single package that pulls everything in, which is simpler to install and much heavier to keep, and the difference shows up first in a cold install and later in every dependency audit.

The runtime list, ES2020, and where WebAssembly comes in

The README lists the supported environments and the constraints that come with them. Node.js 20 and later is the first. Modern browsers are the second, namely Chromium, Firefox and Safari, with Internet Explorer and Edge Legacy explicitly excluded. Browser extensions in Chromium and Firefox are the third. The JavaScript target standard is ES2020, and certain cryptographic functions are implemented with WebAssembly. That last point is the one with a practical consequence, because an environment without WebAssembly support needs something different, and the README says the project is willing to work on a solution with swappable implementations when that is the case. The exclusion of Internet Explorer is also framed as a boundary the maintainers are open to moving, with the stated condition that the request does not ask for Internet Explorer support. For an extension or a browser app, that list is the compatibility contract: if you target an embedded browser or an older corporate build, you need to check it against the list rather than assume a modern target.

Reading the hosted API docs, the guided tour, and the custom module notes

The README points at three separate places to learn, and each answers a different question. The first is a guided tour, a gist, that walks through examples using the Stargate package against Cosmos SDK 0.41 applications such as gaia 4. The second is the hosted API documentation at cosmos.github.io/cosmjs, which the README describes as hard to read and as requiring some TypeScript understanding. It is described as helpful for advanced use cases, and there is a caveat attached to it that matters for anyone pinning versions: the documentation is auto-generated from the current main branch and can occasionally diverge from the latest release. The third is a document inside the stargate package, CUSTOM_PROTOBUF_CODECS.md, that covers using your own custom modules with CosmJS on Stargate chains, which is the route for a chain whose messages the default codecs do not know about. The README also points to the test files as further examples of usage, so the fastest way to see a working call sequence is to read a spec file rather than to guess at the API.

Webpack 5 needs explicit Node type and module handling

There is a short configuration note in the README that only bites browser bundler users. With Webpack 4, certain Node.js types and modules were simply replaced with re-implementations for the browser. With Webpack 5, you have to be explicit about that usage instead, and the README gives a configuration for 0.28 and later.

module.exports = [
  {
    // ...
    plugins: [
      ...,

The snippet is truncated in the README itself, so treat it as the shape of the configuration rather than the finished file. The practical takeaway for a browser or extension build is that the Node built in modules used by the crypto and encoding paths have to be declared rather than assumed, and that a browser bundle of CosmJS is a configuration task, not just an import change. Since the same libraries are used from Node, a project that only touches the server side will not notice this at all, which is why it is easy to discover late, after the first extension build fails.

Apache-2.0, the 0.x line, and a release pace that has slowed

The licence is Apache-2.0, which permits use, modification and redistribution in commercial and closed source work, and it carries the standard conditions around stating changes and preserving the licence and notice files. The repository has a LICENSE file and a NOTICE file, so those obligations are already covered if you vendor the code rather than depend on the published packages. On versions, the recent releases are 0.39.0 on 2026-05-04, 0.38.0 on 2025-12-30 and 0.37.0 on 2025-10-29, and the last push was on 2026-05-04, so the project is current but on a 0.x version line where the API can still move between minor releases. The repository layout shows what a large monorepo costs. It is a Yarn workspace setup with a packages directory and a yarn.lock, and the root package.json drives everything through workspace wide commands, so the format, lint, test, coverage, build and docs scripts all fan out across packages in topological order. Two extra files are worth noticing, .pnp.cjs and .pnp.loader.mjs, which point to a Plug'n'Play resolver, and a .nycrc.yml with a codecov.yml for coverage reporting. Test scripts exist for Firefox and Chrome separately, so browser behaviour is exercised deliberately rather than assumed.

Editorial conclusion

CosmJS fits a TypeScript team building a wallet, explorer, faucet, scraper or browser extension against a Cosmos SDK chain, and especially a team that wants the signing and encoding code out of its own repository while keeping the dependency surface small. It does not fit a project that needs a stable 1.0 contract, since the published line is still 0.x, and chains on much older SDK versions are outside the 0.40+ range the Stargate package targets, where a custom module also needs the protobuf codec route in the package's CUSTOM_PROTOBUF_CODECS.md document. Before you depend on it, read the API documentation page for the exact function you need, because the hosted reference is generated from the main branch and can describe a different state of the code than the release you installed.

Frequently asked questions

Official sources

1. cosmos/cosmjs on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases