@d8d-webcontainer/react

基于 WebContainer 的 React Hooks 库,提供了一组用于在 React 应用中使用 WebContainer 的 Hook。

特性

• 🚀 多终端支持 - 可以创建和管理多个终端实例
• 📁 文件系统操作 - 支持文件浏览、编辑和保存
• 🔄 进程管理 - 支持进程启动、监控和终止
• 🛠 项目初始化 - 支持 git clone、依赖安装等初始化操作
• 🎯 开发服务器检测 - 自动检测和提供开发服务器地址

安装

npm install @d8d-webcontainer/react @d8d-webcontainer/api

基础用法

import { useWebContainer, useTerminal, useFileSystem } from '@d8d-webcontainer/react';

function WebContainerDemo() {
  // 管理多个终端
  const [terminals, setTerminals] = useState([
    { id: 'default', ref: useRef(null) }
  ]);

  // 初始化 WebContainer
  const { container, status, error, devServerUrl, activeProcesses } = useWebContainer({
    serverUrl: 'http://localhost:3000',
    onError: (error) => console.error(error),
  });

  // 终端操作
  const { handleTerminalInput } = useTerminal({
    container,
    activeProcesses,
    onOutput: (data, terminalId) => {
      // 将输出发送到对应的终端
      const terminal = terminals.find(t => t.id === terminalId);
      terminal?.ref.current?.write(data);
    },
    onError: (error) => console.error(error),
  });

  // 文件系统操作
  const { selectedFile, handleFileSelect, handleFileSave } = useFileSystem({
    container,
    onStatusChange: (status) => console.log(status),
    onError: (error) => console.error(error),
  });

  // 添加新终端
  const addNewTerminal = () => {
    const newTerminalId = `terminal-${terminals.length + 1}`;
    setTerminals(prev => [...prev, { 
      id: newTerminalId, 
      ref: createRef() 
    }]);
  };

  return (
    <div>
      <div>状态: {status}</div>
      {error && <div>错误: {error.message}</div>}
      
      {/* 终端列表 */}
      <div className="terminals">
        {terminals.map(({ id, ref }) => (
          <Terminal
            key={id}
            ref={ref}
            onInput={(command) => handleTerminalInput(command, id)}
          />
        ))}
      </div>
      
      {/* 文件浏览器和编辑器 */}
      <FileExplorer container={container} onFileSelect={handleFileSelect} />
      {selectedFile && (
        <Editor
          path={selectedFile.path}
          content={selectedFile.content}
          onSave={handleFileSave}
        />
      )}
    </div>
  );
}

Hooks API

useWebContainer

初始化和管理 WebContainer 实例。

interface UseWebContainerProps {
  serverUrl: string;
    onError?: (error: Error) => void;
    onOutput?: (data: string) => void;
}
interface UseWebContainerReturn {
    container: WebContainer | null;
    status: string;
    error: Error | null;
    devServerUrl: string | null;
    activeProcesses: Array<{pid: number; command: string; terminalId: string}>;
}
const result = useWebContainer(props: UseWebContainerProps): UseWebContainerReturn;

useTerminal

管理终端输入输出和进程控制。

interface UseTerminalProps {
    container: WebContainer | null;
    activeProcesses: Array<{pid: number; command: string; terminalId: string}>;
    onOutput?: (data: string, terminalId: string) => void;
    onError?: (error: Error) => void;
}
interface UseTerminalReturn {
    handleTerminalInput: (command: string, terminalId: string) => Promise<void>;
}
const result = useTerminal(props: UseTerminalProps): UseTerminalReturn;

useFileSystem

管理文件系统操作。

    interface UseFileSystemProps {
    container: WebContainer | null;
    onStatusChange?: (status: string) => void;
    onError?: (error: string) => void;
}
interface UseFileSystemReturn {
    handleFileSelect: (path: string, content: string) => void;
    handleFileSave: (path: string, content: string) => Promise<void>;
    selectedFile: { path: string; content: string } | null;
}
const result = useFileSystem(props: UseFileSystemProps): UseFileSystemReturn;

注意事项

1. 需要同时安装 @d8d-webcontainer/api 作为依赖
2. WebContainer 服务器需要单独运行
3. 建议在组件卸载时清理 WebContainer 实例
4. 文件路径使用正斜杠 / 作为分隔符
5. 终端命令执行结果会通过 onOutput 回调返回

示例项目

完整的示例项目可以参考:

• Vite Demo
• Basic Test

许可证

MIT