@gzl10/nexus-ui

Warning: This project is currently in testing/experimental phase. Use at your own risk.

Vue 3 Admin Panel Framework for nexus-backend. Pre-built components and stores for authentication, users, modules, and storage management.

Repository: https://gitlab.gzl10.com/oss/nexus-backend

Installation

pnpm add @gzl10/nexus-ui

Note: @gzl10/nexus-client and @gzl10/nexus-sdk are bundled dependencies.

Usage

// main.ts
import { bootstrap } from '@gzl10/nexus-ui'
import '@gzl10/nexus-ui/style.css'

const app = await bootstrap({
  apiUrl: '/api/v1',
  base: '/'
})
app.mount('#app')

Custom Routes

const app = await bootstrap({
  apiUrl: '/api/v1',
  routes: [
    { path: '/custom', component: () => import('./pages/CustomPage.vue') }
  ]
})
app.mount('#app')

Features

| Feature | Description | | ------- | ----------- | | Authentication | Login, logout, token refresh, session management | | OTP Challenge | Email verification after failed login attempts | | Password Reset | Email-based password recovery with OTP | | Users Management | CRUD users, roles, permissions | | Modules Explorer | Dynamic module introspection and browsing | | Storage Browser | File upload, download, preview | | Theme System | Light/dark mode with Naive UI | | Internationalization | Built-in i18n support (en, es) | | Real-time | WebSocket integration with socket.io-client | | GDPR Compliance | Consent pages, legal content management |

Exported Components

Display Components

| Component | Description | | --------- | ----------- | | DynamicForm | Auto-generated form from field definitions | | TableDisplay | Data table display with sorting/filtering | | ListDisplay | List display | | MasonryDisplay | Masonry grid display | | DescriptionsDisplay | Key-value descriptions | | ActionDisplay | Action buttons display |

Card Components

| Component | Description | | --------- | ----------- | | ModuleCard | Module display card | | EntityCard | Entity display card | | PluginCard | Plugin display card |

Common Components

| Component | Description | | --------- | ----------- | | AppShell | Root app shell with sidebar/header | | AppHeader | Header with logo, theme toggle, user menu | | AppSidebar | Collapsible sidebar navigation | | AppFooter | Footer with links | | CookieConsent | GDPR cookie consent banner | | AuthCardHeader | Auth page card header with logo | | LegalPageLayout | Layout for legal pages (terms, privacy) |

Input Components (Dual-Mode)

All input components support two presentation modes:

• mode="control" - Editable input for forms (default)
• mode="display" - Read-only rendering for tables/lists

| Component | Type | Description | | --------- | ---- | ----------- | | TextInput | text/email/password | Text input with password toggle | | NumberInput | number | Numeric input | | TextareaInput | textarea | Multi-line text | | MarkdownInput | markdown | Markdown editor (MdEditor) | | SelectInput | select | Single select dropdown | | MultiselectInput | multiselect | Multiple select dropdown | | CheckboxInput | checkbox | Boolean toggle (icon in display) | | DateInput | date | Date picker | | DatetimeInput | datetime | Date and time picker | | TagsInput | tags | Dynamic tags input | | IconInput | icon | Icon picker with preview | | FileInput | file/fileArray | File upload | | ImageInput | image/imageArray | Image upload with thumbnails |

Exported Layouts

| Layout | Description | | ------ | ----------- | | AdminLayout | Main admin layout with sidebar and header | | AuthLayout | Layout for auth pages (login, register) | | PublicLayout | Layout for public pages (landing, legal) | | SettingsLayout | Layout for settings/profile pages | | ErrorLayout | Layout for error pages (403, 404) |

Exported Pages

Auth Pages

| Page | Description | | ---- | ----------- | | LoginPage | Login form with OTP challenge support | | RegisterPage | User registration with OTP verification | | ForgotPasswordPage | Password reset flow (email → OTP → new password) | | ChangePasswordPage | Password change form |

Legal Pages

| Page | Description | | ---- | ----------- | | ConsentPage | GDPR consent collection | | TermsOfServicePage | Terms of service display | | PrivacyPolicyPage | Privacy policy display | | CookiePolicyPage | Cookie policy display |

System Pages

| Page | Description | | ---- | ----------- | | LandingPage | Public landing page | | DashboardPage | Admin dashboard | | ForbiddenPage | 403 Forbidden page | | SystemPage | System modules overview | | ModulePage | Module CRUD management | | EntityEditPage | Entity create/edit page |

Exported Stores (Pinia)

| Store | Description | | ----- | ----------- | | useAuthStore | Authentication state, login/logout, abilities | | useNotificationsStore | Notifications state and actions | | useSocketStore | WebSocket connection, auto-connects with auth |

Exported Composables

| Composable | Description | | ---------- | ----------- | | useTheme | Theme toggle (dark/light), currentLogo | | useFormData | Form data initialization by field type | | buildFieldRules | Form validation rules builder | | isFileType, isArrayFileType | File type detection helpers | | useSelectOptions | Load select options from API/static | | useLocalized | Resolve LocalizedString values | | useLocalizedInput | Multi-language input editing (TextInput, MarkdownInput) | | useApiError | Parse API errors to user messages | | useDisplayFormat | Format values for display components | | useLegalContent | Load legal content from compliance API | | useSidebar | Sidebar collapsed state, modules loading | | useModuleData | Module entity data, sorting, filtering, CRUD | | useOtpFlow | OTP challenge state and handlers |

Exported Configuration

| Export | Description | | ------ | ----------- | | colors, brand, neutrals | Color palette | | lightThemeOverrides, darkThemeOverrides | Naive UI theme overrides | | entityTypeConfigs, getEntityTypeConfig | Entity type icons/colors | | moduleTypeConfigs, getModuleTypeConfig | Module type icons/colors | | displayComponents, getDisplayComponent | Display mode to component mapping |

Exported Utilities

| Export | Description | | ------ | ----------- | | formatBytes, formatDuration | Formatting helpers | | getSingularLabel | Pluralization helper | | isFieldVisible, filterSubmitData | Form field visibility | | getEntityRoutePrefix, getEntityKey | Module routing helpers | | createConfirmPasswordRule | Password confirmation validation | | handleOtpChallenge | OTP error detection |

Re-exported from @gzl10/nexus-client

| Export | Description | | ------ | ----------- | | configureClient | Configure singleton client | | getClient | Get configured client instance | | resetClient | Reset client (logout/testing) | | createNexusClient | Factory for multiple instances | | createAbility | CASL ability factory | | getDeviceId, getDeviceName | Device fingerprinting | | LoginOptions, RegisterInput | Auth input types | | RoleWithPermissions, RolePermission | Role types | | NexusSocket, NexusSocketEvents | Socket.IO types |

Re-exported from @gzl10/nexus-sdk

| Export | Description | | ------ | ----------- | | ModuleDTO, EntityDefinitionDTO | Module/entity types | | FieldDefinitionDTO | Field definition type | | EntityType, Category | Enum types | | LocalizedString, PaginatedResult | Common types | | resolveLocalized, getCountLabel | Localization helpers | | CATEGORIES, CATEGORY_ORDER | Category constants |

Re-exported Types

| Type | Description | | ---- | ----------- | | User, Role | User/role aliases (from client) | | UserWithRoles | User with roles included | | ApiResponse | Generic API response wrapper |

Internationalization (i18n)

Built-in support for English and Spanish. Uses vue-i18n with auto-detection:

import { useI18n } from 'vue-i18n'

const { t, locale } = useI18n()

// Use translations
t('auth.login')        // "Sign In" / "Iniciar Sesión"
t('auth.otpSent')      // "Verification code sent to your email"
t('validation.emailRequired')

// Switch language
locale.value = 'es'

Available namespaces: auth, validation, common, errors, modules, consent, legal.

Configuration Options (BootstrapOptions)

| Option | Description | Default | | ------ | ----------- | ------- | | apiUrl | Backend API URL | /api/v1 | | base | Router base path (must match Vite base) | / | | loginPath | Login redirect path | /login | | routes | Additional user routes | [] | | stores | Additional Pinia stores | [] | | components | Global components to register | {} | | el | Root element selector | #app | | onMounted | Callback after mounting | - | | disableBaseRoutes | Disable built-in routes | false |

Peer Dependencies

{
  "vue": "^3.5.0",
  "vue-router": "^4.6.0",
  "pinia": "^3.0.0",
  "naive-ui": "^2.43.0",
  "@iconify/vue": "^5.0.0",
  "vue-i18n": "^11.0.0"
}

Development

pnpm dev           # Start dev server
pnpm build         # Build app + library
pnpm build:lib     # Build library only
pnpm typecheck     # Type check
pnpm lint          # Linting
pnpm test          # Run tests

Stack

• Vue 3 - Composition API + <script setup>
• Naive UI - Component library
• Pinia - State management
• Vue Router - Routing
• Iconify - Icons
• Vite - Build tool
• Vitest - Testing

License

MIT