Package Reference

@dyrected/nuxt is the recommended integration for Nuxt projects. It can do two different jobs:

mount a self-hosted Dyrected backend inside the Nuxt app
act as the Nuxt-side client integration for a remote Dyrected API

That is why this package is usually the right starting point for Nuxt instead of wiring @dyrected/vue and @dyrected/sdk manually.

For self-hosted Nuxt projects, the server-handler sections show how to run Dyrected inside the same Nuxt application runtime.

What the module gives you

The Nuxt module adds the framework glue for you:

auto-imported Dyrected composables
auto-registered components like DyrectedAdmin, DyrectedImage, and DyrectedMedia
a Nitro server handler when apiBase is a relative path
a provided SDK client that uses Nuxt request fetching

It also installs @nuxt/image so the shipped image component can render through Nuxt's image layer.

Install the module

pnpm add @dyrected/nuxt @dyrected/sdk

For self-hosted mode, also install the core package and your chosen database adapter.

Remote API mode

If Dyrected is already running somewhere else, point the module at that API:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@dyrected/nuxt"],
  dyrected: {
    apiBase: process.env.NUXT_PUBLIC_DYRECTED_URL || "",
  },
});

When apiBase is an absolute URL, the module does not add the Nitro server handler. In that mode, Nuxt acts as a client of the running Dyrected API.

Self-hosted mode

If the Dyrected backend should run inside the Nuxt app, keep apiBase as a relative path and merge in your config:

// nuxt.config.ts
import config from "./dyrected.config";

export default defineNuxtConfig({
  modules: ["@dyrected/nuxt"],
  dyrected: {
    ...config,
    apiBase: "/dyrected",
    adminPath: "admin",
  },
});

With a relative apiBase, the module registers the server handler for you and serves Dyrected under that path.

Import your Dyrected files with `#dyrected`

Nuxt 4 points ~ at the app/ folder, so an import like ~/server/dyrected/access looks for app/server/dyrected/access and fails. The module adds two aliases that always start from your project root, whichever Nuxt version you use:

Alias	Resolves to
`#dyrected`	`<root>/dyrected`
`#dyrected/server`	`<root>/server/dyrected`

For example, if you keep access rules in dyrected/access.ts and a database helper in server/dyrected/db.ts, you import them like this from anywhere in the project:

import { isFinance } from '#dyrected/access'
import { getDyrectedDb } from '#dyrected/server/db'

The alias only points at the folder, so both files are yours to create. If you already define either alias in nuxt.config.ts, yours wins.

Run background tasks

If your config defines background tasks, set runTasks: true and the module starts the runner with your server and stops it on shutdown. It's off by default, so nothing runs unless you ask for it.

export default defineNuxtConfig({
  modules: ["@dyrected/nuxt"],
  dyrected: { ...config, runTasks: true },
});

Use this on a long-lived Node server. On serverless hosts, call runDue() from a platform cron instead.

Add the admin page

The module auto-registers DyrectedAdmin, but you still choose the route that renders it:

<!-- app/pages/admin.vue -->
<script setup lang="ts">
definePageMeta({ layout: false });
</script>

<template>
  <ClientOnly>
    <DyrectedAdmin />
  </ClientOnly>
</template>

Use ClientOnly here because the admin UI needs the browser DOM.

`DyrectedAdmin` theme props

When the Nuxt app already owns a dark, light, or system preference, pass that state into DyrectedAdmin instead of letting the embedded admin keep a separate theme preference.

The component accepts three theme-control props:

theme: the preferred theme, one of system, light, or dark
system-theme: the current resolved OS theme, either light or dark
on-theme-change: callback fired when the admin changes its preferred theme

<!-- app/pages/admin.vue -->
<script setup lang="ts">
definePageMeta({ layout: false });

const { preference, systemTheme, setTheme } = useTheme();
</script>

<template>
  <ClientOnly>
    <DyrectedAdmin
      :theme="preference"
      :system-theme="systemTheme"
      :on-theme-change="setTheme"
    />
  </ClientOnly>
</template>

This keeps the site and embedded admin on the same preference while still letting admin-side theme controls update the host app state.

Fetch content with auto-imported composables

For normal reads, the module gives you a configured SDK client and Nuxt-friendly shortcuts:

useDyrectedCollection
useDyrectedDoc
useDyrectedGlobal
useDyrectedAuth
useLivePreview

Those are auto-imported by the module.

For the end-to-end rendering workflow, use Displaying Content in Nuxt.

Default path expectations

The module defaults apiBase to /dyrected. That means the typical self-hosted API surface is /dyrected/api/..., which lines up with the other framework integrations and the admin wrapper defaults.

If you change the path, keep your runtime config and any hard-coded app expectations aligned with it.

Production expectations

For self-hosted Nuxt:

the runtime still needs live database connectivity
the module can rebuild the Dyrected app when the server handler initializes
a successful front-end build alone does not prove the backend boundary is healthy

For remote API mode:

Nuxt only needs to be able to reach the configured Dyrected URL
your production concern becomes API availability and credentials, not local server mounting