@jsg-developer/vue-pack

@jsg-developer/vue-pack

📖 Overview

@jsg-developer/vue-pack is a modern, high-performance Vue 3 component library built for developer velocity, strict type safety, and modularity. It solves the boilerplate of administrative dashboards, CRUD systems, and complex enterprise data workflows by providing:

1. Schema-Driven Form Engine (FormModal): Automatically generates multi-layout reactive forms with deep nested objects, arrays, file uploaders, rich-text editors, and maps from declarative schemas.
2. Enterprise Datatable (TabelData): Server-side and client-side data presentation, search filtering, multi-column sorting, pagination, dynamic column types, and full CRUD orchestration.
3. Deep Zod Schema Validation: Full inference and runtime validation with Zod v4 and v3 across forms, datatable actions, and storage caches.
4. Offline-First Storage (indexedDB): Dynamic object store creation, reactive queries, migration-free schema handling, and Zod cache validation.
5. Zero-Pollution Subpath Exports: Granular subpaths allowing aggressive tree-shaking—use only the storage module or fetch client without pulling UI code.
6. SSR & Isomorphic Security: Safe HTML sanitization powered by DOMPurify with Node.js fallback, and isolated browser-dependent modules (Leaflet & Quill) for seamless Nuxt 3 integration.

✨ Key Features

📦 Installation

Install @jsg-developer/vue-pack alongside its peer dependencies:

# npm
npm install @jsg-developer/vue-pack vue@^3.5.0 zod@^4.0.0 leaflet@^1.9.4

# pnpm
pnpm add @jsg-developer/vue-pack vue@^3.5.0 zod@^4.0.0 leaflet@^1.9.4

# yarn
yarn add @jsg-developer/vue-pack vue@^3.5.0 zod@^4.0.0 leaflet@^1.9.4

# bun
bun add @jsg-developer/vue-pack vue@^3.5.0 zod@^4.0.0 leaflet@^1.9.4

Peer Dependencies Note:

• vue (>= 3.5.0) is required for generic component inference and reactive primitives.
• zod (>= 3.23.0 || >= 4.0.0) powers schema validation across forms and table CRUD operations.
• leaflet (>= 1.9.4) is required if utilizing the LocationPicker GIS map component.

🗂️ Subpath Architecture

This library is distributed with strict subpath exports. Import only what your feature requires:

@jsg-developer/vue-pack
├── .                 # Umbrella bundle (components, configs, utilities, fetch)
├── /vue              # Vue 3 Plugin (Global registration & options injection)
├── /init             # Headless initializer for IndexedDB and i18n
├── /indexedDB        # Offline-first IndexedDB manager with Zod cache validation
├── /secureFetch      # Authenticated HTTP Client & SecureFetchError
├── /config           # Type-safe configuration helper (defineConfig)
├── /components       # All Vue components (FormModal, TabelData, Inputs, Display, Feedback)
├── /type             # Pure TypeScript interfaces, schema types, and contracts
└── /style.css        # Bundled and prefixed UnoCSS stylesheet

🚀 Quick Start

Option A: Global Plugin Registration (Best for SPAs)

Register all components globally and configure client-side storage and i18n in your entry file (main.ts):

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'

// 1. Import library stylesheet
import '@jsg-developer/vue-pack/style.css'

// 2. Import Vue plugin and configuration helper
import JsgdVuePack from '@jsg-developer/vue-pack/vue'
import { defineConfig } from '@jsg-developer/vue-pack/config'

const app = createApp(App)

// 3. Register with global options
app.use(
  JsgdVuePack,
  defineConfig({
    indexedDB: {
      dbName: 'EnterpriseERP_DB',
      dbVersion: 1,
      storeSingle: ['session_data', 'app_settings'],
      storeArray: ['products', 'orders', 'customers'],
    },
    i18n: {
      // Language overrides or custom dictionary registration
    },
  }),
)

app.mount('#app')

Option B: Modular Subpath Imports (Best for Tree-Shaking & Nuxt)

Import individual components or utilities directly in your Single File Components without registering the global plugin:

<template>
  <div class="p-6">
    <TabelData :base="tableConfig" :validation="tableValidation" @refreshData="fetchData" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { z } from 'zod'
import '@jsg-developer/vue-pack/style.css'
import { TabelData } from '@jsg-developer/vue-pack/components'
import type { BaseConfig, TabelValidationSchema } from '@jsg-developer/vue-pack/type'

// 1. Zod Schema
const productSchema = z.object({
  id: z.number().optional(),
  name: z.string().min(3, 'Product name must have at least 3 characters'),
  price: z.number().positive('Price must be greater than zero'),
})

type Product = z.infer<typeof productSchema>

// 2. Table Configuration
const tableConfig = ref<BaseConfig<Product>>({
  source: {
    DB_NAME: 'products',
  },
  schema: {
    global: {
      name: { type: 'text', label: 'Product Name', required: true },
      price: { type: 'currency', label: 'Price (IDR)', required: true },
    },
  },
  headersTabelDisplay: ['name', 'price'],
  dataTabelDisplay: {
    name: { type: 'text', valueKey: 'name' },
    price: { type: 'currency', valueKey: 'price' },
  },
})

// 3. Zod CRUD Validation Mapping
const tableValidation: TabelValidationSchema<Product> = {
  create: productSchema,
  update: productSchema,
  delete: z.object({ id: z.number() }),
}

const fetchData = () => {
  console.log('Refreshed data')
}
</script>

📚 Complete Subpath API Reference

1. Subpath: @jsg-developer/vue-pack/components

Exports all UI components, categorized into Form, Datatable, Display, Feedback, and Inputs.

A. FormModal (Schema-Driven Form Generator Modal)

A comprehensive dialog component that generates dynamic, multi-column forms based on schema definitions with built-in validation, SEO scoring, and nested data management.

Props (FormModalProps<T>)

Emits

Example Schema Definition:

import type { Schema } from '@jsg-developer/vue-pack/type'

export const userFormSchema: Schema = {
  fullName: {
    type: 'text',
    label: 'Full Name',
    required: true,
    validate: { minLength: 3, maxLength: 50 },
  },
  email: {
    type: 'email',
    label: 'Email Address',
    required: true,
  },
  role: {
    type: 'select',
    label: 'User Role',
    options: ['admin', 'editor', 'viewer'],
    optionsView: ['Administrator', 'Editor', 'Viewer'],
    required: true,
  },
  bio: {
    type: 'quillEditor',
    label: 'Biography',
    placeholder: 'Write user biography...',
  },
}

B. TabelData (Enterprise Datatable)

A powerful datatable engine handling local IndexedDB or remote REST API data, automatic pagination, search queries, multi-format cell renderers, and built-in modal CRUD.

Props (TabelDataProperty<Item>)

Emits

C. SafeHtml (SSR-Safe HTML Renderer)

Renders sanitized HTML safely across both client and server environments.

Props

Example:

<template>
  <SafeHtml :html="articleContent" as="article" />
</template>

<script setup lang="ts">
import { SafeHtml } from '@jsg-developer/vue-pack/components'

const articleContent = '<p>Hello <b>World</b><script>alert("XSS")</script></p>'
</script>

D. Specialized Input Collection

All inputs emit standard Vue 3 v-model (update:modelValue) events and validation errors (push:error, remove:error):

2. Subpath: @jsg-developer/vue-pack/indexedDB

An offline-first, dynamic IndexedDB manager that automatically creates and upgrades object stores on-demand without manual database migration steps.

import {
  saveToIndexedDB,
  getFromIndexedDB,
  getSingleFromIndexedDB,
  getItemById,
  updateItemInStore,
  deleteItemFromStore,
  removeFromIndexedDB,
  clearStore,
  configureIndexedDB,
  isIndexedDBSupported,
} from '@jsg-developer/vue-pack/indexedDB'

Functions Specification

saveToIndexedDB(data: Record<string, any>): Promise<void>

Batch saves or updates records into specified stores. Single stores store values under the 'current' key; array stores are batch updated.

getFromIndexedDB<T = any>(storeName: string, schema?: ZodType<T>): Promise<T[]>

Retrieves all records from an array object store. If a Zod schema is provided, every item is validated against it—corrupted or obsolete records are automatically filtered out.

import { z } from 'zod'
import { getFromIndexedDB } from '@jsg-developer/vue-pack/indexedDB'

const userCacheSchema = z.object({
  id: z.number(),
  username: z.string(),
  lastLogin: z.string(),
})

type UserCache = z.infer<typeof userCacheSchema>

// Guaranteed type-safe T[] matching the Zod schema
const users = await getFromIndexedDB<UserCache>('users', userCacheSchema)

getSingleFromIndexedDB<T = any>(storeName: string, key = 'current', schema?: ZodType<T>): Promise<T | undefined>

Retrieves a single configuration or session record by key.

getItemById<T = any>(storeName: string, id: string | number, schema?: ZodType<T>): Promise<T | undefined>

Finds a specific entity by its primary key from an array store.

updateItemInStore<T = any>(storeName: string, item: T): Promise<void>

Puts/updates an individual item into an array store.

deleteItemFromStore(storeName: string, id: string | number): Promise<void>

Deletes a single item by ID from an array store.

removeFromIndexedDB(data: Record<string, number[] | number>): Promise<void>

Batch deletes items from multiple stores in a single transaction.

clearStore(storeName: string): Promise<void>

Clears all records inside the given object store.

isIndexedDBSupported(): boolean

Returns true if executed in a browser environment with indexedDB available; false in SSR / Node.js.

3. Subpath: @jsg-developer/vue-pack/secureFetch

A lightweight, authenticated fetch client equipped with automatic credentials handling, header injections, and rich error propagation.

import { secureFetch, secureFetchJson, SecureFetchError } from '@jsg-developer/vue-pack/secureFetch'

secureFetch(input: RequestInfo | URL, options?: SecureFetchOptions): Promise<Response>

Parameters (SecureFetchOptions)

Returns

Standard Fetch Promise<Response>. Rejects with SecureFetchError if response status is not 2xx.

secureFetchJson<T = any>(input: RequestInfo | URL, options?: SecureFetchOptions): Promise<T>

Convenience wrapper that executes secureFetch and automatically awaits .json() parsed into type T.

SecureFetchError

class SecureFetchError extends Error {
  status: number
  response?: Response
  errorBody?: any
}

Example:

import { secureFetchJson, SecureFetchError } from '@jsg-developer/vue-pack/secureFetch'

interface UserProfile {
  id: string
  name: string
  email: string
}

try {
  const profile = await secureFetchJson<UserProfile>('/api/v1/profile', {
    authType: 'bearer',
    token: 'jwt.token.here',
  })
  console.log(profile.name)
} catch (error) {
  if (error instanceof SecureFetchError) {
    console.error(`HTTP ${error.status}: ${error.message}`, error.errorBody)
  }
}

4. Subpath: @jsg-developer/vue-pack/config

Provides a type-safe configuration helper for application-level library defaults.

import { defineConfig } from '@jsg-developer/vue-pack/config'

export default defineConfig({
  indexedDB: {
    dbName: 'FinanceAppDB',
    dbVersion: 1,
    storeSingle: ['preferences'],
    storeArray: ['transactions', 'ledgers'],
  },
  i18n: {
    languages: [
      {
        lang: 'id',
        config: {
          searchPlaceholder: 'Telusuri transaksi...',
        },
      },
    ],
  },
})

5. Subpath: @jsg-developer/vue-pack/init

Headless initialization engine. Useful for workers, background tasks, or scripts where Vue components are not mounted but IndexedDB or i18n dictionaries need configuration.

import initialize from '@jsg-developer/vue-pack/init'

initialize({
  indexedDB: {
    dbName: 'BackgroundWorkerDB',
    storeArray: ['sync_queue'],
  },
})

6. Subpath: @jsg-developer/vue-pack/type

Exports all TypeScript contracts, schemas, props, and interface definitions.

import type {
  Schema,
  Field,
  BaseConfig,
  TabelDataProperty,
  TabelValidationSchema,
  FormModalProps,
  SupportedLanguage,
  SecureFetchOptions,
  IndexedDBConfig,
} from '@jsg-developer/vue-pack/type'

🛡️ Zod Validation & Schema Integration

Validation in @jsg-developer/vue-pack natively supports Zod schemas (z.ZodType<T>).

1. Standalone Validation Helpers

The library exports runtime validation utilities from @jsg-developer/vue-pack:

import { z } from 'zod'
import { validate, safeValidate } from '@jsg-developer/vue-pack'

const invoiceSchema = z.object({
  invoiceNumber: z.string().min(5),
  amount: z.number().positive(),
  dueDate: z.string(),
})

// 1. Throwing validator (returns inferred type)
const invoice = validate(invoiceSchema, rawData)

// 2. Safe validator (does not throw)
const result = safeValidate(invoiceSchema, rawData)
if (result.success) {
  console.log(result.data.amount)
} else {
  console.error(result.error.message, result.error.issues)
}

2. Form & Datatable CRUD Validation Pipeline

Attach your Zod schemas directly to TabelData props to enforce strict type checking across all CRUD actions:

import { z } from 'zod'
import type { TabelValidationSchema } from '@jsg-developer/vue-pack/type'

export const itemSchema = z.object({
  id: z.number().optional(),
  title: z.string().min(4, 'Title must be at least 4 characters'),
  sku: z.string().regex(/^[A-Z0-9-]+$/, 'Invalid SKU format'),
  stock: z.number().int().min(0),
})

export type Item = z.infer<typeof itemSchema>

export const itemValidation: TabelValidationSchema<Item> = {
  create: itemSchema,
  update: itemSchema.partial(),
  delete: z.object({ id: z.number() }),
  deleteMany: z.object({ ids: z.array(z.number()) }),
}

🌐 Nuxt 3 / SSR Compatibility

@jsg-developer/vue-pack is designed with isomorphic architecture in mind. All DOM-dependent features are isolated from Node.js runtime crashes:

1. HTML Sanitization: SafeHtml uses sanitizeHtml() with browser detection and safe SSR string stripping fallback.
2. IndexedDB: All storage calls gracefully resolve or return empty arrays on the server.
3. Quill & Leaflet: Both engines utilize dynamic browser imports inside onMounted.

Nuxt 3 Configuration Recommendation

In your nuxt.config.ts, transpile the library and import the stylesheet:

// nuxt.config.ts
export default defineNuxtConfig({
  css: ['@jsg-developer/vue-pack/style.css'],
  build: {
    transpile: ['@jsg-developer/vue-pack'],
  },
})

When rendering components that interact directly with the DOM or window viewport (such as map pickers or full rich-text editors), wrap them in Nuxt's <ClientOnly> component:

<template>
  <ClientOnly fallback-tag="div" fallback="Loading map editor...">
    <LocationPicker v-model="coordinates" label="Branch Location" />
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { LocationPicker } from '@jsg-developer/vue-pack/components'

const coordinates = ref({ lat: '-7.250445', lng: '112.768845' })
</script>

🎨 Styling & UnoCSS

The library uses UnoCSS with a strict custom prefix: jsgd-.

// Inside your app's main entry:
import '@jsg-developer/vue-pack/style.css'

Why jsgd- Prefix?

• Zero Style Leakage: You can safely use Tailwind CSS, Bootstrap, UnoCSS, or Vuetify in your main app without conflicting utility classes.
• Dark Mode Support: Dark theme styling is triggered by the presence of the dark class on the root <html> element.

🤝 Contributing

Contributions, bug reports, and feature proposals are welcome!

1. Fork the repository on GitHub.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'feat: add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

📄 License

This library is open-source software licensed under the MIT License.

Third-Party Licenses

This project bundles and adapts third-party open-source libraries (Leaflet, Quill, DOMPurify). Complete license attestations are included in THIRD_PARTY_LICENSES.md.