Runtime Plugins

Runtime plugins allow you to hook into the Kimesh application lifecycle. They run when the app initializes and can access the Vue app instance, router, and query client.

Defining a Plugin

// src/plugins/analytics.ts
export default defineKimeshRuntimePlugin({
  name: 'analytics',

  setup({ app, router, queryClient }) {
    // Track page views
    router.afterEach((to) => {
      trackPageView(to.fullPath)
    })
  },
})

defineKimeshRuntimePlugin is auto-imported — no import statement needed.

Plugin Hooks

export default defineKimeshRuntimePlugin({
  name: 'my-plugin',

  // Called when the app is being created
  setup({ app, router, queryClient }) {
    // Register Vue plugins
    app.use(myVuePlugin)

    // Add global properties
    app.config.globalProperties.$myHelper = myHelper

    // Provide/inject
    app.provide('myService', createService())
  },

  // Navigation hooks
  hooks: {
    // Before each navigation
    'navigation:before'(context) {
      console.log('Navigating to:', context.to.path)
    },

    // After navigation completes
    'navigation:after'(context) {
      console.log('Navigated to:', context.to.path)
    },

    // On navigation error
    'navigation:error'(context) {
      console.error('Navigation error:', context.error)
    },
  },
})

Plugin Directory

Plugins in src/plugins/ are auto-discovered and loaded in order:

src/plugins/
├── 01.analytics.ts      # Runs first
├── 02.error-handler.ts  # Runs second
└── 03.theme.ts          # Runs third

Numeric prefixes control execution order.

Setup Context

The setup function receives:

interface KimeshAppContext {
  app: App                    // Vue app instance
  router: Router              // Vue Router instance
  queryClient: QueryClient    // TanStack Query client
}

Examples

Error Handling Plugin

export default defineKimeshRuntimePlugin({
  name: 'error-handler',

  setup({ app }) {
    app.config.errorHandler = (err, instance, info) => {
      console.error('Vue error:', err)
      reportError(err)
    }
  },
})

Authentication Plugin

export default defineKimeshRuntimePlugin({
  name: 'auth',

  setup({ app, router }) {
    const auth = createAuthService()
    app.provide('auth', auth)

    // Global navigation guard
    router.beforeEach(async (to) => {
      if (to.meta.requiresAuth && !auth.isAuthenticated()) {
        return { path: '/login', query: { redirect: to.fullPath } }
      }
    })
  },
})

I18n Plugin

export default defineKimeshRuntimePlugin({
  name: 'i18n',

  setup({ app }) {
    const i18n = createI18n({
      locale: 'en',
      messages: { en, vi },
    })
    app.use(i18n)
  },
})

Plugin Meta

Access plugin metadata:

import { getPluginName, getPluginMeta } from 'kimesh'

const plugin = defineKimeshRuntimePlugin({
  name: 'my-plugin',
  meta: { version: '1.0.0' },
  setup() {},
})

getPluginName(plugin)  // 'my-plugin'
getPluginMeta(plugin)  // { version: '1.0.0' }