Web Vim With Node Template Docs

Practical docs for the BrowserPod-powered Vim editor, filesystem bridge, terminal workflow, and learning tools.

Back to Template

Overview

Web Vim With Node Template is a browser-based Vim workflow built on vim-wasm and BrowserPod. The editor is rendered on a canvas, files are stored in BrowserPod under /vimamp, and terminal commands are translated through a controlled shell layer.

  • Vim engine: vim-wasm running in-browser.
  • Runtime and filesystem: BrowserPod.
  • Default workspace root: /vimamp.
  • Training file: /vimamp/vim-training.txt.
  • Default note file: /vimamp/note.txt.

Quick Start

  1. Open the template and choose Editor from the entry menu.
  2. Open View > Show Filetree and select a file.
  3. Edit in Vim, then run :BPSave to sync to BrowserPod.
  4. Use View > Show Terminal to run Node/npm commands.
  5. Use File > Save As... for explicit filename saves.

Entry Menu

The entry screen supports keyboard-first navigation.

  • Editor: starts full editor mode.
  • Help > Tutorial: opens Learn mode.
  • Help > Cheat Sheet: opens command reference page.
  • Help > Docs: opens this documentation page.
  • Settings > Macros: opens macro/keymap page.
  • Settings > Theme: opens theme editor page.

Filesystem Model

The template manages files in BrowserPod at /vimamp. The filetree and commands enforce this root to avoid path escapes.

  • Root is fixed to /vimamp.
  • Filetree is a left docked panel, not overlay.
  • File operations (mkdir, touch, mv, rm) trigger refresh and keep tabs synchronized.
  • Imports write into BrowserPod using binary-safe file handling.

Vim Buffer Sync

Vim buffers and BrowserPod files are synced by explicit commands to avoid accidental writes.

  • :BPSave writes active buffer to BrowserPod path.
  • :BPEdit /absolute/path opens BrowserPod files by path.
  • Save actions in menu call the same sync pipeline.

Terminal Behavior

The visible terminal is a template shell UI that routes commands into BrowserPod. It is intended for project commands without requiring users to learn BrowserPod internals.

Supported command families

  • Native UI commands: help, pwd, cd, ls, cat, open, save, mkdir, touch, mv, rm.
  • Pass-through commands: npm ..., node <file.js>.

Intentional guardrails

  • node -e is blocked in this command path.
  • npm exec is blocked in this command path.
  • Paths are constrained to /vimamp.

Running Node Projects

Typical project flow in the template terminal:

cd my-project
npm install
npm run dev -- --host 0.0.0.0 --port 4173

Some packages with native binaries can fail on WASM platform targets. If this happens, use package-specific WASM settings or alternate tooling that supports wasm32.

Portal Preview URLs

BrowserPod app servers are exposed through portal URLs, not your host localhost.

  • When a portal is emitted, the template logs [portal] https://....
  • Use View > Open Last Portal to open the latest BrowserPod app URL.
  • The menu item stays disabled until a portal has been discovered.

Theme and Appearance

  • Theme editor page provides templates and per-token colors.
  • Theme profile is stored in session and in BrowserPod config when available.
  • Syntax highlighting can be toggled in View.
  • Default font rendering is constrained to safe monospace settings.

Learn Mode and Cheat Sheet

  • Learn mode tracks session accuracy, keys, and errors.
  • Lesson controls: previous, restart, next, exit.
  • Cheat sheet page offers quick command filtering.

Storage and Reset Notes

  • BrowserPod files are persisted in browser storage, scoped per origin.
  • Clearing site data for the active origin resets files and runtime state.
  • Theme/session settings use browser session/local storage.

Troubleshooting

Terminal output missing for npm/node

  • Refresh the page once after updates to shell bridge logic.
  • Verify command is pass-through safe (npm ..., node file.js).

Dev server runs but localhost is empty

  • Use the portal URL reported by the template.
  • Open it via View > Open Last Portal.

Vim canvas text looks distorted

  • Refresh so latest theme/font settings apply.
  • Re-open editor from entry menu if needed.