Skip to content

Revise introduction #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vados-cosmonic merged 3 commits into from
Jul 16, 2025
Merged

Revise introduction #280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f1e0402
Revise introduction
catamorphism Jul 15, 2025
38af0f2
Update component-model/src/introduction.md
catamorphism Jul 15, 2025
2da3ade
More detail on platforms / what APIs are for
catamorphism Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions component-model/src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

- [Introduction](./introduction.md)

# Understanding Component Model
# Understanding WebAssembly Components

- [Why the Component Model?](./design/why-component-model.md)
- [Component Model Concepts](./design/component-model-concepts.md)
Expand All @@ -13,7 +13,7 @@
- [Packages](./design/packages.md)
- [WIT Reference](./design/wit.md)

# Using Component Model
# Using WebAssembly Components

- [Language Support for Components](./language-support.md)
- [C/C++](./language-support/c.md)
Expand Down
65 changes: 56 additions & 9 deletions component-model/src/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

The WebAssembly Component Model is a broad-reaching architecture for building interoperable WebAssembly libraries, applications, and environments.

This documentation is aimed at _users_ of the component model: developers of libraries and applications.

> [!NOTE]
>
> _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to
> see how to add support for the component model to their project.

## Table of contents

| Understanding components | Building components | Using components |
|--------------------------|----------------------|-------------------|
| [Why Components?] | [C/C++] | [Composing] |
Expand All @@ -27,17 +36,55 @@ The WebAssembly Component Model is a broad-reaching architecture for building in
[Running]: ./running-components.md
[Distributing]: ./composing-and-distributing/distributing.md

> [!NOTE]
>This documentation is aimed at _users_ of the component model: developers of libraries and applications.
>
> _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to
> see how to add support for the component model to their project.

## Status
## WebAssembly components

As with all programming, the goal of writing a component
is to make new functionality available
by building it out of existing functionality.

A WebAssembly component runs on a _platform_,
which may be a Web browser,
a stand-alone runtime,
or even an operating system (when compiling WebAssembly to an executable).
By running the component, the platform gains the functionality
that the component implements.
Likewise, the platform provides functionality
that code in components can use to interact
with the outside world.

For example:

- A user of the component model can build a component
that converts the system time to another time zone.
- For the component to work as intended, the underlying platform
must provide the component with a means to access
the current system time and the system time zone.

## APIs for building WebAssembly components

In general, a platform that runs components
must provide well-defined APIs for accessing functionality
that components need:
for example, reading from standard input,
accessing environment variables,
or manipulating network sockets.

It's useful to have a standard, shared set of APIs
that WebAssembly components can depend on.
[WASI](https://wasi.dev/) (the WebAssembly System Interface) is a standards-track specification
that defines these APIs.
A system or platform may expose some or all of the WASI APIs to components.

### Status

[WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model.
This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will
continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= `v0.2.0`. See [WASI.dev](https://wasi.dev) to stay up to date on the latest releases.
The current stable release of WASI is [WASI 0.2.0](https://github.com/WebAssembly/WASI/pull/577),
which was released on January 25, 2024.
WASI 0.2.0 is [a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2)
that components can target.
WASI proposals will continue to evolve and new ones will be introduced;
however, users of the component model can now pin to any stable release >= `v0.2.0`.
The [WASI.dev roadmap](https://wasi.dev/roadmap) tracks upcoming releases.

## Contributing

Expand Down
2 changes: 1 addition & 1 deletion component-model/src/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ The component is said to "export" the `example-interface` interface, making avai
## Still have questions?

Please contribute to the Component Book by filing your question (or one that you think should be covered here) as
[an issue on GitHub][gh-issues].
[an issue on GitHub][gh-issues-new].

[gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new

Expand Down