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
- 📊 TanStack Table - Advanced data tables with sorting, filtering, pagination
- 📈 Nuxt Charts - Line, area, bar, donut, bubble, and gantt charts

> FormKit Support: For FormKit integration, use @xenterprises/nuxt-x-formkit layer together with this layer.

Installation

``bash


Install the layer

npm install @xenterprises/nuxt-x-app

Install peer dependencies (if not already installed)

npm install @nuxt/ui @nuxt/content

Optional: For FormKit support

npm install @xenterprises/nuxt-x-formkit
`

Quick Start

$3

Add the layer to your nuxt.config.ts:

`ts
export default defineNuxtConfig({
extends: [
'@xenterprises/nuxt-x-app',
// Optional: Add FormKit layer for form components
// '@xenterprises/nuxt-x-formkit',
],

modules: [
'@nuxt/ui',
'@nuxt/content', // Optional, for docs
],
})
`

$3

Create app.config.ts to configure your dashboard:

`ts
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',
},
],
},
},
},
})
`

$3

Components are auto-imported with the XA prefix:

`vue



`

Components

$3


- 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

$3

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

$3

- XALayoutContentNav - Content navigation tabs
- XALayoutResponsiveNav - Responsive navigation

$3

- XABillingPricingGrid - Interactive pricing tables
- XACardQuota - SaaS usage meters with visual progress
- XAFeedbackActivityFeed - Audit trail/activity feed
- XACardProgress - Progress indicators

$3

- 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
- XAChartProgressCircle - Circular progress indicators
- XAChartStatusTracker - Status bar visualizations
- XAChartCategoryDistribution - Category distribution displays

$3

- XAStateError - Error states with retry
- XAStateLoading - Loading indicators
- XAModal - Dialog overlays
- XASlide - Side panel overlays
- XAModalConfirm - Confirmation dialogs

$3

- XAFormUploadFile - File upload with drag-drop
- XAFormSearchInput - Debounced search input

> Note: For FormKit-integrated form components (XFormModal, XFormSlide, XFormFileUpload), use the @xenterprises/nuxt-x-formkit layer.

$3


- XABtnCopy - Copy to clipboard
- XADataTimeline - Activity timeline
- XAUserCard - User profile card

See all components →

Composables

All composables are auto-imported - no imports needed!

$3

A simplified, explicit CRUD factory with a fluent, chainable API. Uses .all(), .read(id), and .create() methods to clearly define intent.

#### Basic Usage

`ts
// 1. List all items
const { data, loading, refresh } = useXCrud('/api/users').all()

// 2. Read single item
const { data, form, save } = useXCrud('/api/users').read(123)

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

// 4. Async usage
const { data } = await useXCrud('/api/users').read(123)
`

#### Factory Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| .all(filters?) | UseXCrudListReturn | List mode - fetches array of items |
| .read(id) | UseXCrudDetailReturn | Detail mode - fetches single item |
| .create() | UseXCrudDetailReturn | Create mode - empty form, no fetch |

#### Return Properties

List Mode (.all())
`ts
const {
data, // Ref - array of items
total, // Ref - total count
filters, // Ref> - filter state
search, // Ref - search query
sort, // Ref - sort state
loading, // Ref
error, // Ref
refresh, // () => Promise
create, // (payload: Partial) => Promise
update, // (payload: Partial, id?: string) => Promise
remove, // (id?: string) => Promise
} = useXCrud('/api/users').all()
`

Detail Mode (.read() / .create())
`ts
const {
data, // Ref - single item (null for create)
id, // ComputedRef
form, // Ref> - form state (auto-synced with data)
formDirty, // ComputedRef - has form changed?
loading, // Ref
error, // Ref
save, // () => Promise - create or update based on ID
resetForm, // () => void - reset form to original data
refresh, // () => Promise
create, // (payload: Partial) => Promise
update, // (payload: Partial, id?: string) => Promise
remove, // (id?: string) => Promise
} = useXCrud('/api/users').read(123)
`

#### Options

`ts
useXCrud('/api/endpoint', {
idKey: 'id', // ID field name (default: 'id')
showToast: true, // Show toast notifications (default: true)
initialFilters: {}, // Initial filter values
initialSort: { column: 'name', direction: 'asc' },
transform: (data) => data, // Transform response data
headers: {}, // Custom headers
onFetch: (data) => {}, // Callback after fetch
onError: (error) => {}, // Callback on error
onCreated: (item) => {}, // Callback after create
onUpdated: (item) => {}, // Callback after update
onDeleted: () => {}, // Callback after delete
})
`

#### Examples

`vue




`

`vue




`

`vue




`

Full documentation →

$3

`ts
// Inline table editing
const { startEdit, saveEdit, cancelEdit, isEditing } = useXInlineEdit({
onSave: async (rowId, field, value) => {
await crud.update({ [field]: value }, rowId)
}
})

// Table column presets
const { presets } = useXTableColumns()
const columns = [
presets.avatar('name', 'User'),
presets.email('email'),
presets.badge('status', 'Status', { colorMap: { active: 'success' } }),
presets.date('createdAt', 'Created'),
presets.actions(),
]

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

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

See all composables →

TypeScript Support

Import types for better IDE support:

`ts
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

$3

`ts
// Explicit imports work too
import { XATable, XAModal } from '#components'
import { useXCrud, useXFetch } from '#imports'
import type { NavItem } from '@xenterprises/nuxt-x-app/types'

// Note: Composables are auto-imported by Nuxt and don't need explicit imports
`

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:

`bash
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

$3

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

`ts
export default defineAppConfig({
ui: {
colors: {
primary: 'blue',
neutral: 'slate',
},
},
})
`

Development

`bash


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.