Nuxt

Identify with a client plugin and verify in a Nitro server route.

10 minutes

This quickstart adds Trace to a Nuxt 3 app with the @trace-id/sdk-nuxt module. It sets up the client, a composable identifies the visitor, and a Nitro server route verifies the event with your secret key.

Before you start

You need a running Trace server, a public key (pk_...) whose allowed origins include your site, and a secret key (sk_...) for the server. The quick start guide creates both.

  1. 1

    Install the module

    npm install @trace-id/sdk-nuxt @trace-id/sdk-node
  2. 2

    Register it

    TypeScript
    // nuxt.config.ts
    export default defineNuxtConfig({
      modules: ['@trace-id/sdk-nuxt'],
      trace: { apiKey: 'pk_...', endpoint: 'https://id.example.com' },
      runtimeConfig: {
        traceSecretKey: '', // NUXT_TRACE_SECRET_KEY, server only
      },
    });

    You can leave apiKey and endpoint out and set NUXT_PUBLIC_TRACE_KEY and NUXT_PUBLIC_TRACE_ENDPOINT instead. The module adds a client-only plugin, so collection only runs in the browser, and auto-imports useVisitorData() and useIdentifyClient(). Never put a secret key under trace; it is public config.

    Already using @trace-id/sdk-vue directly?

    That still works: install the plugin yourself in a plugins/trace.client.ts with createIdentify(...). The module is the shorter path.

  3. 3

    Identify on submit

    Vue
    <!-- pages/signup.vue -->
    <script setup lang="ts">
    const email = ref('');
    const { getData, isLoading } = useVisitorData({ immediate: false });
    
    async function submit() {
      const result = await getData({ tags: { action: 'signup' } }); // null if Trace is unavailable
      await $fetch('/api/signup', {
        method: 'POST',
        headers: { 'x-trace-event-id': result?.eventId ?? '' },
        body: { email: email.value },
      });
    }
    </script>
    
    <template>
      <form @submit.prevent="submit">
        <input v-model="email" type="email" required />
        <button :disabled="isLoading">Create account</button>
      </form>
    </template>
  4. 4

    Verify in a server route

    TypeScript
    // server/api/signup.post.ts
    import { verifyEvent } from '@trace-id/sdk-node';
    
    export default defineEventHandler(async (event) => {
      const config = useRuntimeConfig(event);
      const eventId = getHeader(event, 'x-trace-event-id');
    
      let verified = null;
      if (eventId) {
        try {
          verified = await verifyEvent(eventId, {
            secretKey: config.traceSecretKey,
            endpoint: config.public.traceEndpoint,
            timeoutMs: 1500,
          });
        } catch (err) {
          console.warn('Trace check skipped', (err as { code?: string }).code); // fail open
        }
      }
    
      if (verified && verified.suspectScore >= 60) {
        throw createError({ statusCode: 403, statusMessage: 'blocked' });
      }
    
      const { email } = await readBody(event);
      // create the account, and store verified?.visitorId with it for later lookups
      return { ok: true };
    });

    Start in shadow mode

    For the first week, log event.suspectScore and event.reasons instead of blocking. Look at who would have been blocked, then pick thresholds you trust.

  5. 5

    Other backends

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.