Runtime support

Use this page before moving code between browser, Nuxt, Node.js, Worker, and test environments.

Browser

Browser mini apps can use:

• @onmax/nimiq-mini-app-kit
• @onmax/nimiq-mini-app-kit/dev in local development
• @onmax/better-auth-nimiq/client
• @onmax/better-auth-cross-device/client
• @onmax/cross-device-nimiq
• @onmax/unerc20
• @onmax/unimiq

Provider helpers that read window require browser runtime.

import { initMiniAppProvider } from '@onmax/nimiq-mini-app-kit'
import { signInWithNimiq } from '@onmax/better-auth-nimiq/client'

const provider = await initMiniAppProvider()

await signInWithNimiq(authClient.$fetch.bind(authClient), {
  provider,
  appName: 'Arcade Rewards',
})

Use browser runtime when a user gesture, injected provider, localStorage, or EventSource is part of the flow.

Do not import browser provider helpers from server middleware.

Nuxt

Nuxt apps can use:

• @onmax/nimiq-mini-app-kit/nuxt for simulator sidecar and i18n bridge.
• @onmax/unimiq/nuxt for the generic Nimiq facade.
• Better Auth plugins on the server side.

Register the modules separately. They solve different problems.

export default defineNuxtConfig({
  modules: [
    '@onmax/unimiq/nuxt',
    '@onmax/nimiq-mini-app-kit/nuxt',
  ],
  unimiq: {
    network: 'test',
    rpcUrl: process.env.NIMIQ_RPC_URL,
  },
})

Use @onmax/unimiq/nuxt for the generic $nimiq runtime. Use @onmax/nimiq-mini-app-kit/nuxt for the mini-app simulator sidecar and host-language bridge.

Node.js

Node.js can use server packages, tests, and RPC-backed @onmax/unimiq.

Set rpc.url for @onmax/unimiq; direct web-client loading is not the server path.

import { createNimiq } from '@onmax/unimiq'
import { createRpcNimiqDriver } from '@onmax/unimiq/drivers'

export const nimiq = createNimiq({
  driver: createRpcNimiqDriver({
    networkId: 24,
    rpc: {
      url: process.env.NIMIQ_RPC_URL!,
    },
  }),
})

Use Node.js for Better Auth plugins, nonce stores, ledger services, and test runners.

Do not expect window.nimiq, window.ethereum, or browser localStorage to exist.

Cloudflare Workers

Cloudflare Workers can use server-side auth code and RPC-backed @onmax/unimiq.

Set rpc.url in Worker runtime. Direct @nimiq/core loading is not supported in workerd.

import { createNimiq } from '@onmax/unimiq'
import { createRpcNimiqDriver } from '@onmax/unimiq/drivers'

export function createWorkerNimiq(env: { NIMIQ_RPC_URL: string }) {
  return createNimiq({
    driver: createRpcNimiqDriver({
      networkId: 24,
      rpc: {
        url: env.NIMIQ_RPC_URL,
      },
    }),
  })
}

Use Workers for verification and data reads that can go through HTTP RPC.

Do not use direct @nimiq/core loading in workerd.

Tests

Use @onmax/better-auth-nimiq-pay-e2e and @onmax/nimiq-mini-app-kit/dev for deterministic tests.

Use bridge mode only when the test environment can publish the injected provider.

import { expect, test } from 'vitest'
import { createLocalAuthFetcher, runSignInScenario } from '@onmax/better-auth-nimiq-pay-e2e'

test('local Nimiq auth flow', async () => {
  const fetcher = createLocalAuthFetcher({
    appName: 'Arcade Rewards',
    origin: 'https://arcade.example',
  })

  const result = await runSignInScenario({ fetcher })

  expect(result.ok).toBe(true)
})

Expected behavior: local scenarios exercise nonce, sign, and verify without requiring the real Nimiq Pay bridge.