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
Install the module
npm install @trace-id/sdk-nuxt @trace-id/sdk-nodepnpm add @trace-id/sdk-nuxt @trace-id/sdk-nodeyarn add @trace-id/sdk-nuxt @trace-id/sdk-nodebun add @trace-id/sdk-nuxt @trace-id/sdk-node - 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
apiKeyandendpointout and setNUXT_PUBLIC_TRACE_KEYandNUXT_PUBLIC_TRACE_ENDPOINTinstead. The module adds a client-only plugin, so collection only runs in the browser, and auto-importsuseVisitorData()anduseIdentifyClient(). Never put a secret key undertrace; it is public config.Already using @trace-id/sdk-vue directly?
That still works: install the plugin yourself in a
plugins/trace.client.tswithcreateIdentify(...). The module is the shorter path. - 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
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.suspectScoreandevent.reasonsinstead of blocking. Look at who would have been blocked, then pick thresholds you trust. - 5
Other backends