@nodestackapp/server
v2.5.0
Published
The TypeScript-Native Backend Stack. Single-process backend with embedded SQLite, instant CRUD, Auth, Realtime, Files & Admin UI.
Maintainers
Readme
NodeStack
The TypeScript-Native Multi-Application Backend Platform
A self-hosted, single-process backend with embedded SQLite multi-tenancy, instant CRUD, Auth, Realtime SSE, Snapshots, Webhooks, and Themed Admin UI.
https://github.com/user-attachments/assets/70eb11fa-9b68-4eb6-930d-ac367ebc4565
Why NodeStack?
Building modern web and mobile apps often requires managing external database servers, Redis caches, authentication microservices, and boilerplate CRUD route handlers.
NodeStack delivers an instant, complete backend stack in a single Node.js process:
- Zero-Compilation Embedded SQLite: Powered natively by Node.js (
node:sqlite). Zero C++ compilers, Python, or external database daemon installations required. - Multi-Application Platform: Host multiple completely isolated application tenants within a single process—with separate SQLite databases, file storage directories, auth collections, realtime SSE buses, and 1-click app deletion.
- Instant CRUD & Realtime SSE: Automatically exposes REST endpoints and Server-Sent Events change streams for every collection.
- Embedded Web Admin Dashboard: A sleek, reactive dashboard served directly from
http://localhost:8090/_/without needing an external web server. - Native SQLite FTS5 Full-Text Search: High-performance BM25 relevance scoring, prefix queries, and highlighted snippet excerpts without external search services.
- Embedded Serverless Functions: Sandboxed QuickJS-Wasm JavaScript/TypeScript lambda execution with sub-millisecond cold starts, Anti-SSRF network firewalls, direct HTTP routes, database lifecycle hooks, and dedicated CodeMirror IDE workbench.
- Serverless Function Flows: Visual state machine orchestration engine with drag-and-drop designer, declarative Code DSL, 9 state types (Task, Choice, Map, Parallel, Loop, Pass, Wait), database lifecycle event triggers, flow execution concurrency limits, and function-flow referential integrity protection.
- NodeStack Queues Subsystem (v2.4): Transactional SQLite-backed message queuing with atomic claiming, configurable retries, dead-letter queues (DLQ), strict partition FIFO ordering, serverless function binding, and dedicated Admin UI queues manager.
- Outbound Webhooks Engine: Event-driven HTTP callbacks with HMAC-SHA256 signature verification and automated retries.
- Immutable Audit Logs: Field-level
{ old, new }diff computation, actor attribution, sensitive field masking, and visual record timeline. - Built-in Auth & File Storage: JWT tokens, bcrypt password hashing, auth collections (
users), and multipart file uploads with MIME validation. - End-to-End Type Safety: One-command type generation (
nodestack typegen) and live HTTP type exports (GET /_/types.d.ts). - First-Party Client SDK (
nodestack-client): Lightweight (<10KB), zero-dependency TypeScript/JavaScript client for web apps, React, Next.js, React Native, Node.js, Bun, and Deno. - Full TypeScript Extensibility: Write server lifecycle hooks, custom routes, and business logic with direct access to npm.
Comparison: NodeStack vs. PocketBase vs. Supabase
Legend: Exactly one bold cell per row indicates the standout category leader for that specific dimension.
| Feature / Dimension | 🚀 NodeStack | 📦 PocketBase | ⚡ Supabase |
| :--- | :--- | :--- | :--- |
| Primary Ecosystem | TypeScript & Node.js (npm native) | Go | Polyglot (Elixir / Go / SQL) |
| Relational Database Scale | Embedded SQLite (WAL) | Embedded SQLite (WAL) | PostgreSQL (ACID, pgvector, PostGIS) |
| Lowest Resource Footprint | Low (~40–80 MB RAM) | Ultra-Low (~20–40 MB RAM) | Heavy (2–4 GB+ RAM) |
| Zero-Install CLI Velocity | Instant via npx (Zero downloads needed) | Manual binary download | Requires Docker or Cloud account |
| Binary Self-Containment | Standalone Binary (Win, macOS, Linux) | Ultra-Compact Binary (<20MB Go) | Multi-container Docker suite |
| Dual-Mode Usage | Standalone CLI + Importable npm Library | Standalone Binary (Go-only library) | Standalone Service (Cannot embed) |
| Single-Process Multi-Tenancy | Native Multi-App (Isolated DBs in 1 process) | Single tenant per process | Cloud platform (or multi-cluster) |
| Deployment Simplicity | Single binary or npx on a $5 VPS | Single binary on a $5 VPS | Complex self-hosting (10+ Docker containers) |
| Embedded Full-Text Search | Native SQLite FTS5 (BM25 + Snippets) | Basic SQL LIKE queries | Postgres tsvector (Manual schema setup) |
| Realtime Scale & Presence | Lightweight SSE Streams | Lightweight SSE Streams | WebSockets + Presence (Phoenix Engine) |
| Database-Level RLS Security | Visual Rules + SQL expressions | Filter expressions | PostgreSQL Native RLS (In-kernel) |
| Embedded Serverless IDE | QuickJS-Wasm (Sub-ms cold starts & Web IDE) | Basic JS (via Goja VM) | External Deno Edge Functions |
| Workflow Orchestration | Embedded Visual State Machines (Flows & DSL) | None (Manual Go code) | None (External queues/temporal) |
| Background Job Queues | Embedded SQLite (FIFO, DLQ, Functions) | None (Manual in-memory) | None (External BullMQ / SQS) |
| Application Snapshots & Rollback | Atomic checkpoints, drift detection & 1-click restore | Manual ZIP file backups | Sequential SQL migrations only |
| Immutable Audit Trail | Field-level { old, new } diffs & actor attribution | HTTP access request logs only | Requires custom triggers or pgAudit |
| Live HTTP Type Safety | Live dynamic GET /_/types.d.ts endpoint | Community CLI tools (pocketbase-typegen) | CLI typegen (supabase gen types) |
| Interactive API Documentation | Built-in Scalar & Swagger UI (/_/docs) | Static external documentation | Supabase Studio / PostgREST spec |
| Starter Templates & Mock Data | 1-Click templates (E-comm, CRM) + Faker engine | Empty database | Empty database (or Cloud samples) |
When to Choose What
- Choose NodeStack if: You want the simplicity of a single-process embedded backend, but your team builds in TypeScript & Node.js. You get instant access to the npm ecosystem, zero-install
npxstartup, isolated multi-app tenancy in one process, atomic state snapshots, and embedded FTS5 search & Wasm serverless lambdas. - Choose PocketBase if: Your priority is absolute raw binary minimalism (<20MB single Go binary) and the lowest possible idle memory footprint (~20MB RAM).
- Choose Supabase if: You need multi-terabyte enterprise PostgreSQL with complex relational models, pgvector, in-kernel RLS, and bidirectional WebSockets presence.
Quick Start
0. 1-Click "Try in Browser" (Zero Local Setup)
Devs hate cloning repos just to try them. Launch NodeStack immediately without touching your terminal:
- Open in GitHub Codespaces: Boots a dedicated Node.js 24 cloud VM with VS Code in your browser, compiles the server, and automatically pops open the Admin UI (
http://localhost:8090/_/) in an embedded preview. - Deploy on Railway: 1-click cloud deploy with persistent volume storage for your embedded SQLite database (
nodestack_data).
1. Launch with NPX (Instant Backend)
npx @nodestackapp/server startVisit http://localhost:8090/_/ to complete the first-time admin setup and start designing your schema.
2. Create an Admin / Superuser via CLI
npx @nodestackapp/server superuser create [email protected] MySecretPassword123!Programmatic TypeScript SDK
NodeStack is also an importable framework that integrates into your application:
import { NodeStack } from '@nodestackapp/server';
const app = new NodeStack({
dataDir: './nodestack_data',
port: 8090,
});
// Intercept record creation
app.onRecordBeforeCreate('posts', async (event) => {
const { record } = event;
if (!record.title) {
throw new Error('Title cannot be blank');
}
record.slug = record.title.toLowerCase().replace(/[^a-z0-9]+/g, '-');
});
// Custom REST API endpoint
app.router.get('/api/health', async () => {
return { status: 'healthy', uptime: process.uptime() };
});
await app.start();First-Party Client SDK (nodestack-client)
Connect frontend applications to NodeStack with zero external dependencies:
npm install nodestack-clientimport NodeStackClient from 'nodestack-client';
const client = new NodeStackClient('http://localhost:8090');
// 1. Authenticate
await client.collection('users').authWithPassword('[email protected]', 'secret');
// 2. Query with FTS5 Full-Text Search & BM25 Scoring
const results = await client.collection('posts').getList(1, 10, {
search: 'distributed systems',
snippetTag: 'mark',
});
// 3. Multi-Application Scoping (v2.0)
const shopClient = client.app('shop'); // Automatically scopes headers, SSE, and file URLs
const products = await shopClient.collection('products').getList(1, 10);
// 4. Realtime Server-Sent Events (SSE)
client.collection('posts').subscribe('*', (event) => {
console.log('Post changed:', event.action, event.record);
});🛒 Example Applications
Official React E-Commerce Storefront (examples/ecommerce-react)
A modern, full-featured retail storefront showcasing NodeStack's multi-tenancy, authentication, instant CRUD, and real-time capabilities:
- Authentication & Profiles: Registration, JWT sessions with
LocalAuthStore, and 1-click demo login ([email protected]). - Product Catalog & Images: 20 products across 5 categories with SVG hero imagery served directly via NodeStack file storage.
- Faceted Search & Filters: Live search, category pills, price range, in-stock filters, and dynamic star rating computation.
- Wishlist / Favorites: Real-time heart toggles synced to the backend
favoritescollection. - Cart & Checkout: Slide-out cart drawer, free shipping threshold progress meter, and order submission to the
orderscollection. - Order Tracking & Reviews: Visual status stepper (
Pending→Processing→Shipped→Delivered) and verified buyer review forms with live average score updates. - Multi-App Scoping: Configure
VITE_NODESTACK_APPin.env.localto connect seamlessly to isolated tenant databases.
# 1. Start the NodeStack backend with e-commerce template (Port 8090)
# Instant NPX (no cloning required):
npx @nodestackapp/server start --template ecommerce
# Or locally from this repo:
npm run demo:backend
# 2. Start the React storefront (Port 5173 - requires cloning repo)
npm run demo:frontendDocumentation
Full documentation, guides, and tutorials are available on the Official Documentation Portal:
| Guide | Description |
| :--- | :--- |
| Comparison Matrix | Objective architectural comparison with PocketBase and Supabase. |
| Overview & Architecture | Single-process architecture, storage engine, and design principles. |
| Quick Start | Step-by-step setup in under 60 seconds. |
| Collections & Schema | Field types, validation, and automated schema inference. |
| SQLite FTS5 Search | Embedded BM25 relevance scoring and snippet highlighting. |
| Visual Access Rules | Row-level security model and the visual clause builder. |
| Multi-Application Platform | Multi-tenancy, isolated SQLite databases, asset storage, and app scoping. |
| Auth & Security | JWT tokens, bcrypt password hashing, and session revocation. |
| Immutable Audit Logs | Field-level diff computation, actor attribution, and timeline drawer. |
| Realtime SSE | Server-Sent Events engine and topic subscriptions. |
| Outbound Webhooks | Automated HTTP callbacks and HMAC-SHA256 signature verification. |
| Server SDK & Hooks | Database lifecycle hooks and custom Fastify route extensions. |
| Client SDK | Complete nodestack-client usage guide and TypeScript typegen. |
| REST API Reference | Interactive Scalar/Swagger UI API docs and OpenAPI 3.0 spec. |
| Docker & Deployment | Dockerfile, Docker Compose, systemd unit, and reverse proxies. |
License
MIT © NodeStack Contributors
