@d8d-webcontainer/api

基于 WebContainer 技术的远程容器运行时 API。

安装

``bash
npm install @d8d-webcontainer/api
`

基本用法

`typescript
import { WebContainer } from "@d8d-webcontainer/api";
async function main() {
// 初始化 WebContainer
const container = await WebContainer.getInstance({
serverUrl: "http://localhost:3000",
});
// 挂载文件
await container.mount({
"package.json": {
file: {
contents: JSON.stringify({
name: "my-project",
dependencies: {},
}),
},
},
});
// 执行命令
await container.spawn("npm", ["install"], {
onOutput: (data) => console.log(data),
});
}
`

API 参考

$3

#### 静态方法

##### WebContainer.getInstance(config: WebContainerConfig)

创建或获取 WebContainer 实例。

参数:

- config.serverUrl: WebContainer 服务器地址

返回值: Promise

`typescript
const container = await WebContainer.getInstance({
serverUrl: "http://localhost:3000",
});
`

##### WebContainer.hasInstance()

检查是否已存在 WebContainer 实例。

返回值: boolean

##### WebContainer.destroyInstance()

销毁当前的 WebContainer 实例。

#### 实例方法

##### mount(files: FileSystemTree)

挂载文件系统。

参数:

- files: 文件系统树结构对象

`typescript
await container.mount({
src: {
directory: {
contents: {
"index.js": {
file: {
contents: 'console.log("Hello");',
},
},
},
},
},
});
`

##### spawn(command: string, args?: string[], options?: SpawnOptions)

执行命令。

参数:

- command: 要执行的命令
- args: 命令参数数组
- options.onOutput: 输出回调函数

`typescript
await container.spawn("npm", ["install"], {
onOutput: (data) => console.log(data),
});
`

$3

通过 container.fs 访问文件系统 API。

#### list(path?: string)

列出目录内容。

参数:

- path: 目录路径,默认为 '.'

返回值: Promise<{ name: string; type: 'file' | 'directory' }[]>

`typescript
const files = await container.fs.list("./src");
`

#### writeFile(path: string, content: string)

写入文件内容。

参数:

- path: 文件路径
- content: 文件内容

`typescript
await container.fs.writeFile("config.json", '{"port": 3000}');
`

#### remove(path: string)

删除文件或目录。

参数:

- path: 文件或目录路径

`typescript
await container.fs.remove("temp");
`

#### mkdir(path: string)

创建目录。

参数:

- path: 目录路径

`typescript
await container.fs.mkdir("src/components");
`

类型定义

$3

`typescript
interface FileSystemTree {
[path: string]:
| {
file: {
contents: string;
};
}
| {
directory: {
contents: FileSystemTree;
};
};
}
`

$3

`typescript
interface SpawnOptions {
onOutput?: (data: string) => void;
}
`

示例

$3

`typescript
import { WebContainer } from '@d8d-webcontainer/api';
async function createNodeProject() {
const container = await WebContainer.getInstance({
serverUrl: "http://localhost:3000",
});
// 创建项目文件
await container.mount({
"package.json": {
file: {
contents: JSON.stringify({
name: "node-demo",
type: "module",
dependencies: {
express: "^4.18.2",
},
}),
},
},
"index.js": {
file: {
contents: import express from 'express'; const app = express(); app.get('/', (req, res) => { res.send('Hello from WebContainer!'); }); app.listen(3000);,
},
},
});
// 安装依赖
await container.spawn("npm", ["install"], {
onOutput: console.log,
});
// 运行服务器
await container.spawn("node", ["index.js"], {
onOutput: console.log,
});
}
`

$3

`typescript
async function fileOperations(container: WebContainer) {
// 创建目录
await container.fs.mkdir("src");
// 写入文件
await container.fs.writeFile("src/hello.js", 'console.log("Hello");');
// 列出文件
const files = await container.fs.list("src");
console.log("Files:", files);
// 读取文件
const content = await container.fs.readFile("src/hello.js");
console.log("Content:", content);
// 删除文件
await container.fs.remove("src/hello.js");
}
`

注意事项

1. WebContainer 实例是单例的,同一时间只能存在一个实例。

2. 在组件卸载时应该调用 WebContainer.destroyInstance() 清理资源。

3. 文件路径使用正斜杠 /` 作为分隔符。

4. spawn 命令的输出会通过 onOutput 回调返回,包括 stdout 和 stderr。

5. 错误输出会以红色显示,退出信息会以黄色显示。

License

MIT