API Versioning and Support ​

Last Updated: January 2024

TL;DR: if there is ever a major change in the underlying runtime, applications might need to upgrade their version of @webcontainer/api.

The WebContainer API is comprised to two different components. One is the "client library" at @webcontainer/api, an NPM package that these docs discuss in detail. However, there is a second, implicit component that is invisible to consumers of the former: the actual implementation of the runtime, hosted on StackBlitz.

A good way to think about this split is to consider the difference between a REST API and the client library used to access it. That is, the difference between the GitHub API and Octokit, between AWS and the AWS SDK, etc. The versioning of these client libraries is generally straightforward, as they tend to use semantic versioning. The versioning of the underlying REST API or service is however decoupled from the library: it is instead a matter of support policies.

The @webcontainer/api library does, of course, follow semantic versioning. On the other hand, the underlying "engine" API is not explicitly exposed. We currently do not have any plans for a future version: should that happen, it would mean that only certain versions of the client library would target the newer runtime. Moreover, we do not have any plans to retire the existing version: that would mean that older versions of the client library would cease to work. If we ever consider doing that, we will have an ample deprecation phase.