@ciwergrp/nuxid

Nuxid – Nuxt Essentials

Nuxid bundles a set of productivity helpers for Nuxt projects: lodash auto-imports, Element Plus-friendly validation rules, form and cursor fetch composables, helper utilities, optional icon defaults, Element Plus setup, and Pinia integration. Enable the pieces you need and keep the rest off.

Quick start

Install and register the module:

pnpm add @ciwergrp/nuxid

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@ciwergrp/nuxid'],
  nuxid: {
    // lodash, validator, form, helper, and pinia are enabled by default
  },
})

Features

• Lodash auto-imports (enabled by default): imports from lodash-es with prefix ki (e.g. kiDebounce), skips prefix for names starting with is. Configure with:
  • enabled (default true)
  • prefix (false | string, default 'ki')
  • prefixSkip (string | string[] | false, default 'is')
  • upperAfterPrefix (boolean, default true)
  • exclude (string[])
  • alias (Array<[from, to]>)
• Validator helpers (enabled by default): Element Plus friendly createValidationRules plus ValidationRule and ValidationOptions types. Auto-imported when enabled.
• Form composable (enabled by default): useHttp wraps $fetch, handles processing, errors, response, and builds FormData automatically (or always when alwaysFormData: true). Auto-imported when enabled.
• Helper utilities (enabled by default): array/object/number/string/date helpers with configurable factory (number().abbreviate(), string().normalizeValue()) or prefixed (NumberAbbreviate()) styles, locale lookups, currency defaults, and timezone source configuration (query/cookie/localStorage/static).
• Cursor fetch composable (enabled by default): useCursorFetch wraps $fetch, supports cursor pagination, polling, reactive params, custom fetchers, and configurable cursor/meta keys. Auto-imported when enabled.
• Pinia integration (enabled by default): injects Pinia, auto-imports core helpers (defineStore, storeToRefs, etc.), and auto-imports stores from stores by default.
• Icon defaults (disabled by default): installs @nuxt/icon with default component name KIcon, size 1.25em, base class align-middle inline-block text-current, mode svg. Configure via nuxid.icon.config.
• Element Plus module (disabled by default): installs @element-plus/nuxt with your provided config.

Usage snippets

Lodash example

const result = kiDebounce(() => console.log('hello'), 200)

Validator example

const rules = createValidationRules(
  {
    email: ['required', 'email'],
    password: ['required', 'min:8'],
  },
  formState,
)

Form example

const form = useHttp({ name: '', avatar: null }, { alwaysFormData: false })

await form.post('/api/profile')

if (form.errors) {
  console.error(form.errors)
}

Helper example

const price = number().currency(4200)
const slug = string().slug('Hello World')
const label = string().normalizeValue('')

Cursor fetch example

const { data, loadMore, refresh } = useCursorFetch('/api/messages', {
  fetchOptions: { query: { perPage: 20 } },
  pollInterval: 5000,
  itemKey: 'code',
  cursorParam: 'after',
  meta: {
    cursorKey: 'next_cursor',
    hasMoreKey: 'has_next_page',
  },
})

Pinia example

export const useCartStore = defineStore('cart', {
  state: () => ({ items: [] }),
})

Configuration reference

export default defineNuxtConfig({
  modules: ['@ciwergrp/nuxid'],
  nuxid: {
    icon: {
      enabled: false,
      config: {
        componentName: 'KIcon',
        size: '1.25em',
        class: 'align-middle inline-block text-current',
        mode: 'svg',
        provider: undefined,
        collections: undefined,
        aliases: undefined,
        fallbacks: undefined,
        extend: undefined,
      },
    },
    elementPlus: {
      enabled: false,
      config: {},
    },
    lodash: {
      enabled: true,
      prefix: 'ki',
      prefixSkip: 'is',
      upperAfterPrefix: true,
      exclude: [],
      alias: [],
    },
    validator: {
      enabled: true,
    },
    form: {
      enabled: true,
    },
    helper: {
      enabled: true,
      config: {
        style: 'factory',
        localeSource: 'cookie',
        localeKey: 'lang',
        localeFallback: 'en',
        defaultCurrency: 'USD',
        timezone: {
          source: 'cookie',
          key: 'tz',
          static: 'UTC',
          fallback: 'UTC',
        },
      },
    },
    pinia: {
      enabled: true,
      storesDirs: ['stores'],
    },
    fetcher: {
      enabled: true,
    },
  },
})

Disable any feature by setting it to false (e.g. nuxid: { lodash: false }).

Structure Directory

This module is designed to work best in a Nuxt + pnpm monorepo, where each product or domain is its own Nuxt app under apps/, and shared building blocks live in layers/ as Nuxt layers. The root of the repo acts as the single workspace: dependency versions, lint config, TypeScript config, and tooling live at the top level, while apps and layers are composed via Nuxt’s layer system. This keeps per-domain apps small and focused, encourages reuse without copy/paste, and makes it easy to scale multiple teams or products inside one repo.

Recommended top-level structure:

% ls -l
total 1008
-rw-r--r--@   1 bagusvnt  staff   14838 Jan 12 13:24 AGENTS.md
-rw-r--r--    1 bagusvnt  staff     371 Jan  7 10:45 README.md
drwxr-xr-x    5 bagusvnt  staff     160 Jan  7 11:46 apps
-rw-r--r--@   1 bagusvnt  staff     134 Jan  7 12:26 docker-compose.yml
-rw-r--r--    1 bagusvnt  staff    1103 Jan  7 10:45 eslint.config.mjs
drwxr-xr-x    4 bagusvnt  staff     128 Jan  7 10:45 layers
drwxr-xr-x@ 781 bagusvnt  staff   24992 Jan 15 10:06 node_modules
-rw-r--r--@   1 bagusvnt  staff    1158 Jan 15 10:06 package.json
-rw-r--r--@   1 bagusvnt  staff  474254 Jan 15 10:06 pnpm-lock.yaml
-rw-r--r--    1 bagusvnt  staff      38 Jan  7 10:45 pnpm-workspace.yaml
-rw-r--r--    1 bagusvnt  staff     566 Jan  7 10:45 tsconfig.json

Inside apps/, each app represents a domain or product boundary (for example apps/admin/) and owns its nuxt.config.ts, routing, and app-specific modules. Inside layers/, you keep shared pieces such as UI components, composables, config, and utilities that can be layered into any app. Each layer is also a Nuxt project with its own nuxt.config.ts, so you can expose components, auto-imports, and module options from that layer while keeping a clean separation of concerns.

Examples:

• apps/admin/nuxt.config.ts
• layers/ui/nuxt.config.ts

Development

pnpm install
pnpm run dev:prepare    # generate stubs for module + playground
pnpm run dev            # playground with local module
pnpm run dev:build      # production-like build of playground
pnpm run lint
pnpm run test
pnpm run test:types
pnpm run prepack        # build distributable into dist/

Playground lives in playground/. Module entry is at src/module.ts; runtime code under src/runtime; features under src/features.