nuxt-ui-mongocamp

A Nuxt module that wraps @sfxcode/nuxt-mongocamp-server with ready-made UI components, composables, and a runtime plugin. Add the module to your Nuxt app and get MongoCamp authentication, user/role management, and collection access out of the box — built on Nuxt UI and FormKit.

• ✨ Release Notes

Features

• Auth middleware — global route guard that protects /secured/** (login required) and /admin/** (admin role required)
• Ready-made components — login form, user/role management tables, collection browser with stats and paginated data table, server version badge
• FormKit-powered forms — schema-driven forms via @sfxcode/nuxt-ui-formkit with nuxtUIInput, nuxtUISwitch, nuxtUIListbox, and nuxtUISelectMenu inputs
• Composables — useMongocampAdmin, useMongocampCollection, useMongocampDocument, useMongocampSchema auto-imported into your app
• Zero extra config — peer modules (@nuxt/ui, @formkit/nuxt, unocss-nuxt-ui) are declared as moduleDependencies and configured automatically

Module Dependencies

These modules are declared as moduleDependencies and are automatically set up — you do not need to add them manually to your nuxt.config.ts:

| Module | Purpose | |---|---| | @nuxt/ui | Component library (UTable, UModal, UBadge, UPageCard, …) | | unocss-nuxt-ui | UnoCSS preset that matches Nuxt UI's design tokens | | @formkit/nuxt | FormKit core integration for Nuxt | | @sfxcode/nuxt-ui-formkit | Nuxt UI input types for FormKit (nuxtUIInput, nuxtUISwitch, nuxtUIListbox, nuxtUISelectMenu) | | @sfxcode/nuxt-mongocamp-server | MongoCamp REST API client, auth state, and useMongocampApi() / useMongocampAuth() composables |

Quick Setup

npm install @sfxcode/nuxt-ui-mongocamp

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@sfxcode/nuxt-ui-mongocamp'],

  mongocamp: {
    url: process.env.MONGOCAMP_URL,
  },
})

The mongocamp key is forwarded to @sfxcode/nuxt-mongocamp-server. Set MONGOCAMP_URL (and optionally MONGOCAMP_ADMIN_USER / MONGOCAMP_ADMIN_PASSWORD) in your .env file.

Components

All components are auto-imported.

<MongocampLogin />

FormKit schema-driven login form. Persists the last user ID in a cookie (mongocamp_login) and redirects to /secured on success.

<template>
  <MongocampLogin />
</template>

<MongocampUsers />

Full CRUD table for managing users — create, edit (roles via transfer listbox, password change), and delete, all via modal dialogs. Includes a server-side debounced search input and sortable column headers.

<template>
  <MongocampUsers />
</template>

<MongocampRoles />

Full CRUD table for managing roles — create, edit (admin flag, collection grants), and delete. Includes a server-side debounced search input and sortable column headers.

<template>
  <MongocampRoles />
</template>

<MongocampRoleGrants />

Per-role collection grant management — lists grants for a named role, with add/edit/delete. Filters the collection picker to exclude already-granted collections.

<template>
  <MongocampRoleGrants role-name="myRole" />
</template>

<MongocampCollections />

Table of all collections with document count, storage size, and index count. Each row links to the collection info and data pages. Includes a client-side filter input and sortable column headers.

| Prop | Type | Default | Description | |---|---|---|---| | infoPath | string | /secured/admin/collections | Base path for the info page link | | dataPath | string | /secured/admin/collections | Base path for the data page link (<dataPath>/<name>/data) |

<template>
  <MongocampCollections />
</template>

<MongocampCollectionInfos />

Stat-card grid for a single collection — document count, data size, storage size, avg doc size, index count, total index size, and a per-index size table.

<template>
  <MongocampCollectionInfos collection-name="myCollection" />
</template>

<MongocampCollectionData />

Schema-driven paginated data table for a collection.

• Columns derived from the collection's JSON schema; falls back to first-row key derivation when no schema properties exist. Column order: _id first, metaData last, all others sorted A–Z.
• Sorting — clickable column headers trigger server-side sort via the MongoCamp API (field / -field).
• Filtering — debounced search input sends a Lucene query (col1: *term* OR col2: *term*) across all string-typed columns to the API; disabled until the schema is loaded.
• Cell rendering:
  • date-time columns and MongoDB $date extended JSON → locale-formatted date string
  • MongoDB $oid → monospaced ID string
  • metaData objects (with created/updated fields) → structured created / updated / by rows
  • All other objects and arrays → icon button ({} / list); click opens a modal with pretty-printed JSON in a <pre> tag
• Includes a reload button and paginated footer.

<template>
  <MongocampCollectionData collection-name="myCollection" />
</template>

<MongocampVersion />

Displays the connected MongoCamp server name and version as a UBadge. Shows a neutral "unavailable" badge when the server cannot be reached.

<template>
  <MongocampVersion />
</template>

Composables

All composables are auto-imported.

useMongocampAdmin()

Wraps the adminApi and collectionApi for user and role management.

const {
  listUsers,          // (filter?: string) => Promise<UserProfile[]>
  addUser,            // (userId, password, apiKey?, roles?) => Promise<UserProfile>
  deleteUser,         // (userId) => Promise<void>
  updateUserRoles,    // (userId, roles) => Promise<UserProfile>
  updateUserPassword, // (userId, password) => Promise<void>
  listRoles,          // (filter?: string) => Promise<Role[]>
  addRole,            // (name, isAdmin?, collectionGrants?) => Promise<Role>
  updateRole,         // (roleName, isAdmin, collectionGrants?) => Promise<Role>
  deleteRole,         // (roleName) => Promise<void>
  listCollections,    // () => Promise<string[]>
} = useMongocampAdmin()

useMongocampCollection()

Reactive state for paginated collection queries.

const {
  filter,     // Ref<string | undefined>       — MongoDB filter expression
  sort,       // Ref<string[] | undefined>      — sort fields
  projection, // Ref<string[] | undefined>      — field projection
  pagination, // Ref<{ pageIndex: number, pageSize: number }>
  total,      // Ref<number>                    — total document count
} = useMongocampCollection()

useMongocampDocument()

Helpers for document-level operations.

const {
  ensureMetaData,   // <T>(data: T) => T  — stamps createdBy/updatedBy/timestamps from logged-in user
  updateFromPartial, // <T>(obj: T, updates: Partial<T>) => T
} = useMongocampDocument()

useMongocampSchema()

Converts a JsonSchemaDefinition to typed table column definitions. Used internally by MongocampCollectionData.

const { schemaToColumnDefinition } = useMongocampSchema()

// schemaToColumnDefinition(definition, fields) => ColumnDefinition[]
// ColumnDefinition: { columnName, columnKey, columnType }
// columnType: 'string' | 'number' | 'date-time'

Fields are sorted with _id first, metaData last, and all other fields alphabetically.

Route Protection

Route protection is opt-in and config-driven via useMongocampRoles(). Set useGlobalAuthMiddleware: true and list your protected route globs under nuxtUiMongocamp — nothing is protected by default. See Route Protection for the full behavior.

| Path pattern | Requirement | |---|---| | Matches securedRouteParts | User must be logged in | | Matches managementRouteParts | User must be a manager (managerRoles, or admin) | | Matches adminRouteParts | User must be an admin | | /logout | Calls logout() |

On any unmet requirement, the middleware redirects to notAllowedPath (default '/'); /logout redirects to the separate logoutRedirectPath instead (also default '/'). Both are always themselves allowed, so neither can ever cause a redirect loop.

Runtime Plugin

The plugin provides $mongocampVersion (a Ref to the server's version info) via useNuxtApp():

const { $mongocampVersion } = useNuxtApp()
// $mongocampVersion.value?.name
// $mongocampVersion.value?.version

Configuration

The module's own config key is nuxtUiMongocamp — it configures the route middleware described above:

nuxtUiMongocamp: {
  useGlobalAuthMiddleware: true,                // default: false
  notAllowedPath: '/login',                     // default: '/'
  logoutRedirectPath: '/',                       // default: '/'
  managerRoles: ['support'],                    // default: []
  securedRouteParts: ['/secured/**'],           // default: []
  managementRouteParts: ['/secured/manage/**'], // default: []
  adminRouteParts: ['/secured/admin/**'],       // default: []
  useServerProxy: false,                        // default: false — see Server Proxy Auth below
  serverProxyPath: '/api/_mongocamp',           // default shown
}

See Configuration for details on each option, and Server Proxy Auth for the api-key-only, no-login mode useServerProxy enables.

The MongoCamp server is configured separately, under the mongocamp key (provided by @sfxcode/nuxt-mongocamp-server):

mongocamp: {
  url: 'https://your-mongocamp-server',
  apiKey: process.env.MONGOCAMP_API_KEY, // optional, server-side only — required for server proxy auth mode
  paginationSize: 500,   // default: 500
  refreshToken: true,    // default: true
  tokenRefreshInterval: 5000, // ms, default: 5000
}

Contribution

# Install dependencies
pnpm install

# Build stubs + prepare the playground (run once after clone)
pnpm run dev:prepare

# Start playground dev server
pnpm run dev

# Lint
pnpm run lint

# Run tests (Vitest + @nuxt/test-utils e2e)
pnpm run test
pnpm run test:watch

# Type-check
pnpm run test:types

# Build for publishing
pnpm run prepack

The playground reads playground/.env for MONGOCAMP_URL, MONGOCAMP_ADMIN_USER, and MONGOCAMP_ADMIN_PASSWORD. Optional vars demo server proxy auth mode: MONGOCAMP_API_KEY, MONGOCAMP_USE_SERVER_PROXY=true, and MONGOCAMP_PROXY_SHARED_SECRET (activates the example guard hook in playground/server/plugins/mongocamp-proxy-guard.ts).

Documentation

Full documentation (guides, components, composables) lives in docs/ and is built with VitePress:

# Start the docs dev server
pnpm run docs:dev

# Build the static site
pnpm run docs:build

# Preview the built site
pnpm run docs:preview

License

MIT