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.

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

Development

`bash


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:

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

$3

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.

---

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.

$3

1) Bump the version in layers/ui/package.json
- Option A (recommended): use npm version without creating a tag
- Bash:
`bash
cd layers/ui
npm version patch --no-git-tag-version # or minor | major
`
- PowerShell:
`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)
`bash
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:
`bash
cd layers/ui
VERSION=$(node -p "require('./package.json').version")
cd ../..
git tag "ui-v$VERSION"
git push origin "ui-v$VERSION"
`
- PowerShell:
`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@, publishes if not found

$3


- 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.