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.

Development

# Install dependencies
npm install

# Run playground
npm run dev

# Run tests
npm run test

# Build
npm run build

License

MIT

Contributing

Contributions welcome! Please read our contributing guidelines first.