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 |

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.

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

License

MIT