Nuxt X App

A comprehensive Nuxt layer providing production-ready admin dashboard components, CRUD operations, and utilities built on Nuxt UI v4.

Prerequisites

• Node.js 18.0 or higher
• Nuxt 4.x
• Package Manager: npm, pnpm, or yarn

For detailed setup instructions, see INSTALLATION.md

Features

• 60+ Components - Complete UI library for admin dashboards
• 10+ Composables - CRUD, data fetching, and UI utilities
• Responsive - Mobile-first design with collapsible layouts
• TypeScript - Full type safety with exported types
• Auto-imports - Components and composables work out of the box (Prefix: XA)
• Dark Mode - Built-in dark mode support
• Nuxt Charts - Line, area, bar, donut, bubble, and gantt charts

Installation

# Install the layer (all dependencies included)
npm install @xenterprises/nuxt-x-app

Quick Start

1. Extend the Layer

Add the layer to your nuxt.config.ts:

export default defineNuxtConfig({
  extends: '@xenterprises/nuxt-x-app',

  // Optional: Set API URL for CRUD operations
  runtimeConfig: {
    public: {
      x: {
        app: {
          apiUrl: process.env.NUXT_PUBLIC_X_APP_API_URL,
        },
      },
    },
  },
})

2. Configure Dashboard (Optional)

Create app.config.ts to configure your dashboard:

export default defineAppConfig({
  xDashboard: {
    navigation: {
      mode: 'sidebar', // 'sidebar' | 'topnav' | 'both'
      sidebar: {
        brand: {
          title: 'My Dashboard',
          logo: '/logo.svg',
        },
        items: [
          {
            label: 'Dashboard',
            icon: 'i-lucide-layout-dashboard',
            to: '/dashboard',
          },
          {
            label: 'Users',
            icon: 'i-lucide-users',
            to: '/users',
          },
        ],
      },
    },
  },

  // Optional: Override default UI colors
  ui: {
    colors: {
      primary: 'blue',  // layer defaults to 'blue'
      gray: 'cool',     // layer defaults to 'cool'
    },
  },
})

Sidebar Styling

Customize sidebar appearance with these props on XALayout or XALayoutSidebar:

<XALayout
  color="primary"
  sidebar-background-color="bg-white dark:bg-neutral-900"
  sidebar-text-mode="dark"
>
  <!-- Content -->
</XALayout>

| Prop | Type | Default | Description | |------|------|---------|-------------| | color | String | 'primary' | Accent color for navigation items (Nuxt UI color) | | sidebarBackgroundColor | String | 'bg-white dark:bg-neutral-900' | Sidebar background CSS class | | sidebarTextMode | 'dark' \| 'light' | 'dark' | Text color mode - use 'light' for dark backgrounds |

Nuxt UI v4 Sidebar Configuration

XALayoutSidebar now renders the Nuxt UI v4 USidebar component, and mobile behavior is handled automatically by USidebar. The XALayoutMobileSidebar component is deprecated and should be removed from your layouts.

Configure the sidebar through xDashboard.navigation.sidebar in app.config.ts:

export default defineAppConfig({
  xDashboard: {
    navigation: {
      mode: 'sidebar',
      sidebar: {
        // Nuxt UI USidebar options
        variant: 'sidebar',      // 'floating' | 'sidebar' | 'inset'
        collapsible: true,       // boolean | 'offcanvas' | 'icon' | 'none'
        side: 'left',            // 'left' | 'right'
        mode: 'slideover',       // 'slideover' | 'modal' | 'drawer'
        rail: false,             // show a rail to toggle collapse
        close: true,             // show a close button on mobile
        transition: true,        // animate collapse/expand

        // Header
        title: 'My App',
        description: 'Admin dashboard',

        // Existing layer options
        collapsed: false,
        width: '256px',
        collapsedWidth: '64px',
        position: 'left',        // 'left' | 'right'
        brand: {
          title: 'My Dashboard',
          logo: '/logo.svg',
          collapsedLogo: '/icon.svg',
          to: '/',
        },
        items: [
          { label: 'Dashboard', icon: 'i-lucide-layout-dashboard', to: '/dashboard' },
          { label: 'Users', icon: 'i-lucide-users', to: '/users' },
        ],
        footerItems: [
          { label: 'Help', icon: 'i-lucide-help-circle', to: '/help' },
        ],

        // Styling
        ui: {},
        class: '',
      },
    },
  },
})

| Option | Type | Default | Description | |--------|------|---------|-------------| | variant | 'floating' \| 'sidebar' \| 'inset' | 'sidebar' | Visual style of the sidebar | | collapsible | boolean \| 'offcanvas' \| 'icon' \| 'none' | true | Whether and how the sidebar collapses. true maps to 'icon' | | side | 'left' \| 'right' | 'left' | Which side of the screen the sidebar renders on | | mode | 'slideover' \| 'modal' \| 'drawer' | 'slideover' | How the sidebar appears on mobile | | rail | boolean | false | Show a narrow rail for toggling collapse | | close | boolean | true | Show a close button in mobile/slideover mode | | transition | boolean | true | Animate the sidebar when opening/collapsing | | title | string | - | Title shown in the sidebar header | | description | string | - | Description shown below the title | | ui | Record<string, any> | - | Nuxt UI USidebar UI overrides | | class | string | - | Additional CSS classes for the sidebar |

Migration note: The layer has migrated to Nuxt UI v4 (@nuxt/ui ^4.9.0). XALayoutSidebar now wraps USidebar and handles responsive/mobile behavior internally. XALayoutMobileSidebar is deprecated and should be removed from your layouts. If you were previously toggling mobile sidebar state manually, use useXNavigation().toggleSidebarOpen() or rely on the header's built-in mobile toggle.

Dashboard Background

Customize the main content area background:

<XALayout
  background-color="bg-neutral-100/50 dark:bg-neutral-950"
>
  <!-- Content -->
</XALayout>

| Prop | Type | Default | Description | |------|------|---------|-------------| | backgroundColor | String | 'bg-neutral-100/50 dark:bg-neutral-950' | Main content area background CSS class |

3. Use Components

Components are auto-imported with the XA prefix:

<template>
  <XALayout>
    <XALayoutPageHeader
      title="Users"
      description="Manage your users"
    />

    <XATable
      :data="users"
      :columns="columns"
    />
  </XALayout>
</template>

<script setup lang="ts">
const { data: users } = useXCrud('/api/users')

const columns = [
  { key: 'name', label: 'Name' },
  { key: 'email', label: 'Email' },
  { key: 'status', label: 'Status' },
]
</script>

Components

Layout

• XALayout - Main dashboard layout with sidebar/topnav
• XALayoutHeader - Dashboard header with search and user menu
• XALayoutSidebar - Collapsible sidebar with navigation
• XALayoutBreadcrumbs - Breadcrumb navigation
• XALayoutPageHeader - Page title and actions

Data Display

• XATable - Advanced data table (TanStack Table)
• XADataStatusBadge - Status badges with color mapping
• XAAvatar - User profile images
• XAFmtCurrency - Formatted monetary values
• XAFmtDateTime - Date/time formatting
• XADataSkeleton - Loading placeholders
• XAStateEmpty - Empty state messaging

Navigation

• XALayoutContentNav - Content navigation tabs
• XALayoutResponsiveNav - Responsive navigation

Charts

• XAChartLine - Line charts for trends over time
• XAChartArea - Filled area charts
• XAChartBar - Vertical and horizontal bar charts
• XAChartDonut - Donut/pie charts with center content
• XAChartBubble - Multi-dimensional bubble charts
• XAChartGantt - Timeline/Gantt charts for schedules

Feedback

• XAStateError - Error states with retry
• XAStateLoading - Loading indicators
• XAModal - Dialog overlays
• XAModalConfirm - Confirmation dialogs

Buttons

• XABtnCopy - Copy to clipboard
• XABtnEdit - Edit button
• XABtnView - View button
• XABtnBack - Back navigation
• XABtnRefresh - Refresh with loading state
• XABtnExport - Export dropdown (CSV, Excel)

See all components →

Composables

All composables are auto-imported - no imports needed!

useXCrud - CRUD Operations

// List mode
const { data, loading, refresh, create, remove } = useXCrud('/api/users').all()

// Detail mode
const { data, form, save, update, remove } = useXCrud('/api/users').read(id)

// Create mode
const { form, save } = useXCrud('/api/users').create()

Full documentation →

Other Composables

// Table column presets
const { presets } = useXTableColumns()
const columns = [
  presets.avatar('name', 'User'),
  presets.email('email'),
  presets.badge('status', 'Status'),
  presets.actions()
]

// Enhanced fetch with loading states
const { data, loading, error, refresh } = useXFetch('/api/stats')

// File uploads
const { upload, progress, files } = useXFileUpload()

// Notifications
const notifications = useXNotifications()
notifications.add({ title: 'Success', status: 'success' })

See all composables →

Table Features

Auto-Date Formatting

XATable automatically detects and formats common date columns. Columns with these accessor keys are automatically formatted with relative time:

• createdAt, updatedAt, deletedAt, publishedAt
• startedAt, endedAt, dueDate, due_at
• expiresAt, completedAt, created_at, updated_at

<XATable
  :data="orders"
  :columns="[
    { accessorKey: 'name', header: 'Name' },
    { accessorKey: 'createdAt', header: 'Created' },  // Auto-formatted!
    { accessorKey: 'dueDate', header: 'Due' },        // Auto-formatted!
  ]"
/>

Override the auto-detection by specifying a preset:

const columns = [
  { accessorKey: 'createdAt', header: 'Created', meta: { preset: 'date', format: 'short' } }
]

TypeScript Support

Import types for better IDE support:

import type {
  NavItem,
  DashboardConfig,
} from '@xenterprises/nuxt-x-app/types'

// Use in your code
const navItems: NavItem[] = [
  { label: 'Home', to: '/' },
  { label: 'About', to: '/about' },
]

Auto-Imports

This layer leverages Nuxt's auto-import capabilities:

• Components: All components from app/components/X/A/ are auto-imported with XA prefix
• Composables: All composables from app/composables/ are auto-imported
• Types: Import types explicitly from @xenterprises/nuxt-x-app/types

Examples

Check the .playground directory for complete examples:

• CRUD Operations: .playground/pages/demo/crud.vue
• Data Tables: .playground/pages/demo/table.vue
• Forms: .playground/pages/demo/forms.vue
• User Management: .playground/pages/demo/users.vue
• Stats Dashboard: .playground/pages/demo/stats.vue

Documentation

Full documentation is available in the playground:

npm run dev
# Visit http://localhost:3000/components

Browse the playground for:

• Component demos with live examples
• Props and slots documentation
• Code samples for each component

Topics covered:

• Getting Started
• Layout Configuration
• Table Usage
• Data Display Components
• Form Integration
• CRUD Patterns

Configuration

Runtime Config

export default defineNuxtConfig({
  extends: '@xenterprises/nuxt-x-app',
  runtimeConfig: {
    public: {
      x: {
        app: {
          apiUrl: 'https://api.example.com',  // Your API base URL
          pdfLicense: 'your-pdf-license-key', // Optional: License for PDF viewer
        },
      },
    },
  },
})

Environment Variables

| Variable | Description | |----------|-------------| | NUXT_PUBLIC_X_APP_API_URL | API base URL for CRUD operations | | NUXT_PUBLIC_X_APP_PDF_LICENSE | License key for PDF viewer (optional) |

UI Colors

The layer uses Nuxt UI v4 components. Customize colors in app.config.ts:

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',   // layer default: 'blue'
      gray: 'cool',       // layer default: 'cool'
    },
  },
})

The consuming app's app.config.ts will override the layer's defaults.

App Config (xApp)

useXFetch supports an optional xApp.defaultHeaders factory in app.config.ts. It is invoked per request and its result is merged into every request — handy for global headers such as tenant IDs. Precedence: built-in defaults (Accept, Authorization, Content-Type) < xApp.defaultHeaders < per-call headers option.

export default defineAppConfig({
  xApp: {
    defaultHeaders: () => ({
      'x-tenant-id': useTenantStore().currentId,
    }),
  },
})

Migration from v0.3.x

Version 0.4.0 introduced namespaced runtime config to avoid conflicts with other Nuxt modules.

Environment Variable Changes

Before (v0.3.x):

NUXT_PUBLIC_X_APP_API_URL=https://api.example.com
# or
X_APP_API_URL=https://api.example.com

After (v0.4.0+):

NUXT_PUBLIC_X_APP_API_URL=https://api.example.com

Nuxt Config Changes

Before (v0.3.x):

runtimeConfig: {
  public: {
    xAppApiUrl: 'https://api.example.com',
  },
}

After (v0.4.0+):

runtimeConfig: {
  public: {
    x: {
      app: {
        apiUrl: 'https://api.example.com',
      },
    },
  },
}

Code Access

Before (v0.3.x):

config.public.xAppApiUrl

After (v0.4.0+):

config.public.x?.app?.apiUrl

The ?. optional chaining ensures backwards compatibility - if not configured, it will fall back to an empty string.

All Composables

| Composable | Purpose | |---|---| | useXCrud() | Full CRUD operations with caching, retry, optimistic updates | | useXFetch() | Auth-agnostic wrapper around useFetch/$fetch with token injection | | useXTableColumns() | Column definition factory with 12 presets (text, avatar, badge, date, currency, etc.) | | useColumns() | Shortcut wrapper for useXTableColumns presets | | useXFileUpload() | File upload with FormData handling and toast notifications | | useXNotifications() | Notification center with unread counter and status filtering | | useXToast() | Wrapper around Nuxt UI toast with success/error/info helpers | | useXNavigation() | Dashboard navigation state with sidebar collapse/expand | | useXKanban() | Kanban board state management with drag/drop and card CRUD | | useXInlineEdit() | Inline cell editing with save/cancel and pending change tracking | | useConfirm() | Promise-based confirmation dialog API | | useCurrentUser() | User state management with role checking and provide/inject | | useDataTable() | Table UI state (pagination, sorting, filtering, row selection) | | useDateTime() | Date formatting utility with locale support | | useBreadcrumb() | Breadcrumb state per route with automatic label derivation |

Error Reference

Components and composables use consistent error patterns:

| Error Source | Pattern | Example | |---|---|---| | useXCrud | Toast notification with configurable messages per operation | errorMessages: { create: 'Failed to create user' } | | useXFetch | Returns { error } ref with fetch error details | Check error.value after fetch | | useXFileUpload | Toast notification + re-throws error | Wrap in try/catch for custom handling | | useConfirm | Resolves false on cancel (never rejects) | if (await confirm(...)) { ... } | | XABtnConfirmDelete | Emits @error event with error object | <XABtnConfirmDelete @error="handleError" /> | | XABtnEdit | Emits @error event with error object | <XABtnEdit @error="handleError" /> |

How It Works

nuxt-x-app is a Nuxt layer that auto-registers its components, composables, and configuration when extended by a consuming app.

Layer structure:

• nuxt.config.ts — Registers modules (@nuxt/ui, @nuxtjs/color-mode, nuxt-charts), imports the layer's CSS, and defines the runtimeConfig.public.x.app namespace.
• app/components/X/A/ — All components are auto-imported by Nuxt with the XA prefix (derived from the directory path X/A).
• app/composables/ — All composables are auto-imported by Nuxt (no import statements needed).
• app/assets/css/nuxt-x-app.css — Base styles loaded via the layer's nuxt.config.
• app/types/index.ts — Exported types for consumers (NavItem, DashboardConfig, etc.).

Data flow: useXCrud reads the API base URL from runtimeConfig.public.x.app.apiUrl, prepends it to endpoint paths, and uses $fetch with credentials for all requests. Auth tokens are injected via useXFetch, which calls useNuxtApp().$auth?.getToken() if available.

Configuration merging: The consuming app's app.config.ts deeply merges with the layer's defaults, so xDashboard settings can be partially overridden without replacing the entire config.

Layer Architecture

| File | Role | How to Override | |---|---|---| | nuxt.config.ts | Registers modules, sets runtime defaults, loads CSS | Extend in your nuxt.config.ts — Nuxt deep-merges layer configs | | app.config.ts | Not present — defaults are in components | Create app.config.ts with xDashboard key | | app/components/ | Auto-imported components (XA prefix) | Override by placing a same-named component in your app/components/ | | app/composables/ | Auto-imported composables | Override by placing a same-named composable in your app/composables/ |

This layer has no dependencies on other xlayers. It is the base layer that other xlayers (like nuxt-x-app-admin) extend.

Development

# Install dependencies
pnpm install

# Prepare types
pnpm run dev:prepare

# Run playground
pnpm run dev

# Run tests
pnpm run test:run

# Run tests with coverage
pnpm run test:coverage

# Build playground
pnpm run build

Changelog

1.1.1

• Fixed useXFetch GET path dropping auth/default headers — in the useFetch branch, raw caller-supplied headers were spread after the merged headers, silently discarding the Authorization header and JSON defaults whenever a caller passed any header. Caller headers are now merged into the defaults in both the useFetch (GET) and $fetch paths.
• Added xApp.defaultHeaders app config — optional per-request header factory (typed via AppConfigInput) so apps can inject global headers (e.g. x-tenant-id) into every useXFetch call. Guarded: ignored when absent or when the factory throws.

License

MIT