Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Plugins are the entry point for extending the Nuxe runtime. Every file inside app/plugins/ is executed once before the root Vue component mounts, giving you access to the Vue app instance, the router, runtime config, and a lifecycle hook system. Common use cases include registering global Vue components, installing third-party libraries, and attaching route-level analytics.

​
File naming conventions

Nuxe scans app/plugins/ and registers each file automatically. The suffix in the file name controls the execution environment:
File nameRuns on
hello.tsServer and client
client-only.client.tsClient only
server-only.server.tsServer only
Files whose names start with _ are ignored by the scanner — use this for private helpers shared between plugins.

​
defineNuxePlugin

Wrap every plugin export in defineNuxePlugin. It accepts either a plain setup function or an object with a setup function and optional configuration flags. 
// Function form — most common
export default defineNuxePlugin((nuxeApp) => {
  // setup logic runs synchronously or returns a Promise
})

// Object form — enables the parallel option
export default defineNuxePlugin({
  parallel: true,
  setup(nuxeApp) {
    // independent setup that does not need to block other plugins
  },
})
Plugins marked parallel: true are started concurrently alongside other parallel plugins instead of being awaited in sequence. Use this for setup tasks that are fully independent — for example, pre-fetching config from two different endpoints at the same time.

​
The NuxeApp object

The single argument passed to your plugin’s setup function is a NuxeApp instance with the following properties:
​
vueApp
App
The underlying Vue 3 application instance. Use this to call vueApp.component(), vueApp.directive(), or vueApp.use() to register Vue-level extensions.
​
router
Router
The Vue Router instance. Useful for registering global navigation guards or accessing the current route outside of a component.
​
ssrContext
Record<string, unknown> | undefined
The server-side rendering context object. Only present during SSR; undefined on the client. Use it to access request-scoped data passed from the server entry.
​
config
RuntimeConfig
The runtime configuration object. config.public contains values accessible on both the server and the client; private keys are server-only.
​
state
NuxeState
Shared reactive state passed from SSR to the client hydration payload. Use useState to read and write individual keys.
​
payload
{ state: NuxeState }
The full SSR payload object that is serialised into the initial HTML and rehydrated on the client. payload.state is a reference to the same object as state.
​
hook(name, fn)
function
Register a listener for a lifecycle hook. The listener is called every time the named event fires.
​
callHook(name, ...args)
function
Programmatically fire a lifecycle hook. Returns a Promise that resolves after all registered listeners complete.

​
Available lifecycle hooks

Hook nameWhen it fires
app:createdImmediately after the Nuxe app object is constructed, before any plugins run
app:mountedAfter the Vue app has mounted in the browser
page:startBefore a page navigation begins
page:finishAfter a page navigation completes

​
Real-world plugin examples

// app/plugins/hello.ts
export default defineNuxePlugin((nuxeApp) => {
  console.log('[plugin:hello] app:created', nuxeApp.config.public.apiBase)

  nuxeApp.hook('app:mounted', () => {
    console.log('[plugin:hello] app:mounted')
  })
})

​
useNuxeApp()

Inside a Vue component’s setup function or inside another plugin, call useNuxeApp() to access the NuxeApp instance without it being passed as an argument: 
import { useNuxeApp } from '@dvlkit/nuxe'

const nuxeApp = useNuxeApp()
nuxeApp.hook('page:start', () => {
  console.log('navigation started')
})
useNuxeApp() throws if called outside a Nuxe plugin or a Vue component setup context. For top-level module code, receive nuxeApp as the plugin argument instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us