WebContainer Sandbox React


一个基于WebContainer API的React代码沙箱组件库，让你能够在浏览器中运行Node.js环境。

背景

随着大模型能力日益提高，代码沙箱成为了一种非常流行的工具，可以为网页Agent应用提供一个快速预览的环境。
比起运行在服务端的代码沙箱，浏览器中的代码沙箱具有以下优势：
- 使用成本低
- 接入难度低
相较于其他或收费、或不再维护、或兼容较差的代码沙箱，webContainer从目前来看，会是一个更好的选择。

本项目大量借鉴了bolt的实现，虽然他们的源码已经好久没有更新了
另外，本项目也大量使用了AI生成的内容（我只是个臭后端）

特性

- 🚀 在浏览器中运行完整的Node.js环境
- 📝 集成Monaco编辑器
- 🖥️ 内置终端支持
- 🔄 实时预览
- 🐛 错误感知

安装

``bash
npm install webcontainer-sandbox-react


或


yarn add webcontainer-sandbox-react
`

重要

- 你需要在你的项目中安装@webcontainer/api，否则无法使用
- 大部分的组件都依赖antd和@ant-design/icons
- TerminalPanel依赖xterm
- CodeEditor依赖@monaco-editor/react

使用

详情见example

重要
- 因为webContainer使用了，所以确保你响应的headers当中包含'Cross-Origin-Opener-Policy': 'same-origin'和'Cross-Origin-Embedder-Policy': 'credentialless'
- 具体如何设置请自行查阅相关资料

组件

$3


提供WebContainer实例的上下文
- children：React节点，子组件将通过useWebContainer获取到WebContainerContext 详情见 WebContainerContext

$3

- webContainer: WebContainer实例
- iframeSrc: webContainer启动的前端应用的地址

$3

提供Session实例的上下文
- sessionKey: 会话的key，改变后会卸载上一个会话，加载新的会话
- initFiles: 初始化的文件列表
- buildCommand: 构建命令 默认: yarn
- startCommand: 启动命令 默认: yarn dev
- fileObservers: 文件观察者，当文件内容改变时，会触发对应的回调
- onError: 异常回调
- children：React节点，子组件将通过useSession获取到SessionContext 详情见 SessionContext

$3

- loading: 是否正在加载
- loadingContent: 加载中的提示内容
- startProcess: 启动的进程
- writer: 启动的进程的写入流
- output: 启动的进程的输出流（原始的）
- processOutput: 启动的进程的输出流（处理后的）（原始的只能pipeTo一次，这个可以多次）
- sessionErrors: 当前会话中的异常（包括终端和浏览器异常）
- clearErrors: 清除当前会话中的异常
- onError: 异常回调
- files: 当前会话中的文件
- setFile: 设置文件
- spawn: 启动进程

$3

一些预制样式及布局，使用后可以快速搭建一个代码沙箱

$3

预览组件

$3

画廊组件，可以展示多个路径的页面

$3

终端面板

$3

异常修复组件
- onFix: 修复回调
- hanging: 是否正在修复

$3

代码编辑器

缓存优化

1. @webcontainer/api 已经有了一层浏览器缓存，相同版本的依赖不会重复下载
2. 如果你使用yarn进行项目构建，请确保你能保存yarn.lock文件（加载时也能获取到），他将大大减少获取依赖版本的时间（npm同理）
3. 切换会话时，默认不会删除node_modules`文件夹，跨会话间也能共享依赖（前提是各会话之间依赖差异不要太大）