Browser Code Runner

A unified API to execute different programming languages in the browser using web workers. This package provides a seamless way to run JavaScript, Python, and Lua code directly in the browser without blocking the main thread.

Features

• 🚀 Web Worker Support: All code execution runs in separate threads to keep your main thread responsive
• 🐍 Python Support: Execute Python code using Pyodide (CPython compiled to WebAssembly)
• 🔧 JavaScript Support: Execute JavaScript/TypeScript code in a sandboxed environment
• 🎯 Lua Support: Execute Lua code using Fengari (Lua VM in JavaScript)
• ⏱️ Timeout Protection: Configurable timeouts to prevent infinite loops
• 📦 TypeScript Support: Full TypeScript definitions included
• 🧪 Comprehensive Testing: Thorough test coverage for all features

Installation

npm install browser-code-runner

Quick Start

import { runCode } from 'browser-code-runner';

// Execute Python code
const result = await runCode({
  language: 'python',
  code: 'print("Hello from Python!")',
  timeout: 2000
});

console.log(result);
// {
//   stdout: "Hello from Python!\n",
//   stderr: "",
//   exitCode: 0,
//   timeMs: 15
// }

🎮 Try the Demo

Experience the Browser Code Runner in action with our interactive demo:

• 🌐 Live Demo: View Demo
• 📱 Mobile Responsive: Works perfectly on all devices
• 🎨 Monaco Editor: Professional code editing experience
• 🚀 Real-time Execution: See results immediately

Run locally:

npm install
npm run demo

Supported Languages

Phase 1 (Currently Supported)

1. JavaScript/TypeScript

   • Runs natively in the browser
   • Sandboxed execution environment
   • Full access to JavaScript APIs

2. Python

   • Powered by Pyodide (CPython → WebAssembly)
   • ~7-10 MB initial load (cached after first use)
   • Full Python standard library support

3. Lua

   • Powered by Fengari (Lua VM in JavaScript)
   • ~1 MB lightweight interpreter
   • Easy to embed and fast execution

API Reference

runCode(options: RunCodeOptions): Promise<RunCodeResult>

The main function to execute code in any supported language.

Parameters

interface RunCodeOptions {
  language: 'javascript' | 'python' | 'lua';
  code: string;
  stdin?: string;
  timeout?: number; // Default: 5000ms
}

Returns

interface RunCodeResult {
  stdout: string;
  stderr: string;
  exitCode: number; // 0 for success, non-zero for errors
  timeMs: number;   // Execution time in milliseconds
}

createCodeRunner(workerUrl?: string): CodeRunner

Create a new CodeRunner instance for advanced usage.

CodeRunner Class

Advanced API for managing multiple code executions.

const runner = createCodeRunner();

// Execute code
const result = await runner.runCode({
  language: 'javascript',
  code: 'console.log("Hello World");'
});

// Clean up resources
runner.terminate();

Usage Examples

JavaScript Execution

import { runCode } from 'browser-code-runner';

// Simple JavaScript
const jsResult = await runCode({
  language: 'javascript',
  code: `
    const numbers = [1, 2, 3, 4, 5];
    const sum = numbers.reduce((a, b) => a + b, 0);
    console.log('Sum:', sum);
  `
});

console.log(jsResult.stdout); // "Sum: 15\n"

Python Execution

import { runCode } from 'browser-code-runner';

// Python with libraries
const pythonResult = await runCode({
  language: 'python',
  code: `
    import math
    import random
    
    numbers = [random.randint(1, 100) for _ in range(5)]
    print(f"Numbers: {numbers}")
    print(f"Average: {sum(numbers) / len(numbers):.2f}")
    print(f"Square root of 16: {math.sqrt(16)}")
  `,
  timeout: 3000
});

console.log(pythonResult.stdout);

Lua Execution

import { runCode } from 'browser-code-runner';

// Lua programming
const luaResult = await runCode({
  language: 'lua',
  code: `
    function fibonacci(n)
      if n <= 1 then
        return n
      end
      return fibonacci(n-1) + fibonacci(n-2)
    end
    
    for i = 0, 10 do
      print("fib(" .. i .. ") = " .. fibonacci(i))
    end
  `,
  timeout: 2000
});

console.log(luaResult.stdout);

Error Handling

import { runCode } from 'browser-code-runner';

try {
  const result = await runCode({
    language: 'javascript',
    code: 'undefined.method();', // This will cause an error
    timeout: 1000
  });
} catch (error) {
  console.error('Execution failed:', error.message);
}

Advanced Usage with Custom Worker

import { createCodeRunner } from 'browser-code-runner';

// Create a custom runner with specific worker URL
const runner = createCodeRunner('/path/to/custom-worker.js');

try {
  const result = await runner.runCode({
    language: 'python',
    code: 'print("Custom worker execution")'
  });
  
  console.log(result);
} finally {
  // Always clean up resources
  runner.terminate();
}

Performance Considerations

Web Workers

• All code execution runs in separate threads
• Main thread remains responsive during execution
• Automatic cleanup of worker resources

Caching

• Python (Pyodide): ~7-10 MB initial download, cached after first use
• Lua (Fengari): ~1 MB, very lightweight
• JavaScript: No additional downloads required

Timeouts

• Default timeout: 5000ms (5 seconds)
• Configurable per execution
• Automatic cleanup on timeout

Browser Compatibility

• Modern Browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
• Web Worker Support: Required
• ES2020 Features: Required
• WebAssembly: Required for Python support

Development

Setup

git clone <repository-url>
cd browser-code-runner
npm install

Build

npm run build

Test

npm test
npm run test:watch

Lint

npm run lint
npm run lint:fix

Format

npm run format

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Roadmap

Phase 2 (Future)

• C/C++ support via Emscripten
• Ruby support via Opal or WASM MRI builds
• Go support via WebAssembly
• Rust support via WebAssembly

Phase 3 (Future)

• Real-time collaboration features
• Code sharing and execution
• Advanced debugging capabilities
• Performance profiling

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions

Acknowledgments

• Pyodide - Python in the browser
• Fengari - Lua VM in JavaScript
• Web Workers API - Browser threading