@ramathibodi/nuxt-commons

@ramathibodi/nuxt-commons

Nuxt module for Nuxt 3 and Nuxt 4 that provides shared runtime building blocks for Rama projects:

• globally auto-imported UI components
• auto-imported composables
• runtime plugins for permission/dialog/default behavior
• utility and lab exports

Documentation & playground

The live playground is the project's documentation site — every component has a real demo page running the real module against the real Vuetify theme, with a Vuetify-docs-style API panel (Props / Emits / Slots / Exposed) sourced from docs/ai-summary.json. Bug-repro fixtures live under Scenarios.

→ https://ramacare.gitlab.rama.mahidol.ac.th/frontend/rama-modules/ (published from master by the pages CI job; if the project later moves to a unique Pages domain, update NUXT_APP_BASE_URL in the CI job accordingly)

Run it locally with pnpm run dev. See CLAUDE.md > Playground for the conventions every new/modified component must follow.

Install

# pnpm
pnpm add -D @ramathibodi/nuxt-commons

# yarn
yarn add --dev @ramathibodi/nuxt-commons

# npm
npm install --save-dev @ramathibodi/nuxt-commons

Nuxt Setup

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@ramathibodi/nuxt-commons'],
})

Supported Nuxt versions: ^3.16.0 || ^4.0.0

Plugin Initialization (Required)

After registering the module, apps must create a Nuxt plugin that provides $appGraphql and $appAuthentication. This wires up the module's internal bridge system so that ModelTable, ModelSelect, useGraphQl(), and other model-driven components can resolve GraphQL operations and access authentication state.

// app/plugins/graphql.ts (or any plugin name)
// graphqlOperation, graphqlType, graphqlInputType, scalarType are
// auto-imported from your generated composables/graphqlObject.ts.
// useAuthentication is auto-imported from your app/composables/authentication.ts.

export default defineNuxtPlugin(() => {
  return {
    provide: {
      appAuthentication: () => useAuthentication(),
      appGraphql: {
        scalarType,
        graphqlType,
        graphqlInputType,
        graphqlOperation,
      },
    },
  }
})

$appGraphql — Provides generated GraphQL operation metadata (scalar types, object types, input types, and operations) so useGraphqlBridge() and useGraphqlModelOperation() inside the module can resolve queries/mutations by name.

$appAuthentication — Provides a factory function returning the app's authentication state (token, hasPermission, login, logout, etc.) so the module's useAuthentication() bridge can access auth context for API calls and permission checks.

Prerequisites:

1. Run your GraphQL codegen to generate composables/graphqlObject.ts and types/graphql.ts.
2. Implement useAuthentication() in your app returning at minimum { token, hasPermission, login, logout }.

See playground/plugins/nuxtCommon.ts for a working example.

What The Module Registers

Configured in src/module.ts:

• Components from src/runtime/components (global + prefixed)
• Composables from src/runtime/composables/** (auto-imported)
• Plugins:
  • src/runtime/plugins/permission.ts
  • src/runtime/plugins/dialogManager.ts (client)
  • src/runtime/plugins/clientConfig.ts (client)
  • src/runtime/plugins/default.ts (client)
• Type templates from src/runtime/types/*.d.ts

Runtime Config

This module uses public runtime config at:

runtimeConfig.public['nuxt-commons']

Module options are merged into this key by module setup.

Development

# Install dependencies
npm install

# Prepare stubs/types
npm run dev:prepare

# Run playground
npm run dev

# Build playground
npm run dev:build

# Lint and test
npm run lint
npm run test

Concepts

• Model Components — Endpoint Reference — how modelName translates to GraphQL operations and REST API endpoints, with body/response shapes and the By<Qualifier> rule for model/* components.
• Document Template JSON Spec — schema and conventions for document templates.

Documentation

Generate documentation artifacts from source:

# Vue component API docs (vue-docgen)
npm run docs:api:components

# Composable API docs (typedoc)
npm run docs:api:composables

# Both API docs
npm run docs:api

# AI-focused summary + type index
npm run docs:ai:summary

docs:api:components now runs a post-process step that enriches missing prop/event descriptions and missing type/default cells in generated markdown using docs/ai-summary.json.

Documentation config files:

• docs/vue-docgen.config.cjs for component docs generation
• docs/typedoc.json for composable docs generation
• docs/typedoc.tsconfig.json for docs-only TypeScript scope

Generated outputs:

• docs/components/ (vue-docgen output)
• docs/composables/ (typedoc output)
• docs/ai-summary.md (compact AI-oriented markdown summary)
• docs/ai-summary.json (machine-readable component/composable metadata)
• docs/type-index.json (type index for tooling/AI pipelines)

docs:ai:summary generates:

• docs/ai-summary.md
• docs/ai-summary.json
• docs/type-index.json

Publish Notes

package.json version is used to select the publish line by major.minor:

• Keep the same major.minor line to continue normal releases.
• Change it to 0.2.0, 1.1.0, etc. to start publishing that new line on the next release.

npm run dev:build
npm run release