Pier
Docs

Documentation

Architecture

See how CLI, bridge, extension, and terminal rendering fit together.

Runtime Flow

  1. pier <name> <cmd...> wraps portless and records <name>.localhost -> cwd
  2. CLI ensures the bridge process is running
  3. pier setup ensures the Portless proxy is running and prints bridge connection details for the extension
  4. Extension content script activates only on localhost-style pages
  5. Content script opens WebSocket /terminal with token and page context
  6. Bridge resolves the page hostname using the workspace registry
  7. Bridge creates or reuses shell session (node-pty with pipe fallback)
  8. xterm.js renders terminal output in-page

Repository Structure

  • packages/shared: shared constants, settings normalization, and WebSocket protocol helpers
  • packages/cli-core: CLI commands, config store, workspace routing registry
  • packages/bridge-core: bridge HTTP/WebSocket server and shell session management
  • packages/extension-src: extension source and static assets
  • extension/: generated unpacked extension output
  • cli/, server/, and bin/: JS shims loading compiled dist output

Extension Build Pipeline

pnpm run build:extension bundles the shared runtime, content script, options UI, copies static extension assets, and removes stale vendored JS.

Packaging Model

  • Published package is a single npm package: @malviyahimanshu/pier
  • Chrome Web Store extension is the primary user install path
  • pier extension install remains available for manual unpacked workflows
  • Internal packages are implementation details
  • prepack runs build and checks so published tarballs include compiled dist files and release packaging can produce extension ZIP artifacts