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.

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.