Nodalite

Runtime-agnostic TypeScript API framework
The same App runs unmodified on Node, Lambda, Cloudflare Workers, Bun, and Deno.

• Why Nodalite?
• Features
• Requirements
• Installation
• Scaffolding
• Packages
• Quick Start
• Examples
• Development
• Contributing
• Security
• License

Most Node.js frameworks assume a single runtime. Nodalite doesn't.

• Write once, deploy anywhere — the same App instance runs unmodified on Node.js, Bun, Deno, Cloudflare Workers, and AWS Lambda. No conditional imports, no adapter swapping at the application level.
• Zero-dependency core — @nodalite/core has literally zero runtime dependencies. It only uses what the JS runtime already provides (Fetch API). Smaller attack surface, faster installs, no supply-chain surprises.
• Security by default — built-in middleware for CORS, security headers, rate limiting, JWT auth, and body size limits. Follows OWASP guidance ("reject, don't sanitize") with structured error responses.
• Full auth stack — @nodalite/auth ships JWT with refresh token rotation, OAuth2 PKCE (Google, GitHub, Discord), role-based access control, session management, password hashing, and CSRF protection — all runtime-agnostic via WebCrypto.
• Observability built in — @nodalite/otel adds OpenTelemetry tracing and metrics with a single middleware call. HTTP spans, request duration histograms, active request counters, and W3C trace context propagation out of the box.
• WebSocket support — @nodalite/ws provides rooms, heartbeat, path-based routing, and per-connection typed state across Node.js, Cloudflare Workers, Deno, Bun, and AWS Lambda — with zero runtime dependencies.
• Serverless-aware — cold start hooks, disk-cached ML models, body size limits that check Content-Length before buffering, and adapters that properly convert API Gateway event shapes.

Read the documentation for the full architecture rationale, API reference, security checklist, and deployment guide.

• Runtime-agnostic — same App runs unmodified on Node, Bun, Deno, Cloudflare Workers, and AWS Lambda
• Zero-dependency core — @nodalite/core has zero runtime dependencies
• Authentication & authorization — JWT access/refresh token rotation, OAuth2 PKCE (Google, GitHub, Discord), RBAC, sessions, password hashing, CSRF (docs)
• Security middleware — CORS, security headers, rate limiting, body size limits (docs)
• Observability — OpenTelemetry tracing, HTTP metrics, span enrichment, W3C trace context propagation (docs)
• WebSocket support — rooms, heartbeat, path-based routing, per-connection state across Node/Edge/Bun/Deno/Lambda (docs)
• Background workers — worker_threads for bots, pollers, and CPU offload (docs)
• Scheduler — cron/interval scheduling for long-running servers; serverless adapter too (docs)
• ML inference — serverless-aware model runner with ONNX Runtime adapter and built-in model security (docs)
• OpenAPI — auto-generated OpenAPI 3.1.0 specs, Swagger UI, and ReDoc endpoints (docs)
• Route auto-discovery — file-system based route loading with discover(), prefix files, and nested groups
• Distributed rate limiting — Redis, DynamoDB, and Upstash store backends for serverless/multi-instance deployments
• CLI scaffolding — interactive project generation via npx create-nodalite
• Request validation — Standard Schema support (Zod, Valibot, ArkType) with structured 400 responses

Core package:

npm install nodalite
# or the scoped form:
npm install @nodalite/core

Adapters & extras — install only what you need:

npm install @nodalite/adapter-node      # Node.js server
npm install @nodalite/adapter-lambda    # AWS Lambda
npm install @nodalite/adapter-edge      # Cloudflare Workers
npm install @nodalite/middleware         # Security & HTTP middleware
npm install @nodalite/auth               # JWT, OAuth2, RBAC, sessions, CSRF
npm install @nodalite/ws                 # WebSocket support (rooms, heartbeat, multi-runtime)
npm install @nodalite/otel               # OpenTelemetry tracing & metrics
npm install @nodalite/workers            # Background threads
npm install @nodalite/scheduler          # Cron/interval scheduling
npm install @nodalite/ml                 # ML inference
npm install @nodalite/openapi            # OpenAPI spec generation + Swagger UI

Scaffold a new project in seconds:

npm create nodalite
# or
npx nodalite create

Follow the interactive prompts to select a purpose (API, Telegram bot, Lambda, Edge), and optionally add ML inference, security middleware, and a job scheduler. A ready-to-run project is generated with all dependencies installed.

import { App } from '@nodalite/core';
import { cors, securityHeaders } from '@nodalite/middleware';
import { serve } from '@nodalite/adapter-node';

const app = new App();
app.use('*', securityHeaders());
app.use('*', cors({ origin: 'https://your-frontend.example' }));

app.get('/health', (c) => c.json({ ok: true }));
app.get('/users/:id', (c) => c.json({ id: c.req.param('id') }));

serve(app, { port: 3000 });

import { createLambdaHandler } from '@nodalite/adapter-lambda';
export const handler = createLambdaHandler(app);

import { createEdgeHandler } from '@nodalite/adapter-edge';
export default createEdgeHandler(app);

No adapter needed — app.fetch already matches their native server signature:

export default { fetch: app.fetch };

# Install everything across the workspace
npm install

# Build every package (tsup: ESM + CJS + .d.ts)
npm run build --workspaces --if-present

# Run every package's test suite (Vitest)
npm test

# Type-check across every package
npm run typecheck --workspaces --if-present

# Lint
npm run lint

The monorepo uses TypeScript project references for incremental builds — a root tsconfig.json wires all 14 packages together via tsconfig.build.json files with composite: true.

Every package is genuinely tested, not just typed: adapter-node tests start a real HTTP server and hit it with fetch(); adapter-lambda tests use realistic API Gateway event fixtures; workers tests spawn real worker_threads including a crash/restart cycle; ml tests spin up a real local server to verify on-disk model caching; auth tests run a full end-to-end token issue → access → RBAC → refresh rotation flow; ws tests cover connection lifecycle, room management, and heartbeat across all runtime adapters.

We welcome contributions! Please read our community files before opening issues or PRs:

• Contributing Guide — development workflow, code style, PR process
• Code of Conduct — Contributor Covenant v2.1
• Changelog — version history and release notes

git clone https://github.com/AkkilMG/Nodalite.git
cd nodalite
npm install
npm test

If you discover a security vulnerability, please report it privately by emailing me@akkil.dev. Do not open a public GitHub issue. See SECURITY.md for details.

MIT © 2026-present Akkil M G