Nuxt UI Layer

A Nuxt layer that integrates the Nuxt UI framework (v4) with Nuxt 4 projects.

Features

• Full integration of Nuxt UI v4 components and composables
• Tailwind CSS 4 support
• Optimized for performance and accessibility

Configuration

The UI layer includes the @nuxt/ui module for seamless integration.

// nuxt.config.ts in the ui layer
export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run ESLint
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Run TypeScript type checking
npm run typecheck

Usage

To use this layer in your Nuxt project:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@cooperco/nuxt-layer-ui'
  ],
  build: {
    transpile: ['vue']
  }
})

Important: Vue Transpilation

When extending this layer, you must add vue to the build.transpile array in your nuxt.config.ts.

Without this configuration, using core Nuxt UI components like UApp may cause the application to crash or behave unexpectedly. This is due to how Nuxt handles Vue dependencies when they are provided through multiple layers, which can sometimes lead to multiple instances of Vue being loaded. Transpiling vue ensures that the entire application uses a single, consistent Vue instance.

For more technical details, see this Nuxt UI issue.

This will automatically include the UI layer features.

Dependencies

The UI layer includes:

• @nuxt/ui
• @iconify-json/lucide
• @iconify-json/simple-icons

These provide the modern Nuxt UI framework experience within your Nuxt application.

Honeypot

This layer ships an anti-bot honeypot field for forms. It catches naive crawlers that fill every input on a page, without interfering with password managers or accessibility tools.

What it catches — and what it doesn't

| Catches | Doesn't catch | | --- | --- | | Crawlers that fill every form input ("filled" reason) | Sophisticated headless bots that parse CSS / respect aria-hidden | | Scripted submissions faster than a human can type ("too-fast" reason) | Targeted attacks by humans |

Pair this with rate limiting, IP reputation, or a challenge like Cloudflare Turnstile on high-value endpoints. The honeypot is the first cheap layer, not the only one.

Pieces

Three things, in a single self-contained layer:

• <honeypot-field> — the offscreen decoy input. Auto-imported component.
• useHoneypot() — composable that owns state (value, startedAt) and exposes validate() and reset(). Auto-imported composable.
• checkHoneypot() — pure validation function living in shared/utils/. Auto-imported in both Nuxt app code and Nitro server routes, so you can revalidate server-side with zero imports.

Shared types (HoneypotCheckResult, HoneypotInvalidReason, etc.) live in shared/types/honeypot.ts.

Minimal usage

<script setup lang="ts">
const hp = useHoneypot({
  onInvalid: (reason) => {
    // Optional: log via your own logger. The ui layer stays framework-free
    // and intentionally does not depend on the base layer's `useLogger()`.
    console.warn('honeypot rejected', reason)
  }
})

const form = reactive({ name: '', email: '', message: '' })

async function onSubmit() {
  const check = hp.validate()
  if (!check.valid) {
    // Show the same neutral toast either way — bots get no feedback.
    return
  }
  await $fetch('/api/contact', {
    method: 'POST',
    body: {
      ...form,
      website: hp.state.value,   // honeypot decoy
      _hp_ts: hp.state.startedAt // time-trap timestamp
    }
  })
  hp.reset()
}
</script>

<template>
  <form @submit.prevent="onSubmit">
    <u-form-field label="Name"><u-input v-model="form.name"/></u-form-field>
    <u-form-field label="Email"><u-input v-model="form.email" type="email"/></u-form-field>
    <u-form-field label="Message"><u-textarea v-model="form.message"/></u-form-field>

    <honeypot-field
      v-model="hp.state.value"
      :field-name="hp.fieldName"
    />

    <u-button type="submit">Send</u-button>
  </form>
</template>

Server-side revalidation

Client-side validate() is a usability optimization, not a security boundary — a bot can POST directly to your endpoint and skip the client code. Always revalidate on the server. checkHoneypot() is auto-imported in Nitro:

// server/api/contact.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody<Record<string, unknown>>(event)

  const check = checkHoneypot({
    value: typeof body?.website === 'string' ? body.website : '',
    startedAt: typeof body?._hp_ts === 'number' ? body._hp_ts : 0
  })

  if (!check.valid) {
    // Return 200 with a fake-success body so bots can't tell they were caught.
    return { ok: true }
  }

  // ...real submission handling
  return { ok: true }
})

Options

useHoneypot({ fieldName, minFillMs, onInvalid }):

• fieldName (default 'website') — the DOM input name. website is used because password managers don't autofill URL-shaped fields. Override if your real form already has a website input, picking something equally boring and plausible (homepage, fax).
• minFillMs (default 1500) — minimum realistic fill time. Submissions faster than this get { valid: false, reason: 'too-fast' }. Set 0 to disable the time trap.
• onInvalid (optional callback) — fires when validate() rejects. Use this to log to your observability pipeline. Wiring it to useLogger() from the base layer is the common pattern.

Known limitations

• Unsigned startedAt. The client's _hp_ts is untrusted — a bot can send a fake timestamp to bypass the time-trap. A future upgrade path is to HMAC-sign the timestamp server-side and verify the signature in checkHoneypot(). For v1, the time-trap is advisory: it catches naive bots, not determined ones.
• No rate limiting. A bot with an empty honeypot and a plausible-looking _hp_ts can still hammer your endpoint. Layer nuxt-security or a Nitro middleware on top for high-volume endpoints.
• Sophisticated bots that parse CSS will skip the offscreen field and never trip the trap. Pair with CAPTCHA / Cloudflare Turnstile on endpoints that need stronger protection.

Claude Code Skills

This repo includes Claude Code skills for common tasks in apps that use these layers. To use them, copy the relevant skill files from the skills/ directory into your app's .claude/skills/ directory.

Skills provided by the UI layer:

| Skill | File | Description | |-------|------|-------------| | /add-page | skills/add-page.md | Scaffold a Nuxt page with Nuxt UI v4 components, <i18n> block, and useSeoMeta() | | /add-component | skills/add-component.md | Scaffold a Vue component with Nuxt UI v4 primitives, typed props/emits, and <i18n> block |

# Copy UI layer skills into your app
mkdir -p .claude/skills
cp node_modules/@cooperco/nuxt-layer-ui/../../skills/add-page.md .claude/skills/
cp node_modules/@cooperco/nuxt-layer-ui/../../skills/add-component.md .claude/skills/

Or copy them directly from the nuxt-layers repository.

Publishing to npm (tag-based)

This layer is published using GitHub Actions when you push a tag that matches the ui-vX.Y.Z pattern.

High-level flow:

• Bump the version in layers/ui/package.json (SemVer).
• Commit and push your changes to main (or ensure the commit is on main).
• Create and push a tag named ui-vX.Y.Z (matching the package.json version).
• The Publish UI Layer workflow installs deps, checks if that exact version already exists on npm, and if not, publishes to npm.

Important notes:

• Do NOT rely on npm version creating a tag for you (it will create vX.Y.Z). We use a custom tag prefix ui-v.
• The workflow will skip if the version already exists.

Step-by-step

1. Bump the version in layers/ui/package.json

• Option A (recommended): use npm version without creating a tag
  • Bash:

    cd layers/ui
    npm version patch --no-git-tag-version  # or minor | major

  • PowerShell:

    Set-Location layers/ui
    npm version patch --no-git-tag-version  # or minor | major

• Option B: manually edit the version field in layers/ui/package.json (SemVer: MAJOR.MINOR.PATCH)

2. Commit and push the change (from repo root or layers/ui)

git add layers/ui/package.json
git commit -m "chore(ui): bump version"
git push origin main

3. Create and push the tag using the new version

• Get the new version value:
  • Bash:

    cd layers/ui
    VERSION=$(node -p "require('./package.json').version")
    cd ../..
    git tag "ui-v$VERSION"
    git push origin "ui-v$VERSION"

  • PowerShell:

    Set-Location layers/ui
    $version = node -p "require('./package.json').version"
    Set-Location ../..
    git tag "ui-v$version"
    git push origin "ui-v$version"

4. GitHub Actions will publish

• Workflow: .github/workflows/publish-ui.yml
• Auth: uses NPM_TOKEN configured as a GitHub secret
• Behavior: installs, checks npm view @cooperco/nuxt-layer-ui@<version>, publishes if not found

Troubleshooting

• Version already exists: bump the version again (patch/minor/major) and push a new tag.
• Auth errors (401/403): ensure NPM_TOKEN is set in repo secrets and org access is correct.