PortixOne

PortixOne lets web apps print to local thermal printers through a small local runtime and a JavaScript SDK. Try it instantly in mock mode, then connect it to real hardware when ready.

Web App
  ↓
Portix SDK
  ↓
Portix Runtime
  ↓
Thermal Printer

That's the whole mental model — one API call from your app, one small background process on the machine, real paper out the other end. No browser print dialog, no per-vendor driver integration.

One API. Multiple devices. Cross-platform. Printing is the first driver — the same runtime and capability model (Print, Cut, OpenDrawer, ReadWeight, ...) is built to extend to cash drawers, barcode scanners, scales, and customer displays next, instead of a different integration per device and per OS.

Status: Experimental (v0.0.1-alpha) · Current scope: Windows local printing only.

Milestones

• ✅ First Physical Print (2026-07-03) — Runtime → Windows Spooler → Thermal Printer, end-to-end, from a real browser tab.
• ✅ Milestone 2 — Developer Zero (2026-07-03) — SDK published on npm, mock mode, a verified end-to-end Windows installer.
• ✅ Milestone 3 — Local API, pairing, and persisted queue (2026-07-05) — per-app pairing, a crash-recoverable job queue, LAN discovery, human-readable hardware errors. Full detail: MILESTONE_3.md.
• ✅ Milestone 4 — Productization (2026-07-05) — a real measurement layer (GET /metrics), a stress-tested queue, Node.js embedded in the installer (no more Node.js prerequisite), a portable no-admin build, and @portixone/sdk@0.3.0/protocol@0.2.0/shared@0.2.0 republished with the full API. Full detail: MILESTONE_4.md.

See CHANGELOG.md for the full log and ROADMAP.md (now organized as Fase 1–12) for what's next.

Quickstart

npm install @portixone/sdk

import { Portix } from "@portixone/sdk";

const portix = new Portix({ appId: "my-app", tenant: "default" });

await portix.connect();

await portix.print({
    content: "Hello PortixOne!"
});

With the Runtime installed and running, the printer prints — that's it. appId/tenant are your integration's identity: the first connect() pairs automatically (instant from a browser on localhost, otherwise it waits once for approval in the PortixOne tray's "Pairing Requests" menu), and every connect() after reuses it.

No printer or runtime handy? Add { mode: "mock" } and try the exact same code — no setup at all:

const portix = new Portix({ mode: "mock" });

print() renders a text preview of the receipt instead of sending it anywhere. See examples/basic-print for a runnable, standalone version — just npm install && npm start, nothing else — or examples/print-ticket for a real, properly formatted restaurant receipt instead of a "Hello World" string.

Running this repo locally

npm install
npm run dev        # starts the runtime on localhost
npm run build       # builds all workspaces
npm run typecheck

Then open examples/quickstart-html/index.html to try the end-to-end printing flow above in a browser.

Monorepo structure

Folder	Status	License	Description
runtime/	Active (MVP)	Open source	Portix Runtime — headless local bridge (HTTP + WebSocket API + printer manager), installable as a Windows Service
tray/	Active (MVP)	Open source	Lightweight (no Electron) Windows tray icon showing runtime status
installer/	Active (MVP)	Open source	Inno Setup installer — Runtime service + tray, verified install/reinstall/uninstall
sdk-js/	Active (MVP)	Open source	JavaScript SDK (@portixone/sdk) for calling print() from a web app
packages/protocol/	Active (MVP)	Open source	Shared message contract between the runtime and SDKs
packages/shared/	Active (MVP)	Open source	Shared constants and error types
packages/escpos/	Active (MVP)	Open source	ESC/POS command building
examples/	Active (MVP)	Open source	Standalone Node.js example (npm-installed) + minimal HTML demo
docs/	Placeholder	Open source	Quickstart and troubleshooting
cli/	Planned	Open source	Command-line interface for the runtime
sdk-dotnet/	Planned	Open source	.NET SDK
sdk-python/	Planned	Open source	Python SDK
sdk-go/	Planned	Open source	Go SDK
playground/	Planned	Open source	Full Edge Platform
cloud/	Planned	Closed — private repo	Placeholder only; see Open source vs. closed

Layered architecture

1. Cloud Platform (closed) — authentication, projects, API keys, dashboard, device fleet management, licensing, telemetry, team organizations, managed updates, billing, enterprise sync.
2. Secure Communication Layer (open) — HTTPS/WebSockets/TLS between cloud and runtime.
3. Portix Runtime (Edge Runtime) (open) — authenticates, validates, routes commands, and executes jobs locally.
4. Hardware Abstraction Layer (open) — printers, cash drawers, scanners, scales, displays, USB, Serial, Bluetooth, TCP/IP.

Open source vs. closed

PortixOne is open-core. Everything a developer needs to run local printing — and every device capability in the Hardware Abstraction Layer — is open source. The multi-tenant Cloud Platform around it is a separate, closed product.

Open source (MIT, this repo)	Runtime · SDK (JS, .NET, Go, Python) · Protocol · Examples · CLI · Documentation
Closed (portixhq/portix-cloud, private)	Cloud — dashboard, device fleet management, licensing, telemetry, team organizations, managed updates, billing, enterprise sync

The cloud/ folder in this repo is a structural placeholder only, so the layered architecture is visible from the root — it contains no proprietary code and never will.

Try it

npm install @portixone/sdk and see for yourself — the Quickstart above is the whole thing.

Looking for feedback from developers building POS, kiosk, logistics, or web-to-print tools — open an issue with what worked, what didn't, or what's missing.

PortixOne repo network

This monorepo is the source of truth for development. The rest of the knowledge network lives in separate repos, each targeting a distinct search intent:

Repo	What it is
portix.dev	Developer portal — landing, docs, tutorials, examples, roadmap, changelog
portix-runtime	Read-only mirror of the runtime (runtime/ here)
portix-sdk-js	Read-only mirror of the JS SDK (sdk-js/ here)
awesome-web-printing	Curated list of the web printing ecosystem
browser-printing-examples	Runnable examples by framework (vanilla, React, Vue)
escpos-cheatsheet	Quick ESC/POS command reference
thermal-printer-test-files	Real .bin ESC/POS files for testing printers/parsers

License

MIT — see LICENSE. Applies to everything in this repo (the Cloud Platform is closed and lives elsewhere — see Open source vs. closed).