Integrations

The layer includes optional integrations for AI assistance, API reference and SEO optimization.You can configure these integrations via nuxt.config.ts and environment variables.

Configure the assistant

The starter provides an assistant endpoint and uses the ai configuration from the layer. A consumer can override the model and behavior without changing shared server code:

export default defineNuxtConfig({
  ai: {
    model: "mistral-large-latest",
    maxOutputTokens: 12000,
    maxRetries: 3,
    maxSteps: 12,
    temperature: 0.2,
    systemPrompt: "You are the documentation assistant for Example Docs."
  }
});

The systemPrompt replaces the generated documentation-aware prompt. Supply provider API keys through the environment rather than committing them to the repository.

Add API reference content

When OpenAPI settings are provided, the layer can create searchable API content and interactive reference from a local or remote OpenAPI document. For adding a single OpenAPI spec you can use environment variables:

OPENAPI_SOURCE_TYPE=remote
OPENAPI_SOURCE_LOCATION=https://example.com/openapi.json
# or
OPENAPI_SOURCE_TYPE=local
OPENAPI_SOURCE_LOCATION=/some-public-path/spec.yaml

Keep API source selection site-specific. The reusable layer only provides the collection and module integration.

See Scalar and OpenAPI reference for multi-spec setup, background on how the document is parsed and how the generated API content is used by search and the assistant.

Enable Plausible Analytics

Enable Plausible by setting the domain to track in the deployment environment. When it is not set, the layer derives the domain from NUXT_PUBLIC_SITE_URL.

NUXT_PUBLIC_SITE_URL=https://docs.example.com
# Optional when the tracked domain differs from the site URL
PLAUSIBLE_DOMAIN=docs.example.com

Set DISABLE_TRACKING=true to disable custom tracking events. The Plausible integration does not place cookies, and the layer does not configure another tracking service to do so. Enabling it therefore does not require a cookie banner.

Track custom events

Use the auto-imported useTracking() composable in client-side components to record custom events. trackEvent() accepts an event name and a payload with a required event_category and optional event_label and event_value strings. It does nothing during server rendering or when DISABLE_TRACKING=true.

<script setup lang="ts">
const { trackEvent } = useTracking();

function trackDownload() {
  trackEvent("documentation_downloaded", {
    event_category: "engagement",
    event_label: "quickstart-pdf"
  });
}
</script>

<template>
  <UButton @click="trackDownload">Download quickstart</UButton>
</template>

Enable Cloudflare Turnstile

Set both keys in the deployment environment to enable Turnstile:

TURNSTILE_SITE_KEY=your-site-key
TURNSTILE_SECRET_KEY=your-secret-key

Create and configure the widget in the Cloudflare Turnstile documentation. The layer always uses Turnstile in invisible mode, so visitors do not interact with a visible widget. Turnstile still processes visitor or browser signals; when you enable it, mention its use in your privacy policy.

Use Turnstile in a client-side form

The auto-imported useTurnstile() composable manages the widget token. Its API is:

• token — the Ref<string | undefined> bound to <NuxtTurnstile> with v-model.
• isEnabled — whether a public site key is configured.
• getToken() and getTokenWithRetry(retries?, delayMs?) — retrieve the current token, with an optional retry while the invisible check completes.
• isReady() — returns true when Turnstile is disabled or a token is available.
• reset(instance?) — clears the token and resets the widget instance after a request.
• showPendingHint(), showMissingTokenErrorHint(), and captureTurnstileError(error) — show the standard security-check feedback; captureTurnstileError returns whether it handled the error.

<script setup lang="ts">
const turnstile = useTurnstile();
const widget = useTemplateRef("turnstile");

async function submitForm() {
  const token = await turnstile.getTokenWithRetry();
  if (!token) {
    turnstile.showMissingTokenErrorHint();
    return;
  }

  await $fetch("/api/contact", {
    method: "POST",
    headers: { "x-turnstile-token": token }
  });

  turnstile.reset(widget.value as { reset: () => void });
}
</script>

<template>
  <form @submit.prevent="submitForm">
    <NuxtTurnstile
      ref="turnstile"
      v-model="turnstile.token"
      :options="{ action: 'contact_submit', appearance: 'interaction-only' }"
      class="pointer-events-none absolute h-0 w-0 overflow-hidden opacity-0"
    />
    <UButton type="submit">Send</UButton>
  </form>
</template>

Validate Turnstile on the server

Protect the corresponding server route with the auto-imported assertTurnstileToken(event, expectedAction) handler. It reads the token from the x-turnstile-token header, validates it with Cloudflare, and checks that the action matches. It returns nothing when the request is valid; otherwise it throws an H3 error with a stable Turnstile error code in data.code.

export default defineEventHandler(async (event) => {
  await assertTurnstileToken(event, "contact_submit");

  // Process the validated request.
  return useApiResponse({ success: true });
});

Enable the Mailchimp newsletter

The newsletter banner is displayed on documentation pages only when Mailchimp is configured. Add all three values to the consumer's deployment environment:

MAILCHIMP_API_KEY=xxxx-us4
MAILCHIMP_LIST=your-audience-id
MAILCHIMP_SERVER=us4

MAILCHIMP_SERVER is the Mailchimp data center suffix from the API key (for example, us4 from xxxx-us4). MAILCHIMP_LIST is the ID of the audience that receives subscriptions. The API key is server-only; do not expose it through public runtime configuration or commit it to the repository.

When any value is missing, the Mailchimp module, signup endpoint, and newsletter banner remain disabled. You can customise the banner copy in Customize the UI.

Configure site identity

Set the public URL and site identity in the consumer. The URL is used for canonical links, sitemap entries, and absolute social image URLs:

export default defineNuxtConfig({
  site: {
    url: "https://docs.example.com",
    name: "Example Docs",
    description: "Documentation for the Example platform."
  }
});

In the deployment environment, set the corresponding public URL:

NUXT_PUBLIC_SITE_URL=https://docs.example.com