Getting Started

almostnode lets you run Node.js, install npm packages, and start framework dev servers — entirely in the browser.

What is almostnode?

almostnode is a JavaScript library that provides a complete Node.js-like environment inside the browser. It includes:

• A virtual filesystem (VirtualFS) with POSIX-compatible operations
• A runtime that executes JavaScript/TypeScript with 40+ shimmed Node.js modules
• A package manager that installs real npm packages client-side
• Built-in Next.js and Vite dev servers with HMR and file-based routing
• A service worker bridge that makes virtual servers accessible via real URLs

Installation

npm install almostnode

Quick Start

The fastest way to get started is with createContainer(). It sets up a virtual filesystem, runtime, and package manager in one call:

import { createContainer } from 'almostnode';

const { vfs, runtime, npm } = createContainer();

// Write a file to the virtual filesystem
vfs.writeFileSync('/hello.js', `
  console.log('Hello from almostnode!');
`);

// Execute it
runtime.runFile('/hello.js');

Your First Server

Let's create an HTTP server that runs entirely in the browser:

import { createContainer } from 'almostnode';

const { vfs, runtime } = createContainer();

vfs.writeFileSync('/server.js', `
  const http = require('http');

  const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>Hello from the browser!</h1>');
  });

  server.listen(3000, () => {
    console.log('Server running on port 3000');
  });
`);

runtime.runFile('/server.js');

The http module is one of 40+ shimmed Node.js modules available out of the box. The server runs in-memory and can be accessed through the service worker bridge.

Installing npm Packages

You can install real npm packages at runtime. The package manager fetches packages from the npm registry, resolves dependencies, and extracts tarballs — all in the browser:

import { createContainer } from 'almostnode';

const { vfs, npm, runtime } = createContainer();

// Install Express from npm
await npm.install('express');

vfs.writeFileSync('/app.js', `
  const express = require('express');
  const app = express();

  app.get('/', (req, res) => {
    res.json({ message: 'Express in the browser!' });
  });

  app.listen(3000);
`);

runtime.runFile('/app.js');

Comparison with WebContainers

Use Cases

Interactive Documentation & Tutorials

Embed live, editable code examples directly in your docs. Users can modify code and see results instantly — no backend, no setup, no "open in CodeSandbox" redirect.

import { createContainer } from 'almostnode';

const { vfs, runtime } = createContainer();
const repl = runtime.createREPL();

// Wire up to a text editor in your docs page
runButton.addEventListener('click', () => {
  const result = repl.eval(editor.value);
  output.textContent = String(result);
});

This is how the REPL on the almostnode homepage works. Users type Node.js code, hit Enter, and see results — state persists across evaluations, just like a real Node.js REPL.

AI Coding Agents in the Browser

Build AI-powered coding assistants that write, execute, and iterate on code — all client-side. The LLM generates code, almostnode runs it, and the agent can inspect output and fix errors in a loop.

import { createContainer } from 'almostnode';

const { vfs, runtime, npm } = createContainer({
  onConsole: (level, ...args) => logs.push({ level, args })
});

async function agentLoop(task) {
  let code = await askLLM(task);

  for (let i = 0; i < 5; i++) {
    vfs.writeFileSync('/agent/index.js', code);
    logs = [];
    try {
      runtime.runFile('/agent/index.js');
      return { success: true, logs };
    } catch (err) {
      // Send error back to LLM for a fix
      code = await askLLM(
        `Fix this error: ${err.message}\nCode:\n${code}`
      );
    }
  }
}

Because everything runs in the browser, there's no backend to provision. The agent can install npm packages, read/write files, run servers, and inspect output — all within the user's browser tab. For untrusted AI-generated code, use a cross-origin sandboxed iframe to isolate execution.

Code Playgrounds & Sandboxes

Build standalone coding environments where users can experiment with Node.js, Express, or full framework setups. Unlike hosted solutions, everything runs client-side — no server costs, no cold starts, no rate limits.

Educational Tools

Teach Node.js, npm, or web frameworks with live exercises. Students write code and see it execute in real time. The virtual filesystem lets you pre-populate project structures, and the REPL lets students explore APIs interactively.

Prototyping & Demos

Spin up a working Next.js or Express app in seconds to demonstrate ideas, test API designs, or prototype UI components — all from a single HTML page with no build step.

Next Steps

• Core Concepts — understand the architecture: VirtualFS, Runtime, PackageManager, and ServerBridge
• Security & Sandbox — cross-origin isolation, security modes, and service worker setup
• Next.js Guide — run a full Next.js dev server with App Router, HMR, and CSS Modules
• Vite Guide — set up Vite with React and hot module replacement
• API Reference — full method signatures for every class and function