wasmtime / issue #11536 [Question] how to evolve wit file? · git-wasmtime

Stream: git-wasmtime

Topic: wasmtime / issue #11536 [Question] how to evolve wit file?

Wasmtime GitHub notifications bot (Aug 25 2025 at 20:01):

Hello!

I have a working prototype of using wit and wasmtime for some plugin functionality in a commercial app.

Now one major problem I see is how I can evolve the wit file without breaking all the plugins all the time.

If a plugin is done and tested it should not be touched until new functionality is actually required. It should just work.

But when I change the wit file for new plugins and adapt the host accordingly the existing compiled plugins wouldn't be able to be instantiated.

Any ideas?

Should I, or can I even go with multiple wit files and implement all of them on a plugin?

Any idea appreciated.

On another note: how to share .wit files between host and plugins?

I have the wit file in a shared rust lib for now that has no src folder and no rust code, but I just reference it from the plugins.

For now that's good enough, but in the future I would likw to change that and make it more robust.

Anyway, thanks for any kind of input and thanks a lot for wasmtime!

Wasmtime GitHub notifications bot (Aug 25 2025 at 20:39):

alexcrichton commented on issue #11536:

Good question! I'd recommend following the WASI precedent here which is to:

Ensure all packages have a version.

Once a package is "published" (aka consumable by your plugins) then nothing about its types/functions can change.

Addition of new functions/types/interfaces, however, is possible in point release versions.

Your runtime and guests naturally use the latest version of WITs they had at the time of building, and those continue to work indefinitely.

Does that work for your use case?

For sharing WITs I'd recommend wkg from here

Wasmtime GitHub notifications bot (Aug 25 2025 at 20:57):

Froidoh commented on issue #11536:

Wow, thanks for the quick answer!

Well, I think it depends:

Addition of new functions/types/interfaces, however, is possible in point release versions.

What I want to avoid is: a new version of the .wit file is made with changes and now I have to touch every plugin.

Did I understand you correctly that if the wit file changes by just adding new functionality to the host functions and/or plugin functions, an existing compiled plugin .wasm file (without these functions) will still be able to be instantiated?

If so, that's perfectly fine.

If we change an existing signature, that's a breaking change and of course all the plugins need to be adapted to work with it.

Thanks for wkg!

And another request: If, at some point, you could improve the documentation about how to import existing wasi components like wasi-http etc. and how to use them. That would be super helpful!

I am not too deep in the topic yet and last year I implemented my own http-types because back then I couldn't find wasi-http and today I wouldn't know how to "ship" it.

Like, how to even start. Do I vendor it? Is there something like cargo add wasi-http etc.

There is a lot of information, but it's hard to find it.

But please don't get me wrong: I am super thankful for your hard work. wasmtime is an amazing project. Thank you for it!

Wasmtime GitHub notifications bot (Aug 25 2025 at 21:10):

pchickey commented on issue #11536:

What I want to avoid is: a new version of the .wit file is made with changes and now I have to touch every plugin.
Did I understand you correctly that if the wit file changes by just adding new functionality to the host functions and/or plugin functions, an existing compiled plugin .wasm file (without these functions) will still be able to be instantiated?
If so, that's perfectly fine.
If we change an existing signature, that's a breaking change and of course all the plugins need to be adapted to work with it.

Correct. If for example you release a wit at 0.1.0, then when you release 0.1.1, with only additions and no breaking changes, two things will be the case:

if you update your wasmtime to use 0.1.1, all components created with wit 0.1.0 will still link to wasmtime's defiitions of those host functions.

if you leave your wasmtime at 0.1.0, components created with 0.1.1 will work so long as they don't include any of the new functionality created in 0.1.1. Put another way, if all you do is upgrade the version in a wit and not add anything, it will still be compatible.

If you make a breaking change in semver by changing the version to 0.2.0, there will be no more compatibility. Components created on the 0.1.x series will not work in a wasmtime that only provides 0.2.0, and components created with 0.2.0 will not work in a wasmtime that provides 0.1.x. You can, however, build a wasmtime that supports both 0.1 and 0.2, you will just have to define both with their own wasmtime::component::bindgen! and make both sets available in a wasmtime::component::Linker by using the add_to_linker funcs from each.

And another request: If, at some point, you could improve the documentation about how to import existing wasi components like wasi-http etc. and how to use them. That would be super helpful!
I am not too deep in the topic yet and last year I implemented my own http-types because back then I couldn't find wasi-http and today I wouldn't know how to "ship" it.
Like, how to even start. Do I vendor it? Is there something like cargo add wasi-http etc.

Yes, you vendor it. wkg is the tool with which you vendor things, at the moment. If you would prefer, you can copy the file tree of wits out of https://github.com/WebAssembly/wasi-http/tree/main/wit.

There is a lot of information, but it's hard to find it.
But please don't get me wrong: I am super thankful for your hard work. wasmtime is an amazing project. Thank you for it!

Thanks, we know that documentation isnt perfect right now. One of our best sources of information is component-model.bytecodealliance.org . If you can't find something there, you can ask on this issue tracker if it has something to do with wasmtime, or you can file a bug on https://github.com/bytecodealliance/component-docs/ that the docs dont cover something. You can also get help on https://bytecodealliance.zulipchat.com/.

Wasmtime GitHub notifications bot (Aug 25 2025 at 21:13):

pchickey edited a comment on issue #11536:

What I want to avoid is: a new version of the .wit file is made with changes and now I have to touch every plugin.
Did I understand you correctly that if the wit file changes by just adding new functionality to the host functions and/or plugin functions, an existing compiled plugin .wasm file (without these functions) will still be able to be instantiated?
If so, that's perfectly fine.
If we change an existing signature, that's a breaking change and of course all the plugins need to be adapted to work with it.

Correct. If for example you release a wit at 0.1.0, then when you release 0.1.1, with only additions and no breaking changes, two things will be the case:

if you update your wasmtime to use 0.1.1, all components created with wit 0.1.0 will still link to wasmtime's defiitions of those host functions.

if you leave your wasmtime at 0.1.0, components created with 0.1.1 will work so long as they don't include any of the new functionality created in 0.1.1. Put another way, if all you do is upgrade the version in a wit and not add anything, it will still be compatible.

If you make a breaking change in semver by changing the version to 0.2.0, there will be no more compatibility. Components created on the 0.1.x series will not work in a wasmtime that only provides 0.2.0, and components created with 0.2.0 will not work in a wasmtime that provides 0.1.x. You can, however, build a wasmtime that supports both 0.1 and 0.2, you will just have to define both with their own wasmtime::component::bindgen! and make both sets available in a wasmtime::component::Linker by using the add_to_linker funcs from each.

And another request: If, at some point, you could improve the documentation about how to import existing wasi components like wasi-http etc. and how to use them. That would be super helpful!
I am not too deep in the topic yet and last year I implemented my own http-types because back then I couldn't find wasi-http and today I wouldn't know how to "ship" it.
Like, how to even start. Do I vendor it? Is there something like cargo add wasi-http etc.

Yes, you can vendor. wkg is the tool with which you vendor things, at the moment. If you would prefer, you can copy the file tree of wits out of https://github.com/WebAssembly/wasi-http/tree/main/wit.

If you are writing guest components in Rust and they only use the wasi interfaces, rather than vendoring wit, you can use the wasi crate, which just provides the definitions as created by wit-bindgen from a vendored set of wits, and does nothing else.

If you are writing guests in Rust from your own sets of wits, you can create a crate of your own like wasi that exposes all of the raw bindings that all of your other guests can consume, so you don't have to duplicate the vendoring everywhere.

If you are writing guest components which use wasi interfaces and you want to use async Rust, you can consider using the wstd crate, which provides a higher level interface than the raw bindings exposed by wasi.

There is a lot of information, but it's hard to find it.
But please don't get me wrong: I am super thankful for your hard work. wasmtime is an amazing project. Thank you for it!

Thanks, we know that documentation isnt perfect right now. One of our best sources of information is component-model.bytecodealliance.org . If you can't find something there, you can ask on this issue tracker if it has something to do with wasmtime, or you can file a bug on https://github.com/bytecodealliance/component-docs/ that the docs dont cover something. You can also get help on https://bytecodealliance.zulipchat.com/.

Wasmtime GitHub notifications bot (Aug 25 2025 at 21:57):

Froidoh closed issue #11536:

Hello!

I have a working prototype of using wit and wasmtime for some plugin functionality in a commercial app.

Now one major problem I see is how I can evolve the wit file without breaking all the plugins all the time.

If a plugin is done and tested it should not be touched until new functionality is actually required. It should just work.

But when I change the wit file for new plugins and adapt the host accordingly the existing compiled plugins wouldn't be able to be instantiated.

Any ideas?

Should I, or can I even go with multiple wit files and implement all of them on a plugin?

Any idea appreciated.

On another note: how to share .wit files between host and plugins?

I have the wit file in a shared rust lib for now that has no src folder and no rust code, but I just reference it from the plugins.

For now that's good enough, but in the future I would likw to change that and make it more robust.

Anyway, thanks for any kind of input and thanks a lot for wasmtime!

Last updated: Dec 06 2025 at 07:03 UTC