docs
Mini Apps

Nuxt module

Add the mini-app simulator sidecar and runtime helpers to Nuxt.

Use @onmax/nimiq-mini-app-kit/nuxt when a Nuxt app needs the mini-app simulator sidecar, devtools tab, development provider bootstrap, or Nuxt i18n bridge.

Do not use this module as a replacement for generic Nimiq runtime injection. Add @onmax/unimiq/nuxt separately when the app also needs the generic $nimiq facade.

Register the module

nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@onmax/unimiq/nuxt',
    '@onmax/nimiq-mini-app-kit/nuxt',
  ],
  nimiqMiniAppSimulator: {
    appName: 'Dino Checkout',
  },
})

Expected behavior in Nuxt dev:

  • The module adds typed mini-app injections.
  • The module can start the simulator sidecar.
  • The DevTools tab opens the simulator iframe when the sidecar is running.

Expected behavior in production:

  • The module does not start the sidecar.
  • Provider access still comes from the Nimiq Pay host environment.

Configure the simulator sidecar

Use explicit simulator options when your mobile device or host shell needs a stable URL.

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@onmax/nimiq-mini-app-kit/nuxt'],
  nimiqMiniAppSimulator: {
    enabled: true,
    host: '0.0.0.0',
    port: 4174,
    appName: 'Dino Checkout',
    appUrl: 'http://localhost:3000',
    rpcUrl: 'https://rpc.nimiq.dev',
    initialBalanceLuna: 9000,
  },
})

Equivalent environment variables:

.env
NUXT_NIMIQ_SIMULATOR_ENABLED=true
NUXT_NIMIQ_SIMULATOR_HOST=0.0.0.0
NUXT_NIMIQ_SIMULATOR_PORT=4174
NUXT_NIMIQ_SIMULATOR_APP_NAME="Dino Checkout"
NUXT_NIMIQ_SIMULATOR_APP_URL=http://localhost:3000
NUXT_NIMIQ_SIMULATOR_RPC_URL=https://rpc.nimiq.dev
NUXT_NIMIQ_SIMULATOR_INITIAL_BALANCE_LUNA=9000

Expected sidecar URL:

output
http://127.0.0.1:4174

Read Nuxt-injected providers

Use the injected providers for app code that runs after the Nuxt plugin bootstrap.

app/components/PayWithNim.vue
<script setup lang="ts">
import { isMiniAppProviderError } from '@onmax/nimiq-mini-app-kit'

const { $nimiqMiniAppProvider, $nimiqMiniAppProviderSource } = useNuxtApp()

async function pay() {
  if (!$nimiqMiniAppProvider)
    throw new Error('Open this checkout inside Nimiq Pay.')

  const txHash = await $nimiqMiniAppProvider.sendBasicTransactionWithData({
    recipient: 'NQ72H8J9MQ3RHPTC53HRS1YFCJA292LDVVFG',
    value: 1_000,
    fee: 0,
    data: 'order:42',
  })

  if (isMiniAppProviderError(txHash))
    throw new Error(txHash.error.message)

  return txHash
}
</script>

<template>
  <button :disabled="!$nimiqMiniAppProvider" @click="pay">
    Pay
  </button>
  <p v-if="$nimiqMiniAppProviderSource === 'dev-blocking'">
    Local simulator provider
  </p>
</template>

Provider source values:

  • real: injected by Nimiq Pay or already present in the page.
  • host-bridge: launched from the simulator host window.
  • dev-blocking: created by the Nuxt development bootstrap.
  • none: no mini-app provider is available.

Detect provider state manually

Use runtime helpers when a composable or plugin needs a provider state object before the Nuxt injections are available.

app/plugins/mini-app-state.client.ts
import {
  detectNuxtMiniAppProvider,
  resolveNuxtMiniAppProviderState,
} from '@onmax/nimiq-mini-app-kit/nuxt/runtime'

export default defineNuxtPlugin(async () => {
  const provider = await detectNuxtMiniAppProvider({
    client: import.meta.client,
    timeout: 750,
    intervalMs: 25,
  })

  const state = resolveNuxtMiniAppProviderState({
    client: import.meta.client,
    injectedProvider: provider,
    injectedSource: provider ? 'real' : undefined,
  })

  return {
    provide: {
      miniAppState: state,
    },
  }
})

Expected state outside Nimiq Pay after detection finishes:

output
{
  "provider": null,
  "source": "none",
  "available": false,
  "detecting": false
}

Add the i18n bridge only when Nuxt i18n owns locales

The module registers the bridge only when @nuxtjs/i18n is present and nimiqMiniAppSimulator.i18n is enabled.

nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/i18n',
    '@onmax/nimiq-mini-app-kit/nuxt',
  ],
  i18n: {
    locales: ['en', 'de', 'es'],
    defaultLocale: 'en',
  },
  nimiqMiniAppSimulator: {
    i18n: {
      useCookie: false,
    },
  },
})

Use i18n: false when the app should ignore the host language.

Use i18n: { useCookie: true } only when you want Nuxt i18n to persist the host-selected locale.

Runtime rules

  • Use this module for Nuxt dev integration and host language bridging.
  • Use root package imports for app-level provider calls.
  • Keep simulator wallet seeds in local development configuration.
  • Do not depend on the simulator sidecar in production.

Local simulator

Install simulated Nimiq and Ethereum providers for local development and tests.

Host runtime

Build custom simulator hosts with the host runtime subpath.

Copyright © 2026