NPMv0.6.0Node.js 18+MIT License

@junglans/trail-server

Embedded Analytics & On-Page Heatmap Backend Middleware for Express and Next.js

An ultra-fast, zero-cloud-telemetry backend middleware that stores all incoming application events in your own local SQLite database under /api/jungtrail. Powered by better-sqlite3 with Write-Ahead Logging (WAL) for sub-millisecond event ingestion.

View on npm RegistryGitHub Repository
INGESTION LATENCY
<0.8ms
PEER DEPENDENCIES
Express >=4.0
DATA PERSISTENCE
Local SQLite
EXTERNAL TRAFFIC
Zero Bytes
On This Page
1. Installation2. Quickstart & Usage3. REST API Endpoints4. Configuration OptionsFAQ & SecurityRelated Packages

1. Installation

Install @junglans/trail-server using your favorite package manager. All dependencies are minimal and zero-leakage.

Install Command
npm install @junglans/trail-server

2. Quickstart & Implementation

Get up and running in less than 30 seconds. Copy and paste the code snippets below directly into your codebase.

Code Examples
import express from 'express';
import { jungtrailMiddleware } from '@junglans/trail-server';

const app = express();
app.use(express.json());

// Mount the analytics API onto Express
app.use('/api/jungtrail', jungtrailMiddleware({
  dbName: 'analytics.db',
  dbPath: './data/analytics.db',
  adminKey: process.env.JUNGLANS_ADMIN_KEY || 'production-secret-key',
  cors: true,
  retentionDays: 90
}));

app.listen(8000, () => {
  console.log('Junglans Trail server active on port 8000');
});
File: server.jsjavascript

3. REST Ingestion & Analytics Endpoints

All endpoints are mounted automatically onto your host server under /api/jungtrail.

MethodEndpointAuthorizationDescription
POST/api/jungtrail/eventsPublic / Write KeyIngests client and backend batches of user interactions, clicks, rage clicks, Web Vitals, and errors.
GET/api/jungtrail/heatmapAdmin Key RequiredReturns coordinates, element selectors, and click density clusters formatted for live canvas heatmap rendering.
GET/api/jungtrail/statsAdmin Key RequiredRetrieves aggregate KPIs: unique sessions, total page views, bounce rate, average time-on-page, top referral paths.
GET/api/jungtrail/stats/ecommerceAdmin Key RequiredCalculates e-commerce conversion rates, cart abandonment funnel metrics, total revenue, and average order value.
GET/api/jungtrail/exportAdmin Key RequiredStreams a full JSON or CSV export of all indexed telemetry records for offline reporting and data warehousing.

4. Configuration Options

Configurable parameters passed into the initialization middleware or factory functions.

OptionTypeDefaultDescription
dbNamestring'analytics.db'Filename of the SQLite database created in the target directory.
dbPathstring'./data/analytics.db'Relative or absolute filesystem path where database and WAL journal files are maintained.
adminKeystringundefinedSecret passphrase required to access /stats, /heatmap, and /export endpoints.
corsbooleantrueEnables Cross-Origin Resource Sharing headers for multi-domain frontend clients.
retentionDaysnumber90Automatic rolling retention period after which old event rows are vacuumed.

Frequently Asked Questions