Skip to main content
← Back

wRPC Error Handling & axios in a Wasm Component Model App

The May 14, 2025 wasmCloud community call brings back the "Documentation of the Week" and "Issue of the Week" segments and digs into two practical threads in the Wasm component model. Brooks Townsend walks through the experimental error handling for custom interfaces landed in wasmCloud 1.8 — where wRPC surfaces platform-level transport errors to the guest instead of panicking — and turns the gap in its docs into an Issue of the Week. Victor Adossi then demos a new TypeScript example that runs the popular axios HTTP library inside a WebAssembly component, and the team gives kudos for a new cron job capability provider and per-component memory limits.

Key Takeaways​

  • Error handling for custom interfaces with wRPC landed in wasmCloud 1.8 behind a feature flag: wrap your return type in a result and use the wRPC error resource, and the guest receives an actionable platform-level error (a dropped socket, changed NATS credentials) instead of panicking
  • wRPC is the transport under every custom interface — when you call a component or provider in wasmCloud, the call is encoded with the component model and sent over wRPC, whether the underlying transport is NATS, TCP, or QUIC
  • A new "Issue of the Week" asks for a wasmCloud-specific RPC error-handling example built from the project's own examples (e.g. a composition example) rather than the upstream wRPC repo sample
  • The platform harness pattern — covered in a fresh blog post — separates platform concerns (filesystem, environment, proprietary internals) from user business logic, composing the two via WebAssembly composition or dynamic links over wRPC
  • Victor's axios demo shows that with a bundler (Rollup, esbuild, or Rolldown) resolving Node-style dependencies into a single JS file, the axios HTTP library compiles cleanly into a WebAssembly component via ComponentizeJS and JCO
  • The example exports the wasi:cli/run interface, so the component runs with wasmtime run, jco run, or wash, and never needs to import wasi:http/outgoing-handler because StarlingMonkey's fetch support is wired in automatically
  • Future Node standard-library support in StarlingMonkey would let much of the NPM ecosystem run in Wasm components with no changes, once shims for interfaces like filesystem and secure random are implemented
  • Community kudos went to a maintainer for a distributed cron job capability provider (pending a NATS 2.11.2 bump) and for per-component memory limits that reach all the way down to the Wasmtime engine layer

Chapters​

Meeting Notes​

Documentation of the Week: Error Handling with Custom Interfaces and wRPC​

Brooks revived the "Documentation of the Week" segment (thanks to a suggestion from Eric) to highlight new docs as features land. The first pick was the page on error handling with custom interfaces and wRPC, a feature that shipped in wasmCloud 1.8. When you define a custom interface and run a component or provider, wasmCloud converts the call to use wRPC and the component model encoding, sending it over NATS, TCP, or QUIC. Behind a feature flag (because the team is still gathering reps with it), all you do is wrap your desired return type in a result and make the error type a wRPC error resource.

The payoff is that platform-level failures become actionable. Brooks gave the baseline contrast: a hello-world function that simply returns a string would, on a dropped NATS connection or a missing link, just panic in the component because there was no way to report the failure back. With wRPC error handling, the guest receives a real error it can respond to — retry the call, sleep and try again, or bail with its own custom error implementation. Brooks framed it as the first step toward much more robust custom interface support.

Issue of the Week: A wasmCloud-Specific RPC Error Handling Example​

The docs page itself surfaced a natural "Issue of the Week": the error-handling documentation borrows its example from the upstream wRPC examples repo, but we could really use a wasmCloud-specific example. Brooks suggested adapting one of the project's own examples — for instance the composition example where a hello-world component calls another component — by redefining its WIT to demonstrate error handling in a real wasmCloud deployment. His view: there's "pretty much always" a reason to prefer an actionable platform error over a panic, so this pattern should become something developers reach for by default rather than only after finding the docs page.

The Platform Harness Pattern​

Brooks introduced a new blog post on platform engineering with Wasm and the platform harness pattern, a pattern increasingly used by teams running wasmCloud to host an internal Wasm platform. The pattern separates the implementation of platform concerns — filesystem access, environment interaction, proprietary internal systems — from user code. A shared platform harness component handles the cross-cutting platform work the same way for every application, while the individual developer's component shrinks to pure business logic. The two are composed either at build time via WebAssembly composition or at runtime via dynamic links over wRPC. Brooks noted the pattern requires no architectural change to wasmCloud itself and invited longtime community members to weigh in on whether the terminology resonates.

Demo: Running the axios HTTP Library in a TypeScript Wasm Component​

Victor Adossi demoed a pull request adding an example that uses axios — a popular alternative to fetch — inside a WebAssembly component, landing in the wasmCloud TypeScript repo where newer TS examples and best practices now live. The engine underneath is StarlingMonkey, which supports fetch; that support bubbles up through ComponentizeJS and JCO, the standard tooling wash uses to build JS/TS components. The catch is which libraries you can pull in: pure-JavaScript libraries work, but anything that compiles native bindings (think node-gyp) can't, because native linking doesn't translate to a Wasm component.

axios fits the bill, with a little tweaking. The key piece is the Rollup config — any bundler works (esbuild, Rollup, or the up-and-coming Rolldown) — set up to resolve Node-style require/resolution and emit a single JavaScript file, because the Wasm JS toolchain won't replicate Node's package resolution on its own. The component code itself is short: it makes a basic axios call out to a JSON placeholder service and writes the stringified response to stdout. Crucially, the WIT interface exports wasi:cli/run (so it runs with wasmtime run, jco run, or wash) and never imports wasi:http/outgoing-handler — JCO adds that import automatically because fetch is always available, which can surprise developers wondering how a WASI component makes HTTP calls it never asked for.

axios vs fetch, the NPM Ecosystem, and the Quickstart​

Asked by Brooks, Victor confirmed axios is primarily for outgoing HTTP; people reach for it because of better defaults, more automatic behavior, and — as Aditya noted in chat — notably better error handling than fetch. Brooks observed that as more "libraries just work" examples accumulate, existing JavaScript that uses axios could compile to a component speaking wasi:http with little more than a bundling step and no source changes. Victor tied this to the bigger picture: planned Node standard-library support in StarlingMonkey would, in theory, unlock much of the NPM ecosystem in Wasm components automatically — once someone implements shims for platform-dependent interfaces like filesystem access and secure random. He closed by pointing newcomers to the HTTP hello-world example in the quickstart, which shows both the fast path (wash dev) and a slower, manual path that teaches what wash dev does under the hood — a nod to the wasmCloud lattice. Jochen Rau praised the value of being able to walk through the individual steps visibly rather than treating it as magic.

WebAssembly News and Updates​

This call captures the WebAssembly component model maturing on two fronts at once. On the runtime side, wRPC is quietly becoming the universal transport beneath wasmCloud's custom interfaces, and its new error-handling support turns transport failures into recoverable, typed errors instead of panics. On the language side, the JavaScript/TypeScript story keeps closing the gap with native Node: StarlingMonkey, ComponentizeJS, and JCO already make popular libraries like axios compile into components, and planned Node standard-library shims point toward running large swaths of the NPM ecosystem in WebAssembly components unmodified. For ongoing updates, follow the wasmCloud blog and the Bytecode Alliance.

What is wasmCloud?​

wasmCloud is a CNCF project that lets you build applications using WebAssembly components and deploy them anywhere — cloud, edge, or Kubernetes clusters. It uses the WebAssembly component model to let you write business logic in any supported language (Rust, Go, Python, TypeScript, C#, and more) while the platform handles capabilities like HTTP, messaging, and key-value storage through a pluggable provider architecture. wasmCloud's host is built on Wasmtime, and connects components and providers over wRPC so a call can travel over NATS, TCP, or QUIC transparently. With built-in OpenTelemetry observability and Kubernetes integration, wasmCloud bridges WebAssembly's portable, sandboxed execution model and production cloud-native infrastructure.

Topic Deep Dive: The Wasm Component Model​

Both of this meeting's threads trace back to the Wasm component model. The component model is what lets wasmCloud encode a custom interface call and ship it over wRPC to any transport — and it's why adding a result with a wRPC error resource gives the guest a typed, actionable error across that boundary rather than an opaque crash. The same model is what makes Victor's axios example portable: a TypeScript component compiled through ComponentizeJS and JCO declares its imports and exports as typed WIT interfaces, so the host can wire in fetch/wasi:http without the component ever asking for it. And it's the foundation of the platform harness pattern, where a platform component and a business-logic component are composed through typed interfaces without either trusting the other's internals. As more of the JavaScript ecosystem reaches the component model — and as error handling becomes first-class — the promise of "write a component once, run it in any host and any language" gets steadily closer.

Who Should Watch This​

This call is especially valuable for wasmCloud developers using custom interfaces who want robust, recoverable error handling instead of panics (start with the error-handling walkthrough at 1:02), JavaScript and TypeScript developers curious whether their favorite NPM libraries can run in WebAssembly components (Victor's axios demo at 13:29), and platform engineers evaluating how to separate platform concerns from user code with the platform harness pattern (the blog discussion at 10:16).

Up Next​

Future calls will follow the threads opened here: feedback on the cron job capability provider once it lands on NATS 2.11.2, the rollout of per-component memory limits pending a look at control-interface changes, and contributions to the new "Issue of the Week" for a wasmCloud-specific RPC error-handling example. Expect the "Documentation of the Week" and "Issue of the Week" segments to continue as a recurring way to surface new features and good first contributions.

Get Involved​

wasmCloud is a CNCF project and contributions are welcome. Join the community:

Full Transcript​

Read the complete transcript with speaker labels and timestamps:

Read the full transcript →