DEV Community: Tophe

Writing components in TypeScript with jco - WebAssembly Component Model

Tophe — Fri, 19 Sep 2025 07:33:20 +0000

This part isn’t required to use the project — but if you want to experiment with writing plugins in TypeScript, here’s how it works.

The downsides of writing plugins in TypeScript is mostly that your .wasm file will be much larger than the one compiled from rust or C:

~100KB of wasm for the rust plugin

~12MB of wasm for the TypeScript plugin

The reason is that a JavaScript runtime needs to be embedded in the .wasm file, which is not the case for the rust plugin.

More about the SpiderMonkey runtime embedding.

It is setup in the project, however, I don't rely on plugins written in TypeScript for the moment as would be too much of a performance hit (mostly for the web host).

import type { plugin as pluginApi } from "./types/plugin-api";

export const plugin: typeof pluginApi = {
  name: () => "echo",
  man: () => "...",
  run: (payload: string) => {
    return {
      status: "success",
      stdout: payload,
      stderr: undefined,
    };
  },
};

The jco toolchain helps compile JS/TS code into WebAssembly components.

Build Steps

Generate TypeScript types:

cd packages/plugin-name
jco types --world-name plugin-api --out-dir ./src/types ../../crates/pluginlab/wit

Bundle your TS code into a single file (using rolldown or another bundler).

rolldown ./src/component.ts --file ./dist/component.js

Componentize it:

jco componentize ./dist/component.js \
  --wit ../../crates/pluginlab/wit \
  --world-name plugin-api \
  --out ./dist/component.wasm \
  --disable http --disable random

(Optional) Optimize the resulting .wasm file:

jco opt ./dist/component.wasm -o ./dist/component-opt.wasm

Example: `package.json` Scripts

{
  "wit-types": "jco types ...",
  "bundle": "rolldown ...",
  "componentize": "jco componentize ...",
  "build": "npm run wit-types && npm run bundle && npm run componentize",
  "optimize": "jco opt ...",
  "typecheck": "tsc --noEmit"
}

📎 Here are links to the implementation of the plugin-echo plugin in TypeScript in the project.

Writing components in Go with TinyGo compiler - WebAssembly Component Model

Tophe — Fri, 19 Sep 2025 07:32:56 +0000

Setup

Required tools for TinyGo WebAssembly Component Model support:

TinyGo compiler v0.39.0+: Compiles Go code to WebAssembly components
wkg: Resolves and bundles WIT dependencies into a single package
wasm-tools: Converts WebAssembly modules to components

Build Process

Go plugins require a specific build process due to TinyGo's Component Model requirements:

1. Prepare WIT files for TinyGo

TinyGo has specific requirements that differ from other languages. The prepare-wit-files.sh script (a custom script for this project) copies WIT files from crates/pluginlab/wit to go_modules/wit and uncomments TinyGo-specific lines:

./scripts/prepare-wit-files.sh -i crates/pluginlab/wit -o go_modules/wit -s "SPECIFIC TinyGo"

Why this workflow exists: The go_modules/wit directory is gitignored and contains modified versions of the WIT files specifically for TinyGo. This workflow maintains crates/pluginlab/wit as the single source of truth for all WIT definitions, while automatically generating TinyGo-compatible versions.

Why this is needed: The wasip2 target of TinyGo assumes that component is targeting wasi:cli/command@0.2.0 and requires explicit inclusion of WASI imports. The script searches for lines containing "SPECIFIC TinyGo" and uncomments them:

world plugin-api {
  // The wasip2 target of TinyGo assumes that the component is targeting
  // wasi:cli/command@0.2.0 world (part of wasi:cli), so it needs to
  // include the imports from that world.
  // It's only included for the versions of the wit files destined for TinyGo.
- // include wasi:cli/imports@0.2.0; // SPECIFIC TinyGo - DO NOT CHANGE THIS LINE
+ include wasi:cli/imports@0.2.0; // SPECIFIC TinyGo - DO NOT CHANGE THIS LINE
  import http-client;
  import host-state-plugin;
  export plugin;
}

2. Bundle WIT dependencies with wkg

Why wkg is used: TinyGo cannot resolve WIT imports on its own - it needs all dependencies to be either bundled into a single WASM file or pre-resolved into a local directory. For example, when TinyGo sees include wasi:cli/imports@0.2.0;, it doesn't know where to find that external package or what's inside it. The wkg tool handles dependency resolution by fetching all imported WIT interfaces and creating a complete WIT package:

cd go_modules/
wkg wit build

This creates repl:api.wasm containing all the WIT definitions needed by the plugin. The command also generates a wkg.lock file that locks the dependency versions for reproducible builds.

3. Generate Go bindings

Use wit-bindgen-go to generate Go code from the bundled WIT package:

cd go_modules/plugin-name/
go tool wit-bindgen-go generate --world plugin-api --out internal ../repl:api.wasm

This creates the internal/ directory with all the generated Go bindings for the plugin interfaces.

4. Compile with TinyGo

TinyGo compiles the Go code directly to a WebAssembly component:

cd go_modules/plugin-name/
tinygo build -target=wasip2 --wit-package ../repl:api.wasm --wit-world plugin-api -o plugin-name-go.wasm main.go

File Structure

Project organization: Go plugins follow this structure in the repo:

go_modules/
  wit/                           # Modified WIT files for TinyGo
    plugin-api.wit               # Contains TinyGo-specific includes
    shared.wit                   # Shared types and interfaces
    host-api.wit                 # Host API definitions
  repl:api.wasm                  # Bundled WIT package (from wkg)
  wkg.lock                       # Lock file for WIT dependencies (from wkg)
  plugin-echo/                   # Plugin directory
    go.mod                       # Go module with wit-bindgen-go tool
    main.go                      # Plugin implementation
    internal/                    # Generated bindings (from wit-bindgen-go)
      repl/api/plugin/           # Plugin interface bindings
      repl/api/transport/        # Transport type bindings
      wasi/                      # WASI interface bindings
    plugin-echo-go.wasm          # Final WebAssembly component

Plugin Implementation

Standard pattern: Go plugins use the init() function to register their exports, following the WebAssembly Component Model pattern:

package main

import (
    "webassembly-repl/plugin-echo/internal/repl/api/plugin"
    "webassembly-repl/plugin-echo/internal/repl/api/transport"
    "go.bytecodealliance.org/cm"
)

func init() {
    plugin.Exports.Name = func() string {
        return "echogo"
    }
    plugin.Exports.Man = func() string {
        return `... some man text ...`
    }
    plugin.Exports.Run = func(payload string) cm.Result[plugin.PluginResponse, plugin.PluginResponse, struct{}] {
        response := plugin.PluginResponse{
            Status: transport.ReplStatusSuccess,
            Stdout: cm.Some(payload),
            Stderr: cm.None[string](),
        }
        return cm.OK[cm.Result[plugin.PluginResponse, plugin.PluginResponse, struct{}]](response)
    }
}

// main is required for the wasip2 target
func main() {}

Go Module Configuration

Required setup: The go.mod file must include the wit-bindgen-go tool as a Go tool dependency:

module webassembly-repl/plugin-echo

go 1.24

tool go.bytecodealliance.org/cmd/wit-bindgen-go

// ... other dependencies

This allows the project to use go tool wit-bindgen-go commands for generating bindings.

📎 Here are links to:

the go_modules directory that contains the Go plugins
the justfile file that contains the build commands for Go plugins
PR#16 - Add Go Language Plugin Support

Writing components in C with WASI SDK - WebAssembly Component Model

Tophe — Fri, 19 Sep 2025 07:29:50 +0000

What is WASI-SDK?

Unlike Rust with cargo-component, C/C++ lacks an integrated toolchain for building WebAssembly components. The WASI SDK provides the essential tooling needed to compile C code to WebAssembly.

The WASI SDK includes:

clang compiler configured with a WASI sysroot (complete set of target platform headers and libraries) for the wasm32-wasi target
WASI-enabled C standard library (libc) that implements WASI interfaces
Cross-platform support for different operating systems and architectures
Preview 2 compatibility for building modern WebAssembly components

This allows you to write C plugins that can access filesystem, networking, and other system resources through WASI interfaces, just like Rust plugins.

WASI-SDK Setup

The project uses a custom script just dl-wasi-sdk that acts like a package manager, automatically downloading and extracting the correct version of the WASI SDK for your OS/architecture into c_deps/ (which acts like a node_modules for C dependencies).

How to write a C plugin

Build Process

C plugins are built using a two-step process:

Generate bindings: wit-bindgen c ./crates/pluginlab/wit --world plugin-api --out-dir ./c_modules/plugin-name creates the C bindings from your WIT interface
Compile and convert: Use the WASI SDK's clang to compile C code to a WebAssembly module (P1), then convert it to a P2 component

The build process:

Compiles component.c, plugin_api.c, and plugin_api_component_type.o to a WebAssembly module with -mexec-model=reactor:

  ./c_deps/wasi-sdk/bin/clang component.c plugin_api.c plugin_api_component_type.o \
    -o plugin-name-c.module.p1.wasm -mexec-model=reactor

Converts the P1 module to a P2 component using wasm-tools component new:

  wasm-tools component new plugin-name-c.module.p1.wasm -o plugin-name-c.wasm

File Structure

The C plugins follow this structure in the repo:

c_deps/                           # WASI SDK installation
c_modules/
  plugin-echo/                    # Plugin directory
    component.c                   # Your plugin implementation
    plugin_api.c                  # Generated bindings (from wit-bindgen)
    plugin_api.h                  # Generated header (from wit-bindgen)
    plugin_api_component_type.o   # Generated object file (from wit-bindgen)
    plugin-echo-c.module.p1.wasm  # Compiled WebAssembly module (P1)
    plugin-echo-c.wasm            # Final WebAssembly component (P2)

Plugin Implementation

The C plugin implements the same interface as the Rust version, with function signatures generated from the WIT interface by wit-bindgen:

exports_repl_api_plugin_name() corresponds to fn name() -> String
exports_repl_api_plugin_man() corresponds to fn man() -> String
exports_repl_api_plugin_run() corresponds to fn run(payload: String) -> Result<PluginResponse, ()>

Here's the key implementation details - plugin-echo/component.c:

#include "plugin_api.h"
#include <string.h>
#include <stdlib.h>

void exports_repl_api_plugin_name(plugin_api_string_t *ret)
{
    // Populate ret with "echoc" as the plugin name
    // plugin_api_string_dup() allocates new memory and copies the string
    plugin_api_string_dup(ret, "echoc");
}

void exports_repl_api_plugin_man(plugin_api_string_t *ret)
{
    // Populate ret with the manual text for the echo command
    // plugin_api_string_dup() allocates new memory and copies the string
    const char *man_text = "some man text ...\n";
    plugin_api_string_dup(ret, man_text);
}

bool exports_repl_api_plugin_run(plugin_api_string_t *payload, exports_repl_api_plugin_plugin_response_t *ret)
{
    // Set status to success (0 = success, 1 = error)
    ret->status = REPL_API_TRANSPORT_REPL_STATUS_SUCCESS;

    // Set stdout to contain the payload
    // is_some = true means the optional string has a value
    ret->stdout.is_some = true;

    // Create a properly null-terminated string from the payload
    // The payload has ptr and len, we need to ensure it's null-terminated
    char *temp_str = malloc(payload->len + 1);
    if (temp_str == NULL)
    {
        // Handle allocation failure
        ret->stdout.is_some = false;
        ret->stderr.is_some = false;
        return false;
    }

    // Copy the payload data and null-terminate it
    memcpy(temp_str, payload->ptr, payload->len);
    temp_str[payload->len] = '\0';

    // Use plugin_api_string_dup to create the output string
    plugin_api_string_dup(&ret->stdout.val, temp_str);

    // Free our temporary string
    free(temp_str);

    // Set stderr to none (no error output)
    ret->stderr.is_some = false;

    // Return true for success (false would indicate an error)
    // This corresponds to Ok(response) in the Rust Result<T, ()> pattern
    return true;
}

Memory Management Notes:

Input parameters (like payload) are owned by the runtime - they MUST NOT be freed by the plugin
Output parameters (like ret) are populated by the plugin, freed by the runtime
plugin_api_string_dup() allocates new memory for string copies
The generated _free functions handle cleanup automatically

Key Differences from Rust:

Manual memory management for temporary strings
Explicit handling of string length vs null termination
Boolean return values instead of Rust's Result<T, ()> pattern
Direct manipulation of the generated C structs

📎 Here are links to:

the plugin-echo C implementation and the plugin_api.h header file
PR#6 - Add C Language Plugin Support

Building components in multiple languages - WebAssembly Component Model

Tophe — Fri, 19 Sep 2025 07:29:10 +0000

The Bytecode Alliance organization maintains a very useful website about The WebAssembly Component Model and each associated languages has also a page on it.

Now that I've explained the purpose of the project and its architecture in the previous section, I will focus on concrete examples of implementing multiple languages in the same project and sharing some tips I had to learn the hard way.

Before choosing a language for compiling to WebAssembly, you should consider the impact it has on the final size of your wasm file - here is a comparaison of the size of the echo plugin in the different languages:

Language	Size
C	56K
Rust	72K
Go (with TinyGo)	332K
TypeScript	12M

Looking at the table above, the differences in .wasm file size come from the language and how much runtime support it brings:

C and Rust produce very small files (56K and 72K here) because they compile directly to efficient machine-level code without needing to ship a runtime. Rust is slightly larger due to safety checks and standard library overhead, but both remain compact.
Go (TinyGo) is larger (332K) because Go normally includes a large runtime. TinyGo reduces this compared to regular Go, but you still pay a higher size cost than C/Rust.
TypeScript is much bigger (12M) because it doesn’t compile directly to Wasm. Instead, you’re shipping a whole JavaScript engine runtime inside your .wasm file.

I've already covered creating Rust components, let's now focus on C, Go and TypeScript.

Building a plugin system - WebAssembly Component Model

Tophe — Fri, 19 Sep 2025 07:28:55 +0000

The WebAssembly Component Model (WCM) is still very early days, but it's a very promising technology. However, the examples out there are either too simple or too complex.

The goal of my project topheman/webassembly-component-model-experiments is to demonstrate the power of WCM — with more than just a simple "Hello, World".

1. Introduction

This project is an experiment to explore and understand the WebAssembly Component Model through a concrete application: a modular REPL where each command is implemented as a Wasm component.

The goals were:

Build a real-world project using WebAssembly Component Model.
Evaluate DX, tooling, portability, and interoperability.
Use WIT files to define interfaces and enforce isolation/sandboxing.
Run the same plugin code (examples in Rust, C, Go and TypeScript) across CLI (Rust) and browser (TypeScript) hosts.

That way, it would demonstrate features like:

You could run a third-party plugin that is written in a different language
Without having to trust the author, since the plugins are sandboxed and isolated from the host

I'll first go over the basics of WebAssembly Component Model, then dig into the project and its architecture — so you get a more hands-on understanding of the technology through an actual use case.

🧪 Try the online demo (web version)

▶️ Example of running the CLI pluginlab 👇

2. From WebAssembly MVP to Component Model

WebAssembly has evolved over time:

WebAssembly → WASI → WebAssembly Component Model

WebAssembly MVP (2017)

WebAssembly began as a low-level binary format — portable, secure and fast — but everything had to be wired manually when dealing with multiple modules.

WASI (WebAssembly System Interface)

WASI added a way for Wasm modules to interact with the host (files, networking, etc.) securely. It has evolved through previews:

Preview 1 (deprecated): Initial WASI specification
Preview 2 (current): Stable APIs used in this project
Preview 3 (future): Enhanced capabilities like async operations

But WASI didn't really solve how to compose multiple modules easily.

WebAssembly Component Model

That’s where WCM comes in:

WIT (WebAssembly Interface Types): define interfaces with strong typing.
Componentization: encapsulate logic into reusable, sandboxed units.
Typed imports/exports: clean separation of responsibilities.

It makes it much easier to build systems from Wasm components — like plugins — without glue code everywhere.

3. Defining Interfaces with WIT

WIT (WebAssembly Interface Types) is an IDL (Interface Description Language). It defines the contract between components and host.

Here’s a simplified version of the plugin-api.wit file used in this project:

package repl:api;

interface plugin {
  enum repl-status { success, error }

  record plugin-response {
    status: repl-status,
    stdout: option<string>,
    stderr: option<string>,
  }

  name: func() -> string;
  man: func() -> string;
  run: func(payload: string) -> result<plugin-response>;
}

interface http-client {
  record http-header { name: string, value: string }

  record http-response {
    status: u16,
    ok: bool,
    headers: list<http-header>,
    body: string,
  }

  get: func(url: string, headers: list<http-header>) -> result<http-response, string>;
}

world plugin-api {
  import http-client;
  export plugin;
}

A WIT world is a higher-level contract that describes a component's capabilities and needs.

The world plugin-api enforces the following:

The plugin (Wasm Component) implements the plugin interface.
The host provides the http-client interface.

This separation lets plugins remain unaware of the host environment (CLI or browser).

4. Creating WebAssembly Components in Rust

For C, Go and TypeScript, see the following posts.

With Rust, you use cargo-component (which relies on wit-bindgen) to generate bindings from your WIT definitions. Here’s a stripped-down version of the echo plugin:

mod bindings;
use crate::bindings::exports::repl::api::plugin::{Guest, PluginResponse, ReplStatus};

struct Component;

impl Guest for Component {
  fn name() -> String { "echo".to_string() }
  fn man() -> String { "Some man page".to_string() }
  fn run(payload: String) -> Result<PluginResponse, ()> {
    Ok(PluginResponse {
      status: ReplStatus::Success,
      stdout: Some(payload),
      stderr: None,
    })
  }
}

bindings::export!(Component with_types_in bindings);

If you need to do networking or filesystem access:

networking: you will use the http-client interface, the host will provide its own implementation
filesystem: you will use the standard library of your language, like std::fs::* in Rust or fs.readFileSync() in TypeScript - the host will provide transparent bindings to the host's filesystem

Build process

cargo component build -p plugin-echo

This will generate a target/wasm32-wasip1/debug/plugin_echo.wasm file.

5. Hosts: CLI and Browser

🔧 CLI Host (Rust)

The CLI host (pluginlab) uses wasmtime, which supports WebAssembly Component Model natively, as its underlying runtime.

pluginlab implements security and functionality features on top of wasmtime's capabilities, including:

Filesystem sandboxing via flags (--allow-read, --allow-write, --dir, etc.)
Network access via --allow-net (you can also whitelist domains/IPs)
Plugin loading (--plugins) from local or HTTP sources
REPL logic injection (--repl-logic)

The http-client interface is implemented using the reqwest crate and only works if networking is allowed. Calls to http-client.get() will fail without --allow-net.

Since the reqwest crate is async, we need to use wasmtime_wasi::p2::add_to_linker_async when we link a plugin component so that it will share the same async runtime as the host, otherwise, you will get Cannot start a runtime from within a runtime. error (see d057660).

Handling mismatched versions

To work together, the host and the plugins must share the same version of the WIT file, otherwise, the bindings will not match and you will get a runtime error.

The CLI host will handle such errors and tell the user to update their cli - more infos on PR#10.

🌐 Browser Host (TypeScript)

Since browsers only support Wasm modules, not components, we use jco transpile in the build step to convert the compiled .wasm components into a compatible format for the browser:

.js glue code (exports typed functions)
.core.wasm files (transpiled WebAssembly modules)

Example of call to jco to transpile a component:

jco transpile --no-nodejs-compat --no-namespaced-exports public/plugins/plugin_echo.wasm -o ./src/wasm/generated/plugin_echo/transpiled

Networking

Because jco doesn’t support async functions yet, the http-client interface is implemented with a synchronous XMLHttpRequest wrapper inside the browser host.

This implementation lives in src/wasm/host/http-client.ts, and is mapped via the build system so that it will be used when the repl:api/http-client interface is called:

Filesystem

Browsers don’t have access to a real filesystem, so a virtual one is injected at runtime. I use @bytecodealliance/preview2-shim/filesystem to mount an in-memory virtual FS that shims wasi:filesystem.

A CLI script prepareFilesystem.ts generates a JSON structure from a directory. That structure is passed to @bytecodealliance/preview2-shim/filesystem#_setFileData at runtime so that plugins can access a filesystem without changing their code.

You can check it out on the demo and try commands like ls or cat README.md to see it in action.

Local fork of `@bytecodealliance/preview2-shim`

@bytecodealliance/preview2-shim doesn't support WRITE operations properly out of the box (see issue #12).

I forked the project and added support for WRITE operations, you can check the implementation details in the PR#15, that way, plugins like tee can write to the filesystem in the browser (see demo).

6. REPL Logic

The REPL logic itself is also a Wasm component (repl-logic-guest.wasm). It handles:

Variable expansion (export VAR=value, echo $VAR)
Help and man routing
Plugin dispatching

Why a separate REPL logic component? Because it’s reused between CLI and browser — no need to duplicate logic accross platforms.

WIT definition

interface repl-logic {
  record plugin-response {
    status: repl-status,
    stdout: option<string>,
    stderr: option<string>,
  }

  record parsed-line {
    command: string,
    payload: string,
  }

  variant readline-response {
    to-run(parsed-line),
    ready(plugin-response),
  }

  readline: func(line: string) -> readline-response;
}

Implemented in crates/repl-logic-guest and compiled to a repl-logic-guest.wasm file.

Input Flow Example

When the user prompts the REPL, the host sends the input to the readline function exposed by the repl-logic-guest component, which returns a readline-response. Then there are two possibilities:

Reserved Command: If the input is a reserved command (like help, man, list-commands or export ), the repl-logic-guest component executes the command directly and returns the output as a readline-response.ready(plugin-response) variant which will be displayed to the user by the host.
Plugin Command: Otherwise, the repl-logic-guest component returns a readline-response.to-run(parsed-line) variant with the parsed payload to be executed by a plugin.
- Then the host dispatches this payload to the run function of the targetted plugin which will return a readline-response.ready(plugin-response) variant which will be displayed to the user by the host.

This back and forth is necessary because the run of each plugin is only accessible in the host (not via the repl-logic-guest component), since it's the host which instantiates the plugins.

Here is a sequence diagram that illustrates the flow:

Reserved Command (`help`)

Plugin Command (`echo Hello`)

These flows show the system's ability to handle both built-in logic and plugin delegation using the same architecture.

7. Testing and CI/CD

Testing

The project includes comprehensive end-to-end (e2e) tests that ensure any regression is caught without being tightly coupled to any specific implementation. These tests cover both the terminal REPL and the web interface.

Terminal E2E Tests

Uses rexpect for testing the CLI REPL behavior
Tests plugin loading, execution, and error handling
Ensures the terminal interface works correctly across different scenarios

Web E2E Tests

Uses Playwright for testing the web interface
Tests plugin functionality in the browser environment
Validates the web-host integration with WebAssembly components

CI/CD

The project maintains a robust CI/CD pipeline that covers multiple programming languages and targets:

Multi-Language Pipeline

Rust: CLI application with WebAssembly target + Plugins
TypeScript/Node.js: Web interface and tooling
Go: Plugin implementations with TinyGo
C: Plugin implementations with WASI SDK

Checkout the source code of the CI/CD pipeline in the .github/workflows folder.

Automated Testing

E2E tests run automatically for both CLI and web targets

Deployment Automation

Website is automatically published on successful builds
Release drafts are automatically created when git tags are pushed
Pre-uploaded wasm plugin files are included in releases (that way, plugins from previous versions are still available)
View releases: GitHub Releases

Cross-compilation & Publication to Hombrew tap automation PR#17

When tagged, the cli is cross-compiled to linux/macos - (Intel/ARM)
Uploaded to a draft release
When the release is published, the version is published to my Homebrew tap repo

8. Conclusion

This project was a playground to:

Go deep into the WebAssembly Component Model
Work with WIT interfaces, sandboxing, and plugin-based architecture
Share logic between CLI and browser using Wasm components

What's next?

This project was the necessary step to understand the Wasm Component Model, get familiar with the tooling and the ecosystem and make a real-world project with it.

The goal was never to build a full-featured shell, but to focus on WASM Components, this project will eventually be the foundation for a more advanced project.

This project will let me keep experimenting with WebAssembly Component Model as new features, languages, tooling, and versions come out. It's basically my playground for testing new ideas and concepts.

Resources

Repo: topheman/webassembly-component-model-experiments
A few PRs that are worth checking out:
Website: topheman.github.io/webassembly-component-model-experiments
Previous work with WebAssembly:
- topheman/bevy-rust-wasm-experiments: Basic video game in rust that compiles both to a binary file and a web (via WebAssembly, binding the accelerometer and gyroscope sensors from the mobile device)
- topheman/webassembly-wasi-experiments: Discover WebAssembly System Interface (WASI) with C/Rust targetting NodeJS, python, Wasmtime and the browser
- topheman/rust-wasm-experiments: Discover how to use Rust to generate WebAssembly, called by JavaScript
- 📺🇫🇷 Utiliser WebAssembly, dès aujourd'hui - ParisJS #86
Bytecode Alliance - The WebAssembly Component Model

React Server Components in Practice: Building a fake E-commerce Site with Next.js 15 latest features

Tophe — Tue, 04 Mar 2025 15:17:54 +0000

👀 See the demo here - 👨‍💻 See the source code here

For the last 18 months, in the react ecosystem, we have been witnessing the rise of server components.

It's not the only new concept that has been introduced. Metaframeworks like Next.js have been relying for months on alpha/beta/RC versions of react 19, preparing for features like:

RSC (React Server Components)
Server Actions
Streaming
New caching strategies
Partial Prerendering

The stable version of react 19 shipped in December 2024 (see their blog post).

Experiments
Features of the project
Tech stack
Implementation
- Experimental flags
- Server components
  - Layout
  - QR Code Generation
  - Header / UserIcon
  - Header / SearchCombobox
  - Category page
  - Search Page / Product Page
- Mixing RSC and client components
- Server actions
- Progressive Enhancement
Conclusion

Experiments

For the last year, multiple blog posts and videos have been published explaining how you would use those new features (some content even go deeper explaining some implementation details).

Those are great content, however, they don't address the following questions:

Should we now go all-in on RSCs and Server Actions? Drop all client components?
How does this mix with client-side fetching? (react query, etc ...)
When should you use either one of them?

This is why I decided to build a real project to experiment on those new features.

Features of the project

👀 See the demo here - 👨‍💻 See the source code here

It's a fake e-commerce website, that allows you to:

Access list of categories of products
Access products by category
Access product details
Search for products
Add/remove product to/from cart
View cart
Login/Logout (a fake identity is generated for you when you login)
Checkout (a fake payment is made)

Constraints:

It should be SSR friendly (for performance and SEO reasons)
It should also have a good user experience on client-side (fast navigation, interactivity, etc ...)
It should take in account progressive enhancement
Real api calls are made to an external API containing mock data

Tech stack

Next.js 15.2 - canary version (some features are not yet available in the stable version)
React 19
Tailwind CSS
TypeScript
Shadcn UI
Vercel (for hosting)
No database, everything is stored on cookies for simplicity

Implementation

Experimental flags

I turned on the following experimental flags (which needed the canary version of Next.js):

dynamicIO

The dynamicIO flag is an experimental feature in Next.js that causes data fetching operations in the App Router to be excluded from pre-renders unless they are explicitly cached.

It is useful if your application requires fresh data fetching during runtime rather than serving from a pre-rendered cache.

It is expected to be used in conjunction with use cache so that your data fetching happens at runtime by default unless you define specific parts of your application to be cached with use cache at the page, function, or component level.

Link to documentation (dynamicIO)

ppr

Partial Prerendering (PPR) enables you to combine static and dynamic components together in the same route.

Link to documentation (PPR)

Here is the report of the build, you can see most of the routes are partially prerendered as static HTML with dynamic server-streamed content. ◐

Route (app)                              Size     First Load JS
┌ ◐ /                                    214 B           195 kB
├ ○ /_not-found                          140 B           120 kB
├ ◐ /account                             671 B           196 kB
├ ○ /api/hello/world                     140 B           120 kB
├ ƒ /api/og                              353 B           121 kB
├ ◐ /category/[slug]                     1.17 kB         196 kB
├   └ /category/[slug]
├ ◐ /checkout                            207 B           195 kB
├ ◐ /login                               214 B           195 kB
├ ◐ /product/[slug]                      1.04 kB         196 kB
├   └ /product/[slug]
└ ◐ /search                              1.17 kB         196 kB
+ First Load JS shared by all            120 kB
  ├ chunks/520-047851854c706276.js       60.6 kB
  ├ chunks/f5e865f6-9abf91c0747daaa2.js  57.8 kB
  └ other shared chunks (total)          1.92 kB


ƒ Middleware                             33.1 kB

○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
ƒ  (Dynamic)            server-rendered on demand

Server components

By default, all components are server components in Next.js App Router, unless you explicitly mark them as client components using the "use client" directive.

In RSCs, you can:

Fetch data, access backend resources directly (APIS, databases, file-system, etc ...)
Keep large dependencies and sensitive data on the server
Send only the HTML output to the client

RSCs can be rendered on the server, they can also be rendered at build time - any runtime which doesn't have interactive content.

I will detail a few use cases I implemented on this project which leverages RSC features with the experimental flags I enabled.

The server actions part is detailed in the next section.

Layout - RSC + PPR = build time generation of static layout

A simplified version of the layout component:

<Providers>
  <Header />
  <Cart />
  <main>
    {children}
  </main>
  <Footer />
</Providers>

Since every components are server components by default, it will return a static HTML shell.

Since we enabled the ppr flag, the layout will be rendered at build time, and the HTML will be cached (as it doesn't need to be rendered on each request).

You still can include client components, like the Cart component, which will be rendered on the client.

Unrelated: on this project, I use the Route groups feature to have a specific layout for the checkout page and a generic one for the rest of the app.

QRCode - RSC + PPR + "use cache" = build time generation of static content

On the home page, I display a QRCode linking to the website, which is rendered by this react component: <CustomQRCode payload="https://thefakeshop.vercel.app/" />.

CustomQRCode being a server component, it lets us use the toDataURL from the qrcode package to generate the QRCode image. Since RSCs can be async, we can await toDataURL directly in the component.

That way, we don't need to ship the qrcode package to the client bundle, the RSC will return the HTML containing the QRCode image (an img tag with a data url).

Even better: since the url we want our QRCode is static (it won't change based on the request), we can tag the CustomQRCode with the "use cache" directive which, when used on a project with ppr (Partial Prerendering) enabled, will prerender the QRCode image at build time.

Header / UserIcon - RSC + Suspense + PPR + DynamicIO = streaming

In the Header component, I use a UserIcon server component, either:

shows a white user icon if the user is not logged in
shows a green user icon (which links to the account page) if the user is logged in

// Header.tsx - simplified version
import { Suspense } from "react";
import { User } from "lucide-react";

import UserIcon from "./UserIcon";

<header>
  {/* Rest of the header */}
  <Suspense fallback={<User />}>
    <UserIcon />
  </Suspense>
</header>

// UserIcon.tsx - simplified version
import { User } from "lucide-react"; // The user svg icon
import Link from "next/link";

import { getUserInfos } from "@/actions/session";

export async function UserIcon() {
  // Fetches the user infos server-side
  const userInfos = await getUserInfos();

  return (
    <Link href="/account">
      <User className={userInfos ? "text-green-300" : ""} />
    </Link>
  );
}

At build time, the User component (which is the fallback for our Suspense boundary wrapping UserIcon) is rendered and cached. Thanks to the ppr flag, it will be rendered as static HTML.
At runtime, when the server starts streaming the HTML, it first returns this fallback HTML as part as the HTML response.
While the HTML is being streamed to the client, the UserIcon server component is rendered on the server.
If the user is logged in, a fragment of HTML containing the green user icon is streamed to the client which will replace the fallback HTML.

All that in the same HTTP response. And since our "loading" state is just the default User icon, it doesn't show at all.

Here is a simplified version of the raw HTML response with comments to explain the streaming part, follow the 🔍 comments to understand the streaming process:

<!DOCTYPE html>
<html lang="en">
    <body>
        <header>
            <div>
                <a href="/">
                    <span>Fake</span>
                    <span>Shop</span>
                </a>
                <form action="/search"><!-- form for the search combobox (explained in the next section) --></form>
                <nav>
                    <ul>
                        <li>
                            <!--$?-->
                            <template id="B:0"></template>
<!-- 🔍 1. default icon --> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-user " data-prerender-hint="default icon prerendered">
                                <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"></path>
                                <circle cx="12" cy="7" r="4"></circle>
                            </svg>
                            <!--/$-->
                        </li>
                        <li class=""><!-- cart button --></li>
                    </ul>
                </nav>
            </div>
        </header>
        <main></main>
        <footer></footer>
        <div hidden id="S:0"> <!--- 🔍 2. the logged in user icon which was streamed down to the client -->
            <a class="hover:text-gray-300" title="Logged in as Kaley Weimann" href="/account">
                <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-user text-green-300">
                    <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"></path>
                    <circle cx="12" cy="7" r="4"></circle>
                </svg>
            </a>
        </div>
        <script>
            // 🔍 3. light runtime that will swap suspense fallback with the streamed content
            $RC = function(b, c, e) {
                c = document.getElementById(c);
                c.parentNode.removeChild(c);
                var a = document.getElementById(b);
                if (a) {
                    b = a.previousSibling;
                    if (e)
                        b.data = "$!",
                        a.setAttribute("data-dgst", e);
                    else {
                        e = b.parentNode;
                        a = b.nextSibling;
                        var f = 0;
                        do {
                            if (a && 8 === a.nodeType) {
                                var d = a.data;
                                if ("/$" === d)
                                    if (0 === f)
                                        break;
                                    else
                                        f--;
                                else
                                    "$" !== d && "$?" !== d && "$!" !== d || f++
                            }
                            d = a.nextSibling;
                            e.removeChild(a);
                            a = d
                        } while (a);
                        for (; c.firstChild; )
                            e.insertBefore(c.firstChild, a);
                        b.data = "$"
                    }
                    b._reactRetry && b._reactRetry()
                }
            }
            ;
            $RC("B:0", "S:0") // 🔍 4. swapping the default icon with the streamed logged in icon
        </script>
        <script>
            (self.__next_f = self.__next_f || []).push([0])
        </script>
        <script>
            self.__next_f.push([1, "..."])
        </script>
    </body>
</html>

Header / SearchCombobox - RSC + Suspense + dynamicIO = progressive enhancement

The SearchCombobox relies on @headlessui/react for the combobox UI, and react-query for the search request of the autocomplete. So it's a client component.

Since we use the dynamicIO flag, NextJS will attempt to render the SearchCombobox at build time (as it is a client component, on the Layout, which is statically rendered at build time).

However, since we also rely on useSearchParams on this component, we have to wrap it inside a Supense boundary.

// Header.tsx - simplified version
import { Suspense } from "react";

import SearchCombobox from "./SearchCombobox";
import SearchComboboxSkeleton from "./SearchComboboxSkeleton";

<header>
  {/* Rest of the header */}
  <Suspense fallback={<SearchComboboxSkeleton />}>
    <SearchCombobox />
  </Suspense>
</header>

// SearchCombobox.tsx - simplified version
"use client";

export function SearchCombobox({ initialQuery = "" }) {
  // all the client-side logic for the combobox (autocomplete UI, react-query, etc ...)

  return (
    <form role="search" action="/search">
      <Combobox/>
    </form>
  );
}

// SearchComboboxSkeleton.tsx - simplified version
export function SearchComboboxSkeleton() {
  // the skeleton of the combobox - exactly looks like the `SearchCombobox` component
  return (
    <form role="search" action="/search">
      <input type="text" name="q" placeholder="Search products..." />
    </form>
  );
}

That way, the fallback for the Suspense boundary of the SearchCombobox component will be the SearchComboboxSkeleton which:

looks just like the SearchCombobox component
is statically rendered at build time
doesn't require any client-side JavaScript

That way, the search combobox will be usable as soon as this part of the HTML is loaded, even before the whole page or the JavaScript is loaded - progressive enhancement.

Once the JavaScript is loaded, the DOM of the SearchComboboxSkeleton will be replaced with the real SearchCombobox component which will be interactive.

Category Page - RSC + Suspense = streaming

The category page.tsx file exports a sync root component that:

wraps a CategoryContent component with a Suspense boundary
- with the dynamicIO flag, if the page.tsx exported an async component it would be considered as dynamic and would be rendered on the server everytime
- since we export a sync component, the CategoryContent will be rendered at build time and cached as static HTML (better for perf)
- the skeleton showed while loading ProductGridLoading is rendered at build time and cached as static HTML
passes the params to this CategoryContent component
- this component is async and handles loading the products by category with getProductsByCategory at runtime

Splitting the code like this lets us:

have a fast initial page load (the HTML is rendered at build time)
stream the products to the client in the same HTTP response (the CategoryContent component is server-side rendered)

Other benefits:

the ProductGrid component shows the details of each product with a Link to their detail page
that way, NextJS will prefetch the detail page of each product, that way, accessing the detail page of a product will be very fast

Here is a simplified version of the code of the category page:

// src/app/(shop)/category/[slug]/page.tsx - simplified version
import { slugToDisplayName } from "@/utils/slugUtils";

// Sync root component
export default function CategoryPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  return (
    <PageContainer>
      <Suspense fallback={<ProductGridLoading />}>
        <CategoryContent params={params} />
      </Suspense>
    </PageContainer>
  );
}

// Async child component
async function CategoryContent({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const { products } = await getProductsByCategory(slug);

  return (
    <>
      <h1>{slugToDisplayName(slug)}</h1>
      {products.length > 0 ? (
        <ProductGrid products={products} />
      ) : (
        <p>No products found in this category.</p>
      )}
    </>
  );
}

This is the component that handles the loading state of the category page (and the search page). In order to avoid a flash on the title of the page (when it will be replaced by the real title), it is infered from the pathname.

// ProductGridLoading.tsx - simplified version
"use client";

import { slugToDisplayName } from "@/utils/slugUtils";

export function ProductGridLoading() {
  const [title, setTitle] = useState("Loading ...");

  useEffect(() => {
    const pathname = window.location.pathname;

    if (pathname === "/search") {
      const query = new URLSearchParams(window.location.search).get("q");
      setTitle(`Search results for "${query}"`);
    } else if (pathname.startsWith("/category/")) {
      const slug = pathname.split("/").pop();
      if (slug) {
        setTitle(slugToDisplayName(slug));
      }
    }
  }, []);

  return (
    <>
      <h1>{title}</h1>
      <ProductGridSkeleton />
    </>
  );
}

Search Page / Product Page - RSC + Suspense = streaming

On the render level, it works mostly the same way as the category page.

Mixing RSCs with client components

Until now, we have been mainly using RSCs.

Here are the main client components that are used in the project:

SearchCombobox - a client component that relies on react-query to fetch the search results
AddToCartButton - a client component that displays an icon button to add a product to the cart
Cart - a client component that displays the cart and allows to update the quantity of the items
- It shows when you click on the AddToCartButton component or on the cart icon in the Header component
- It relies on react-query to fetch the cart items and the products

Server Actions

NextJS documentation

Server Actions are asynchronous functions that are executed on the server. They can be called in Server and Client Components to handle form submissions and data mutations in Next.js applications.

No need to mount seperate api routes
Only call functions from the server actions

Server actions are often presented inside <form action={myServerAction}> usage. Here are two examples on this project:

Login Page: src/app/(shop)/login/page.tsx
Checkout Page: src/app/(checkout)/checkout/page.tsx

I'm also using react-query on the client side to handle the cart. Since react-query only expects a function that returns a promise, you can totally mix it with server actions (you don't have to open a new api route, only call functions from the server actions).

See my custom react-query hooks example.

Progressive enhancement

Often, when people talk about progressive enhancement, they talk about the ability to use the page even if JavaScript is disabled.

With features like RSC streaming that returns the critical HTML first so that the page renders as soon as it loads and swaps the loaded HTML with the final one as soon as the final chunks are loaded, we need JavaScript to be enabled.

This is about performance. Example on this project:

If you land on a category page which takes too long to load
The header will be sent in the first chunks of the HTML response
It will contain the JS-free version of the SearchCombobox component
You will still be able to make a search even if the JavaScript is still loading and hasn't bootstrapped the page

Thanks to <form action="/search"><input name="q" /></form> which doesn't need JavaScript to be enabled.

Conclusion

Server components is a great piece of technology.

I really learned a lot about caching strategies on NextJS.

I succeeded in my challenge of mixing server actions and react-query. However, I don't know yet what is the best strategy (maybe like every topic in software development, it depends). If you have any feedback or suggestions, please let me know.

Discover React Suspense

Tophe — Sat, 06 Oct 2018 19:30:19 +0000

Watch screencast [en] / Watch talk [fr]

With React v16, the Facebook team shipped a new version of the core called “Fiber”. Thanks to this full rewrite, we’ve already seen new features like Fragments, Portals and ErrorBoundaries. Some other features are still under development:

Suspense
Time Slicing

For the last few months, engineers from facebook have made a few demonstrations of the possibilities of these features. Few examples are available (at the time of the writing, those are still unstable/undocumented APIs).

After the talk of Ryan Florence at React Rally presenting Suspense and how @reach/router is ready for it, I decided to make a little project:

to dive into those new concepts
to share code examples
to expose a simple tool that could help explain the benefits of using suspense

👉Try topheman/react-fiber-experiments👈

What problems does Suspense solves ?

It lets you start rendering before all data is ready (rendering can be paused when data starts loading and resumed when it finishes)
It lets you avoid a cascade of spinners, that may cause flashes due to unintentional reflows and repaints
Code splitting becomes a built-in feature, easy to use (you also can pause rendering while loading script)

What this means:

Move the fetching of data closer to where it will be rendered – data encapsulation
Get rid of loading states – cleaner state in components (maybe even stateless in some use cases – no more need of componentDidMount lifecycle hook to go fetch data)
Finer grain control over spinners (thanks to <Placeholder>)

How to test it today

Suspense is still under active development, be aware that the APIs might change and be unstable, though it’s advanced enough to hack a project with. You’ll need to make your own build of React.

Tophe

This was a short introduction to React Suspense, go further by watching the video and play online with topheman/react-fiber-experiments.

This post was originally posted on my blog.

Finding knowledge is not hard. Putting it all together is.

Tophe — Fri, 11 May 2018 06:44:14 +0000

The reason why I made topheman/npm-registry-browser

In software development, a lot of great quality resources are available, often for free. I’ve been getting feedbacks from developers – at work, online, at meetups – who shared that the hard part is not finding the knowledge but picking one library over an other or putting them all together.

Tutorials explaining a specific problem are all over there, what’s missing is projects examples / courses with a wider point of view.

This is what I decided to do in my latest project: topheman/npm-registry-browser. I respect some constraints that you would get, developing a real-world application, such as:

external API calls
using external libraries (UI kits, router, http clients …)
project setup for development with teams
code quality (linter, code formatting)
tests (unit / end to end)
automation / dev pipeline

The project itself is a Single Page Application that lets you search for packages in the npm registry and show details for each one of them such as the readme, the versions, the stats … In fact, this project is just an excuse to expose how to put together all those technologies I mentioned above.

The source code is available on github. You can test a demo online. I will be adding more features in the next weeks.

TRY IT

PS: This project is based on create-react-app and remains unejected. It was a constraint I imposed myself from the start. I never used CRA before (I have my own webpack starter-kit), so I wanted to test it to be able to tell what’s possible to do with it and what is not.

PPS: I chose not to use Redux, at least, not in that first version because … You might not need Redux (explanation) …

📺Watch video of the talk (fr)

This post was originally posted on my blog.

DEV Community: Tophe

Writing components in TypeScript with jco - WebAssembly Component Model

Build Steps

Example: package.json Scripts

Writing components in Go with TinyGo compiler - WebAssembly Component Model

Setup

Build Process

1. Prepare WIT files for TinyGo

2. Bundle WIT dependencies with wkg

3. Generate Go bindings

4. Compile with TinyGo

File Structure

Plugin Implementation

Go Module Configuration

Writing components in C with WASI SDK - WebAssembly Component Model

What is WASI-SDK?

WASI-SDK Setup

How to write a C plugin

Build Process

File Structure

Plugin Implementation

Building components in multiple languages - WebAssembly Component Model

Building a plugin system - WebAssembly Component Model

1. Introduction

2. From WebAssembly MVP to Component Model

WebAssembly MVP (2017)

WASI (WebAssembly System Interface)

WebAssembly Component Model

3. Defining Interfaces with WIT

4. Creating WebAssembly Components in Rust

Build process

5. Hosts: CLI and Browser

🔧 CLI Host (Rust)

Handling mismatched versions

🌐 Browser Host (TypeScript)

Networking

Filesystem

Local fork of @bytecodealliance/preview2-shim

6. REPL Logic

WIT definition

Input Flow Example

Reserved Command (help)

Plugin Command (echo Hello)

7. Testing and CI/CD

Testing

CI/CD

8. Conclusion

Resources

React Server Components in Practice: Building a fake E-commerce Site with Next.js 15 latest features

Table of Contents

Experiments

Features of the project

Tech stack

Implementation

Experimental flags

Server components

Layout - RSC + PPR = build time generation of static layout

QRCode - RSC + PPR + "use cache" = build time generation of static content

Header / UserIcon - RSC + Suspense + PPR + DynamicIO = streaming

Header / SearchCombobox - RSC + Suspense + dynamicIO = progressive enhancement

Category Page - RSC + Suspense = streaming

Search Page / Product Page - RSC + Suspense = streaming

Mixing RSCs with client components

Server Actions

Progressive enhancement

Conclusion

Discover React Suspense

👉Try topheman/react-fiber-experiments👈

What problems does Suspense solves ?

How to test it today

Finding knowledge is not hard. Putting it all together is.

The reason why I made topheman/npm-registry-browser

Example: `package.json` Scripts

Local fork of `@bytecodealliance/preview2-shim`

Reserved Command (`help`)

Plugin Command (`echo Hello`)