WebContainer Sandbox React

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

背景

随着大模型能力日益提高，代码沙箱成为了一种非常流行的工具，可以为网页Agent应用提供一个快速预览的环境。 比起运行在服务端的代码沙箱，浏览器中的代码沙箱具有以下优势：

• 使用成本低
• 接入难度低 相较于其他或收费、或不再维护、或兼容较差的代码沙箱，webContainer从目前来看，会是一个更好的选择。

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

特性

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

安装

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'
• 具体如何设置请自行查阅相关资料

组件

WebContainerProvider

提供WebContainer实例的上下文

• children：React节点，子组件将通过useWebContainer获取到WebContainerContext 详情见 WebContainerContext

WebContainerContext

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

SessionProvider

提供Session实例的上下文

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

SessionContext

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

SessionLayout

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

Preview

预览组件

Gallery

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

TerminalPanel

终端面板

ErrorFix

异常修复组件

• onFix: 修复回调
• hanging: 是否正在修复

CodeEditor

代码编辑器

缓存优化

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