A browser-based code execution environment with TypeScript, Python, Node.js support and React bindings
npm install @examples-ai/code-containerBrowser-based code execution environments for Node.js and Python with TypeScript support and React bindings.
Features:
- 🌐 Browser-based: Run Node.js and Python code directly in the browser
- 🏗️ WebContainer Integration: Full Node.js runtime powered by StackBlitz WebContainer
- 🐍 Pyodide Integration: Complete Python environment with scientific packages
- 🔒 Isolated: Secure isolated execution environments
- 📦 Package Support: Install and use npm/pip packages
- 📁 File System: Virtual file system operations
- 🔄 Singleton Pattern: Efficient resource sharing across instances
- 🎯 TypeScript: Full TypeScript support with type definitions
- ⚛️ React Integration: Hooks and providers for React applications
- 🛡️ Error Handling: Comprehensive error handling and retry mechanisms
``bash`
npm install code-containeror
yarn add code-containeror
pnpm add code-container
`typescript
import { NodeContainer, PythonContainer, bootWebContainer, bootPyodide } from 'code-container';
// Node.js container
const nodeContainer = await bootWebContainer();
const result = await nodeContainer.run('console.log("Hello World!"); return 42;');
// Python container
const pythonContainer = await bootPyodide();
const pyResult = await pythonContainer.run('print("Hello from Python!"); 2 + 3');
`
`typescript
import { NodeContainerProvider, PythonContainerProvider, useNodeContainer, usePythonContainer } from 'code-container';
function App() {
return (
);
}
function NodeCodeRunner() {
const { webContainer, isLoading, error } = useNodeContainer();
const isReady = webContainer && !isLoading && !error;
const runCode = async () => {
if (!isReady) return;
try {
const result = await webContainer.run('console.log("Hello from Node.js!"); return 42;');
console.log(result);
} catch (err) {
console.error('Execution failed:', err);
}
};
if (error) return
return (
function PythonCodeRunner() {
const { pyodide, isLoading, error } = usePythonContainer();
const isReady = pyodide && !isLoading && !error;
const runCode = async () => {
if (!isReady) return;
try {
const result = await pyodide.run('print("Hello from Python!"); 2 + 3');
console.log(result);
} catch (err) {
console.error('Execution failed:', err);
}
};
if (error) return
return (
API Reference
$3
####
bootWebContainer(): Promise
Initializes a Node.js container with WebContainer runtime.####
bootPyodide(): Promise
Initializes a Python container with Pyodide runtime.####
resetNodeRuntime(): void
Resets the Node.js runtime singleton.####
resetPythonRuntime(): void
Resets the Python runtime singleton.$3
####
NodeContainer
- run(code: string, options?: RunOptions): Promise - Execute Node.js code
- File system operations: readFile(), writeFile(), etc.
- Package management: Install npm packages####
PythonContainer
- run(code: string, options?: RunOptions): Promise - Execute Python code
- installPackage(packageName: string): Promise - Install Python packages
- File system operations for Python environment$3
####
useNodeContainer(): NodeContainerHookResult
Returns:
- webContainer: NodeContainer | null - The Node.js container instance
- isLoading: boolean - Loading state
- error: Error | null - Error state####
usePythonContainer(): PythonContainerHookResult
Returns:
- pyodide: PythonContainer | null - The Python container instance
- isLoading: boolean - Loading state
- error: Error | null - Error state$3
####
NodeContainerProvider
Provides Node.js container context to child components. Automatically handles WebContainer initialization.####
PythonContainerProvider
Provides Python container context to child components. Automatically loads Pyodide and handles initialization.Props:
-
src?: string - Custom Pyodide CDN URL (default: jsdelivr v0.25.1)
- strategy?: 'beforeInteractive' | 'afterInteractive' | 'lazyOnload' - Loading strategyFeatures
$3
Containers are initialized automatically when providers mount, with singleton pattern ensuring efficient resource usage.$3
Python containers automatically capture print() output and return it as execution results.$3
Comprehensive error handling with proper error states exposed through hooks.$3
Full TypeScript definitions with proper typing for all APIs and hooks.Development
$3
`bash
pnpm install
`$3
`bash
pnpm build
`$3
`bash
pnpm test
`$3
`bash
cd examples/react-demo
pnpm dev
`Browser Requirements
- Node.js Container: Requires modern browsers with SharedArrayBuffer support
- Python Container: Works in all modern browsers
- HTTPS: Required for WebContainer in production environments
License
MIT License - see LICENSE file for details.
Contributing
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)