webcontainer-sandbox-react/README.md

A React component library for WebContainer-based code sandboxes

# WebContainer Sandbox React

[![npm version](https://img.shields.io/npm/v/webcontainer-sandbox-react.svg)](https://www.npmjs.com/package/webcontainer-sandbox-react)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## 背景

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

本项目大量借鉴了[bolt](https://github.com/stackblitz/bolt.new)的实现，虽然他们的源码已经好久没有更新了
另外，本项目也大量使用了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'`
- 具体如何设置请自行查阅相关资料

## 组件

### WebContainerProvider
提供WebContainer实例的上下文
- `children`：React节点，子组件将通过`useWebContainer`获取到`WebContainerContext` 详情见 [WebContainerContext](src/contexts/WebContainerContext.tsx)


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


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


### 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`文件夹，跨会话间也能共享依赖（前提是各会话之间依赖差异不要太大）