Node.js

@glyphhq/node sends events from API routes, webhooks, and background jobs. Use server-side tracking for payments, subscription changes, and other events that must not depend on a browser session.

Install

npm install @glyphhq/node

The package ships ESM and CJS builds with TypeScript types. Node.js 18+ is required (the SDK uses the built-in fetch). The SDK reports its package name and version with each request. Glyph stores this as diagnostic metadata alongside the write key used for ingestion. It is not added to event properties.

Initialize

import { GlyphNode } from "@glyphhq/node";

const writeKey = process.env.GLYPH_WRITE_KEY;
if (!writeKey) {
  throw new Error("GLYPH_WRITE_KEY is not set");
}

const glyph = new GlyphNode({
  writeKey,
});

Keep the write key in an environment variable. Use a glyph_pk_... key in production and a glyph_test_... key while testing the integration. Configuration & delivery lists the shared constructor options. The Node client adds one option:

Option	Default	Description
`flushOnExit`	`false`	Flush queued messages on the process’s `beforeExit` event. A best-effort safety net — prefer explicit `flush()` or `close()`.

Identify customers with `profile`

Call profile when a customer signs up or when a profile trait changes. userId is the stable identity key, and every profile must include email.

await glyph.profile("user_123", {
  email: "sarah@example.com",
  name: "Sarah Chen",
  plan: "pro",
});

Record actions with `track`

await glyph.track("user_123", "Invoice paid", {
  amount: 4900,
  currency: "USD",
});

Methods resolve once the message is queued. If a call reaches the flushAt threshold, its promise waits for that flush attempt. To backfill an event, pass its original timestamp as the fourth argument:

await glyph.track("user_123", "Invoice paid", { amount: 4900 }, {
  timestamp: new Date("2026-06-01T09:30:00Z"),
});

Record account context with `group`

group records a group/account event on the customer’s timeline. Glyph does not currently create a separate account record or provide group-level analytics.

await glyph.group("user_123", "acme_inc", { plan: "enterprise" });

Flushing

Messages queue locally and flush when the queue reaches flushAt (default 20) or on the flushIntervalMs timer (default 5 s). In short-lived processes, flush explicitly before exiting:

await glyph.flush(); // send everything queued now
await glyph.close(); // stop the timer and flush — call on shutdown

Serverless and API routes

Serverless runtimes can freeze or terminate as soon as a response is sent, taking your queue with them. Flush before responding:

import { GlyphNode } from "@glyphhq/node";
import { NextResponse } from "next/server";

const writeKey = process.env.GLYPH_WRITE_KEY;
if (!writeKey) {
  throw new Error("GLYPH_WRITE_KEY is not set");
}

const glyph = new GlyphNode({ writeKey });

export async function POST() {
  await glyph.track("user_123", "Report exported");
  await glyph.flush();

  return NextResponse.json({ ok: true });
}

Handle delivery failures

The SDK retries transient delivery failures. Add an onError callback to log batches that still fail:

import { GlyphNode } from "@glyphhq/node";

const writeKey = process.env.GLYPH_WRITE_KEY;
if (!writeKey) {
  throw new Error("GLYPH_WRITE_KEY is not set");
}

const glyph = new GlyphNode({
  writeKey,
  onError: (error, messages, { retryable, status }) => {
    console.error(`Glyph delivery failed (${status ?? "network"})`, {
      retryable,
      dropped: retryable ? 0 : messages.length,
    });
  },
});

Retryable failures leave the batch queued for a later flush. Non-retryable failures, such as a 401 from an invalid write key, call onError and then drop the batch. See Configuration & delivery.

Getting started

SDKs

Guides

Reference

Install

Initialize

Identify customers with `profile`

Record actions with `track`

Record account context with `group`

Flushing

Serverless and API routes

Handle delivery failures

​Install

​Initialize

​Identify customers with profile

​Record actions with track

​Record account context with group

​Flushing

​Serverless and API routes

​Handle delivery failures

Install

Initialize

Identify customers with `profile`

Record actions with `track`

Record account context with `group`

Flushing

Serverless and API routes

Handle delivery failures