Node.js and edge

@mirafive/sdk-server sends events and evaluates feature flags on a server. Use it in Node.js, Bun, Deno, Cloudflare Workers, Vercel functions and other edge runtimes. Using Next.js, TanStack Start, Nuxt or Astro? Their packages (Next.js, TanStack Start, Nuxt, Astro) build on this one and wire it for you. On Convex, use @mirafive/sdk-convex.

InstallCopy Anchor Link

npm install @mirafive/sdk-server

For Deno:

deno add npm:@mirafive/sdk-server

Requires Node 20 or newer, Bun, Deno or workerd (Cloudflare Workers). The package is ESM only, has no runtime dependencies and uses only fetch, crypto.subtle, crypto.randomUUID, AbortController, timers and TextEncoder. Each of its two entries is under 4 kB (min + gzip).

Set upCopy Anchor Link

You need the secret key of a server source (mf_…). See Keys for where to find it. It stays on the server: new Mira() throws a TypeError when it runs in a browser.

MIRAFIVE_SECRET_KEY=mf_…

The package reads no environment variables itself. Pass the key as key, and your own host (optional) as host.

track() buffers. A batch leaves after 1 second or at 100 events. A process or function that ends before that loses the buffer, so each runtime needs one line that waits for delivery:

import { Mira } from '@mirafive/sdk-server'

export const mira = new Mira({
  key: process.env.MIRAFIVE_SECRET_KEY,
  host: process.env.MIRAFIVE_HOST,
})

process.on('SIGTERM', async () => {
  await mira.shutdown()
  process.exit(0)
})

Server events are sent in full mode by default. See Consent.

VerifyCopy Anchor Link

1. Send an install check once. It proves the key and host work and is never stored or billed:

   Copy Text

   import { Mira } from '@mirafive/sdk-server'
   
   const mira = new Mira({ key: process.env.MIRAFIVE_SECRET_KEY })
   
   console.log(await mira.send([{ name: '$install_check' }]))

   It prints { batch: '…', accepted: 0, dropped: 1, reason: 'install_check' }. A wrong key rejects with a MiraError instead (see Errors).

2. Track a real event, then open the source's live view in MIRA FIVE and find it.

Nothing arriving? See Troubleshooting.

Track eventsCopy Anchor Link

Call track(name, options) where the thing happens:

mira.track('order completed', {
  userId: order.customerId,
  properties: { revenue: order.total, currency: 'EUR' },
})

userId is your own pseudonymous id, never an email address. time (a Date, epoch milliseconds or an ISO string) defaults to now. anonymousId and sessionId link the event to a browser visitor when the browser SDK sent them to you. Names starting with $ are reserved.

Each event is checked when you call track(), against the limits the server applies: names up to 128 characters, ids up to 256, properties up to 64 values, 5 levels, keys of 128 characters and 32 KB. An event that breaks one, or whose properties are not JSON (a BigInt, a cycle), is dropped alone and reported to onError as invalid_event. The rest of the batch goes.

with() returns a view whose events carry the same ids and properties. It shares the client's buffer:

const requestMira = mira.with({ userId: session.userId, properties: { tenant: 'acme' } })

requestMira.track('report_exported')

To have TypeScript check event names and properties, pass an event map. It is types only:

type Events = { signup: { plan: 'free' | 'pro' }; logout: undefined }

const mira = new Mira<Events>({ key: process.env.MIRAFIVE_SECRET_KEY })

mira.track('signup', { properties: { plan: 'pro' } }) // checked by TypeScript

Event names, properties and revenue are covered in Track events.

Identify usersCopy Anchor Link

identify(userId, traits?, { anonymousId? }) records the person's traits. With the browser's anonymous id, it also links the visitor's earlier events to the user:

mira.identify(user.id, { plan: user.plan }, { anonymousId })

Call it after signup and login. It needs full mode. See Identify users.

Idempotent sendsCopy Anchor Link

Webhooks and jobs are sometimes delivered twice. send() delivers 1–1000 events as one batch now and resolves to the server's receipt. Give it an idempotency key and a repeat is stored and billed once:

await mira.send(
  [{ name: 'order completed', userId: order.customerId, properties: { revenue: 129, currency: 'EUR' } }],
  { idempotencyKey: `order-${order.id}` },
)

The batch id is derived from the key, so every MIRA FIVE SDK maps the same key to the same batch, and the server keeps a batch id for a day. Retries resend the byte-identical body. To resend the same bytes from another process (a durable outbox), also fix each event's time and pass sentAt: send(events, { idempotencyKey, sentAt }).

send() rejects with a MiraError. It honours Retry-After up to 120 seconds; pass signal to cancel it.

ConsentCopy Anchor Link

• Full mode (default) sends the identifiers you pass: userId, anonymousId, sessionId. You hold the consent or other lawful basis for them.
• Consentless mode (mode: 'consentless') counts without identifiers, for revenue, invoices and anonymous totals. Passing userId, anonymousId or sessionId then throws a TypeError, because the server would refuse the whole batch.
• A consentless source refuses full batches with 400 collection_mode_not_allowed.
• Do Not Track and Global Privacy Control reach a server as DNT: 1 and Sec-GPC: 1 headers. For such a request, leave the ids out of track() and pass optedOut: true to flags.

See Consent.

Feature flagsCopy Anchor Link

@mirafive/sdk-server/flags evaluates this source's flags in your process. Create one MiraFlags next to the client and pass the client as mira, so experiments counted on the server send their exposures:

import { Mira } from '@mirafive/sdk-server'
import { MiraFlags } from '@mirafive/sdk-server/flags'

export const mira = new Mira({ key: process.env.MIRAFIVE_SECRET_KEY })
export const flags = new MiraFlags({ key: process.env.MIRAFIVE_SECRET_KEY, mira })

Get the flags of one person or visitor, then read them:

const user = await flags.for({
  userId: session.userId,
  properties: { plan: 'pro' },
  optedOut: request.headers.get('Sec-GPC') === '1' || request.headers.get('DNT') === '1',
})

if (user.enabled('new-checkout')) {
  // the new checkout
}

const headline = user.variant('pricing-test', 'control')
const limits = user.config('checkout-limits', { maxItems: 10 })

The first for() waits up to 1.5 seconds for the flag document. After that, reads are synchronous. A for() more than 30 seconds after the last fetch starts a refresh in the background (with If-None-Match) and answers from the document it has. Reads never throw: a flag that is missing, unreadable or not loaded yet answers your fallback. Failed fetches, and each unreadable flag once, go to onError.

On Cloudflare Workers, keep one MiraFlags per isolate and pass each request's waitUntil, so refreshes and exposures leave with that request:

const user = await flags.for({ userId }, { waitUntil: (promise) => ctx.waitUntil(promise) })

What a unit takesCopy Anchor Link

Without experiments consent, the anonymous id is not used and every experiment answers its default. Without targeting consent, no segment is looked up and segment conditions are false. See Feature flags and Experiments.

Segment lookupsCopy Anchor Link

When a flag tests a segment, for() asks MIRA FIVE which segments the unit is in (POST /v1/flags/segments). The lookups of one tick share requests of up to 100 units, wait at most 300 ms and are cached for a minute. A failed lookup makes segment conditions false, and evaluate() reports MEMBERSHIP_UNAVAILABLE.

ExperimentsCopy Anchor Link

enabled, variant and config count the unit in an experiment counted on the server: one $exposure per unit, variant and hour, sent through mira. evaluate(key) explains an answer and never counts. An experiment counted in the browser answers its default on the server (NOT_ALLOWED); a bootstrap hands it to the browser instead.

Server renderingCopy Anchor Link

Render the server's answers into the page, so the browser SDK starts from them and the first render matches:

import { bootstrapHeaders } from '@mirafive/sdk-server/flags'

const html = `<!doctype html><html><head>${user.bootstrap()}</head><body></body></html>`

return new Response(html, { headers: { 'Content-Type': 'text/html', ...bootstrapHeaders } })

bootstrap() returns <script type="application/json" id="mirafive-flags">…</script> with <, >, &, U+2028 and U+2029 escaped. It carries only flags the website reads too, never server-only values. bootstrapHeaders is Cache-Control: private, no-store: the block belongs to one visitor, so send it with every page that carries one. React and the browser SDK read the same block.

SnapshotsCopy Anchor Link

flags.snapshot() returns the document in use. Store it at build time and pass it back as document: it answers at once, before the first fetch, while it is younger than 7 days.

ErrorsCopy Anchor Link

track(), identify() and flush() never throw for transport reasons. Their failures go to onError (default: console.warn), including batches the server accepted but dropped for ingestion_paused or allowance_exhausted. send() rejects with a MiraError. Flag reads never throw; their failures go to the onError of MiraFlags.

import { Mira, MiraError } from '@mirafive/sdk-server'

const mira = new Mira({
  key: process.env.MIRAFIVE_SECRET_KEY,
  onError: (error: MiraError) => console.error('[mirafive]', error.code, error.status, error.message),
})

MiraError extends Error with code, status?, retryable, retryAfterMs? and errors? (for validation_failed, up to 10 { path, message }).

Retries use full-jitter backoff (250 ms doubling, at most 4 s) and resend the byte-identical body. Buffered deliveries honour Retry-After up to 30 seconds. The server's error format is described in Ingest API errors.

API referenceCopy Anchor Link

import { Mira, MiraError } from '@mirafive/sdk-server'
import type {
  EventOptions,
  Events,
  Fetch,
  Json,
  MiraErrorCode,
  MiraErrorInit,
  MiraOptions,
  Mode,
  Page,
  Receipt,
  Scope,
  SendEvent,
  SendOptions,
} from '@mirafive/sdk-server'

import { bootstrapHeaders, MiraFlags } from '@mirafive/sdk-server/flags'
import type {
  Bootstrap,
  Flag,
  FlagDocument,
  FlagErrorCode,
  FlagEvaluation,
  FlagUnit,
  ForOptions,
  MiraFlagsOptions,
  MiraFlagsStatus,
  UserFlags,
} from '@mirafive/sdk-server/flags'

new Mira<Events>(options)Copy Anchor Link

Receipt is { batch, accepted, dropped, reason? }. dropped > 0 with a reason (bot, install_check, ingestion_paused, allowance_exhausted) means nothing was kept. A receipt is final: it is never retried.

new MiraFlags(options)Copy Anchor Link

A failed refresh keeps the last document and backs off up to 5 minutes.

UserFlagsCopy Anchor Link

evaluate() returns { variant, reason, rule?, errorCode? } or { reason: 'ERROR', errorCode }. Reasons: STATIC, TARGETING_MATCH, SPLIT, DEFAULT, DISABLED. Error codes: NOT_READY (no document yet), FLAG_NOT_FOUND (not a flag of this source), UNSUPPORTED (a newer or broken flag format). Beside a variant: MEMBERSHIP_UNAVAILABLE (segments could not be looked up, so their conditions were false) and NOT_ALLOWED (no consent, or an experiment counted in the browser; the default is served).

bootstrapHeaders is { 'Cache-Control': 'private, no-store' }.

TroubleshootingCopy Anchor Link

Set up with an AI agentCopy Anchor Link

Paste this into your coding agent:

Add MIRA FIVE server-side analytics (and feature flags, if the project uses them) with @mirafive/sdk-server.
Docs: https://docs.mirafive.io/sdks/node.md

1. Install @mirafive/sdk-server with the project's package manager (Deno: deno add npm:@mirafive/sdk-server).
   If this is a Next.js, TanStack Start, Nuxt, Astro or Convex project, use that framework's MIRA FIVE package instead.
2. Read the secret key from MIRAFIVE_SECRET_KEY and add MIRAFIVE_SECRET_KEY= to .env.example.
   It is server-only: never import this package or the key into browser code.
3. Create one client in a server-only module:
     export const mira = new Mira({ key: process.env.MIRAFIVE_SECRET_KEY })
   from '@mirafive/sdk-server'. On Cloudflare Workers create it once per isolate from env.MIRAFIVE_SECRET_KEY.
4. Make sure events leave before the process or function ends:
   - long-running Node, Bun or Deno server: await mira.shutdown() on SIGTERM;
   - Cloudflare Workers: ctx.waitUntil(mira.flush()) in every request;
   - Vercel functions: pass waitUntil from '@vercel/functions' to new Mira();
   - scripts: await mira.flush() before exit.
5. Track the few business events that matter where they happen, e.g.
     mira.track('signup', { userId: user.id, properties: { plan } })
   and call mira.identify(user.id, { plan }) after signup and login. Use the internal user id, never an email.
   For webhooks, use await mira.send([...], { idempotencyKey: event.id }).
6. Only if the project uses feature flags: export const flags = new MiraFlags({ key: process.env.MIRAFIVE_SECRET_KEY, mira })
   from '@mirafive/sdk-server/flags', then (await flags.for({ userId: user.id })).enabled('key').
   Pass optedOut: true when the request has Sec-GPC: 1 or DNT: 1.
7. Keep the default full mode (the app holds consent). For anonymous counts only, use
   mode: 'consentless' and pass no userId, anonymousId or sessionId.
8. Verify: run await mira.send([{ name: '$install_check' }]) once and check that the receipt's
   reason is 'install_check'. Report what you changed.
Do not add other analytics libraries, cookies or consent banners.