almostnode

Features

Requirements

Quick Start

Installation

npm install almostnode

Basic Usage

import { createContainer } from 'almostnode';
// Create a Node.js container in the browser
const container = createContainer();
// Execute JavaScript code directly
const result = container.execute(`
 const path = require('path');
 const fs = require('fs');

 // Use Node.js APIs in the browser!
 fs.writeFileSync('/hello.txt', 'Hello from the browser!');
 module.exports = fs.readFileSync('/hello.txt', 'utf8');
`);
console.log(result.exports); // "Hello from the browser!"

Running Untrusted Code Securely

import { createRuntime, VirtualFS } from 'almostnode';
const vfs = new VirtualFS();
// Create a secure runtime with cross-origin isolation
const runtime = await createRuntime(vfs, {
 sandbox: 'https://your-sandbox.vercel.app', // Deploy with generateSandboxFiles()
});
// Now it's safe to run untrusted code
const result = await runtime.execute(untrustedCode);

Working with Virtual File System

import { createContainer } from 'almostnode';
const container = createContainer();
const { vfs } = container;
// Pre-populate the virtual filesystem
vfs.writeFileSync('/src/index.js', `
 const data = require('./data.json');
 console.log('Users:', data.users.length);
 module.exports = data;
`);
vfs.writeFileSync('/src/data.json', JSON.stringify({
 users: [{ name: 'Alice' }, { name: 'Bob' }]
}));
// Run from the virtual filesystem
const result = container.runFile('/src/index.js');

With npm Packages

import { createContainer } from 'almostnode';
const container = createContainer();
// Install a package
await container.npm.install('lodash');
// Use it in your code
container.execute(`
 const _ = require('lodash');
 console.log(_.capitalize('hello world'));
`);
// Output: Hello world

Running Shell Commands

import { createContainer } from 'almostnode';
const container = createContainer();
// Write a package.json with scripts
container.vfs.writeFileSync('/package.json', JSON.stringify({
 name: 'my-app',
 scripts: {
 build: 'echo Building...',
 test: 'vitest run'
 }
}));
// Run shell commands directly
const result = await container.run('npm run build');
console.log(result.stdout); // "Building..."
await container.run('npm test');
await container.run('echo hello && echo world');
await container.run('ls /');

Running CLI Tools

// Install a package that includes a CLI tool
await container.npm.install('vitest');
// Run it directly — bin stubs are created in /node_modules/.bin/
const result = await container.run('vitest run');
console.log(result.stdout); // Test results

Streaming Output & Long-Running Commands

const controller = new AbortController();
await container.run('vitest --watch', {
 onStdout: (data) => console.log(data),
 onStderr: (data) => console.error(data),
 signal: controller.signal,
});
// Send input to the running process
container.sendInput('a'); // Press 'a' to re-run all tests
// Stop the command
controller.abort();

With Next.js Dev Server

import { VirtualFS, NextDevServer, getServerBridge } from 'almostnode';
const vfs = new VirtualFS();
// Create a Next.js page
vfs.mkdirSync('/pages', { recursive: true });
vfs.writeFileSync('/pages/index.jsx', `
 import { useState } from 'react';

 export default function Home() {
 const [count, setCount] = useState(0);
 return (
 <div>
 <h1>Count: {count}</h1>
 <button onClick={() => setCount(c => c + 1)}>+</button>
 </div>
 );
 }
`);
// Start the dev server
const server = new NextDevServer(vfs, { port: 3000 });
const bridge = getServerBridge();
await bridge.initServiceWorker();
bridge.registerServer(server, 3000);
// Access at: /__virtual__/3000/

Service Worker Setup

Which Setup Do I Need?

Option 1: Cross-Origin Sandbox (Recommended)

import { generateSandboxFiles } from 'almostnode';
import fs from 'fs';
const files = generateSandboxFiles();
// Creates: index.html, vercel.json, __sw__.js
fs.mkdirSync('sandbox', { recursive: true });
for (const [filename, content] of Object.entries(files)) {
 fs.writeFileSync(`sandbox/${filename}`, content);
}
// Deploy to a different origin:
// cd sandbox && vercel --prod

Option 2: Same-Origin with Vite

// vite.config.ts
import { defineConfig } from 'vite';
import { almostnodePlugin } from 'almostnode/vite';
export default defineConfig({
 plugins: [almostnodePlugin()]
});

// vite.config.ts
almostnodePlugin({ swPath: '/custom/__sw__.js' })
// Then in your app:
await bridge.initServiceWorker({ swUrl: '/custom/__sw__.js' });

Option 3: Same-Origin with Next.js

// app/__sw__.js/route.ts
import { getServiceWorkerContent } from 'almostnode/next';
export async function GET() {
 return new Response(getServiceWorkerContent(), {
 headers: {
 'Content-Type': 'application/javascript',
 'Cache-Control': 'no-cache',
 },
 });
}

// pages/api/__sw__.ts
import { getServiceWorkerContent } from 'almostnode/next';
import type { NextApiRequest, NextApiResponse } from 'next';
export default function handler(req: NextApiRequest, res: NextApiResponse) {
 res.setHeader('Content-Type', 'application/javascript');
 res.setHeader('Cache-Control', 'no-cache');
 res.send(getServiceWorkerContent());
}

// App Router (file-based route)
await bridge.initServiceWorker({ swUrl: '/__sw__.js' });
// Pages Router (API route)
await bridge.initServiceWorker({ swUrl: '/api/__sw__' });

Option 4: Manual Setup (Other Frameworks)

cp node_modules/almostnode/dist/__sw__.js ./public/

import { getServiceWorkerPath } from 'almostnode/next';
import fs from 'fs';
fs.copyFileSync(getServiceWorkerPath(), './public/__sw__.js');

Comparison with WebContainers

When to use almostnode

Example: Code Playground

import { createContainer } from 'almostnode';
function createPlayground() {
 const container = createContainer();
 return {
 run: (code: string) => {
 try {
 const result = container.execute(code);
 return { success: true, result: result.exports };
 } catch (error) {
 return { success: false, error: error.message };
 }
 },
 reset: () => container.runtime.clearCache(),
 };
}
// Usage
const playground = createPlayground();
const output = playground.run(`
 const crypto = require('crypto');
 module.exports = crypto.randomUUID();
`);
console.log(output); // { success: true, result: "550e8400-e29b-..." }

When to use WebContainers

API Reference

createContainer(options?)

interface ContainerOptions {
 cwd?: string; // Working directory (default: '/')
 env?: Record<string, string>; // Environment variables
 onConsole?: (method: string, args: any[]) => void; // Console hook
}
const container = createContainer({
 cwd: '/app',
 env: { NODE_ENV: 'development' },
 onConsole: (method, args) => console.log(`[${method}]`, ...args),
});

container.run(command, options?)

interface RunResult {
 stdout: string;
 stderr: string;
 exitCode: number;
}
interface RunOptions {
 onStdout?: (data: string) => void; // Stream stdout in real-time
 onStderr?: (data: string) => void; // Stream stderr in real-time
 signal?: AbortSignal; // Cancel the command
}

container.sendInput(data)

VirtualFS

// Synchronous operations
vfs.writeFileSync(path, content);
vfs.readFileSync(path, encoding?);
vfs.mkdirSync(path, { recursive: true });
vfs.readdirSync(path);
vfs.statSync(path);
vfs.unlinkSync(path);
vfs.rmdirSync(path);
vfs.existsSync(path);
vfs.renameSync(oldPath, newPath);
// Async operations
await vfs.readFile(path, encoding?);
await vfs.stat(path);
// File watching
vfs.watch(path, { recursive: true }, (event, filename) => {
 console.log(`${event}: ${filename}`);
});

Runtime

// Execute code string
runtime.execute('console.log("Hello")');
// Run a file from VirtualFS
runtime.runFile('/path/to/file.js');
// Require a module
const module = runtime.require('/path/to/module.js');

createRuntime (Async Runtime Factory)

import { createRuntime, VirtualFS } from 'almostnode';
const vfs = new VirtualFS();
// RECOMMENDED: Cross-origin sandbox (fully isolated)
const secureRuntime = await createRuntime(vfs, {
 sandbox: 'https://your-sandbox.vercel.app',
});
// For demos/trusted code: Same-origin with explicit opt-in
const demoRuntime = await createRuntime(vfs, {
 dangerouslyAllowSameOrigin: true,
 useWorker: true, // Optional: run in Web Worker
 cwd: '/project',
 env: { NODE_ENV: 'development' },
});
// Both modes use the same async API
const result = await secureRuntime.execute('module.exports = 1 + 1;');
console.log(result.exports); // 2

Security Modes

Sandbox Setup

Quick Setup (Vercel)

import { generateSandboxFiles } from 'almostnode';
import fs from 'fs';
const files = generateSandboxFiles();
// Generates: index.html, vercel.json, __sw__.js
fs.mkdirSync('sandbox', { recursive: true });
for (const [filename, content] of Object.entries(files)) {
 fs.writeFileSync(`sandbox/${filename}`, content);
}
// Deploy: cd sandbox && vercel --prod

Manual Setup (Any Platform)

1. The sandbox HTML page

<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"></head>
<body>
<script type="module">
 import { VirtualFS, Runtime } from 'https://unpkg.com/almostnode/dist/index.js';
 let vfs = null;
 let runtime = null;
 window.addEventListener('message', async (event) => {
 const { type, id, code, filename, vfsSnapshot, options, path, content } = event.data;
 try {
 switch (type) {
 case 'init':
 vfs = VirtualFS.fromSnapshot(vfsSnapshot);
 runtime = new Runtime(vfs, {
 cwd: options?.cwd,
 env: options?.env,
 onConsole: (method, args) => {
 parent.postMessage({ type: 'console', consoleMethod: method, consoleArgs: args }, '*');
 },
 });
 break;
 case 'execute':
 const result = runtime.execute(code, filename);
 parent.postMessage({ type: 'result', id, result }, '*');
 break;
 case 'runFile':
 const runResult = runtime.runFile(filename);
 parent.postMessage({ type: 'result', id, result: runResult }, '*');
 break;
 case 'syncFile':
 if (content === null) { try { vfs.unlinkSync(path); } catch {} }
 else { vfs.writeFileSync(path, content); }
 break;
 case 'clearCache':
 runtime?.clearCache();
 break;
 }
 } catch (error) {
 if (id) parent.postMessage({ type: 'error', id, error: error.message }, '*');
 }
 });
 parent.postMessage({ type: 'ready' }, '*');
</script>
</body>
</html>

2. Required HTTP headers

Access-Control-Allow-Origin: *
Cross-Origin-Resource-Policy: cross-origin

Use in your app

const runtime = await createRuntime(vfs, {
 sandbox: 'https://sandbox.yourdomain.com', // Must be different origin!
});
// Code runs in isolated cross-origin iframe
const result = await runtime.execute(untrustedCode);

Local Development

# Terminal 1: Main app on port 5173
npm run dev
# Terminal 2: Sandbox on port 3002
npm run sandbox

What cross-origin sandbox protects

PackageManager

// Install a package
await npm.install('react');
await npm.install('lodash@4.17.21');
// Install multiple packages
await npm.install(['react', 'react-dom']);

Supported Node.js APIs

Fully Shimmed Modules

Stubbed Modules

Framework Support

Vite

import { VirtualFS, ViteDevServer, getServerBridge } from 'almostnode';
const vfs = new VirtualFS();
// Create a React app
vfs.writeFileSync('/index.html', `
 <!DOCTYPE html>
 <html>
 <body>
 <div id="root"></div>
 <script type="module" src="/src/main.jsx"></script>
 </body>
 </html>
`);
vfs.mkdirSync('/src', { recursive: true });
vfs.writeFileSync('/src/main.jsx', `
 import React from 'react';
 import ReactDOM from 'react-dom/client';

 function App() {
 return <h1>Hello Vite!</h1>;
 }

 ReactDOM.createRoot(document.getElementById('root')).render(<App />);
`);
// Start Vite dev server
const server = new ViteDevServer(vfs, { port: 5173 });

Next.js

Pages Router

/pages
 /index.jsx → /
 /about.jsx → /about
 /users/[id].jsx → /users/:id
 /api/hello.js → /api/hello

App Router

/app
 /layout.jsx → Root layout
 /page.jsx → /
 /about/page.jsx → /about
 /users/[id]/page.jsx → /users/:id

Hot Module Replacement (HMR)

How It Works

// HMR works automatically - just edit files and save
vfs.writeFileSync('/app/page.tsx', updatedContent);
// The preview iframe will automatically refresh with the new content

Setup Requirements

// Create sandboxed iframe for security
const iframe = document.createElement('iframe');
iframe.src = '/__virtual__/3000/';
// Sandbox restricts the iframe's capabilities - add only what you need
iframe.sandbox = 'allow-forms allow-scripts allow-same-origin allow-popups';
container.appendChild(iframe);
// Register the iframe as HMR target after it loads
iframe.onload = () => {
 if (iframe.contentWindow) {
 devServer.setHMRTarget(iframe.contentWindow);
 }
};

Manual HMR Triggering

function triggerHMR(path: string, iframe: HTMLIFrameElement): void {
 if (iframe.contentWindow) {
 iframe.contentWindow.postMessage({
 type: 'update',
 path,
 timestamp: Date.now(),
 channel: 'next-hmr', // Use 'vite-hmr' for Vite
 }, '*');
 }
}
// After writing a file
vfs.writeFileSync('/app/page.tsx', newContent);
triggerHMR('/app/page.tsx', iframe);

Supported File Types

Demos

Development

Setup

git clone https://github.com/macaly/almostnode.git
cd almostnode
npm install

Run Tests

# Unit tests
npm test
# E2E tests (requires Playwright)
npm run test:e2e

Development Server

npm run dev

Contributing

License

Acknowledgments