devtools-layer-skilld

nuxtseo-layer-devtools

Shared Nuxt layer providing components, composables, and a design system for all Nuxt SEO module devtools clients.

Source: packages/devtools-layer/ (published as nuxtseo-layer-devtools)

Available Libraries

The layer registers these Nuxt modules, so all consumers have them available without extra config:

• @nuxt/ui (v4): Full component library. Use UButton, UBadge, UIcon, UInput, UTooltip, UApp, etc. freely. Default variants via app.config.ts (primary green, buttons ghost/neutral/sm, badges subtle/neutral/xs, tooltips zero delay).
• @vueuse/nuxt: All VueUse composables auto imported.
• Shiki: Syntax highlighting via the layer's loadShiki / useRenderCodeHighlight composables.

Architecture (Model C — source layer, assembled)

Each module ships its devtools panel as a source layer under devtools/. It is NOT a standalone app the module builds itself.

1. nuxtseo-shared/devtools (packages/shared/src/devtools.ts): setupDevToolsUI() registers the Nuxt DevTools iframe tab. In dev it assembles every installed SEO module's devtools/ layer + the base layer into one unified client, builds it once, and serves it at /__nuxt-seo-devtools/<slug> (one route per module). The module never extends the layer itself — the assembler writes the extending config.
2. nuxtseo-layer-devtools (packages/devtools-layer/): the base layer — shared components, composables, CSS, fonts.
3. Module client (<module>/devtools/): pages + lib for that module's panel. Extended by the assembler; renders at /__nuxt-seo-devtools/<slug>.

Rules

1. Module devtools/nuxt.config.ts is empty — export default defineNuxtConfig({}). The assembler wires the layer extension. Only add components: [{ path: resolve(__dirname, './components'), pathPrefix: false }] if the module ships its own components/<mod>/ UI.
2. Use EXPLICIT imports for layer composables — import { useDevtoolsConnection } from 'nuxtseo-layer-devtools/composables/rpc', import { appFetch } from '.../composables/rpc', import { isProductionMode, path, refreshTime } from '.../composables/state', import { loadShiki } from '.../composables/shiki'. Do NOT rely on auto-imports / #imports for layer composables (#imports is fine for Nuxt built-ins like navigateTo, useRoute, useAsyncData).
3. The consuming module's root tsconfig.json MUST exclude both dist and devtools. The devtools client is a separate layer-extended app, typechecked only when assembled — never at the module root. Omitting dist lets the client:build copy get typechecked in the wrong context (no layer auto-imports, drags the layer's raw .ts in) and breaks nuxt typecheck.
4. ALWAYS use layer components over custom HTML: DevtoolsSection not custom details, DevtoolsKeyValue not custom tables, DevtoolsSnippet/OCodeBlock not custom code blocks, DevtoolsPanel not a custom card, DevtoolsEmptyState/DevtoolsLoading/DevtoolsAlert not custom equivalents. Use KeyValueItem.code for inline code instead of separate snippets.
5. ALWAYS use @nuxt/ui components (UButton, UInput, UBadge, UIcon, UTooltip, etc.) for interactive elements. Never hand-roll a button/input/badge/tooltip.
6. NEVER add custom CSS that duplicates what the layer or Nuxt UI provides.
7. NEVER enable SSR in the client (it runs in an iframe) — the layer already sets ssr: false.
8. ALWAYS disable the module itself in the assembled client (the base layer sets robots: false, sitemap: false, content: false).
9. ALWAYS guard devtools setup with if (nuxt.options.dev) in module.ts; debug server routes are dev-only.
10. Debug endpoint convention: /__<module>__/debug.json (og-image is the historical exception: /_og/debug.json).
11. Use Carbon icons consistently (carbon: prefix). Give the debug tab devOnly: true; redirect dev-only tabs to the index in production via an isProductionMode watch.

Required File Structure

devtools/
├── nuxt.config.ts              # empty defineNuxtConfig({}) (+ components reg only if components/ exists)
├── pages/
│   ├── <mod>.vue               # DevtoolsLayout shell + <NuxtPage/> (REQUIRED)
│   └── <mod>/
│       ├── index.vue           # overview tab
│       ├── debug.vue           # devOnly tab
│       ├── docs.vue            # <DevtoolsDocs url=.../>
│       └── <other-tabs>.vue
├── lib/<mod>/
│   ├── state.ts                # data ref + refreshSources() + watch (REQUIRED)
│   └── rpc.ts                  # useDevtoolsConnection() (REQUIRED)
└── components/<mod>/           # OPTIONAL: module-specific UI only
src/
├── devtools.ts                 # wraps setupDevToolsUI from nuxtseo-shared/devtools
├── module.ts                   # setupDevToolsUI(dev only) + registers debug route
└── runtime/server/routes/__<module>__/
    └── debug.json.ts           # JSON debug endpoint

Implementation Templates

For full component/composable API reference, read reference.md.

devtools/nuxt.config.ts

// Assembled by nuxtseo-shared in the user's project; this extends the base layer there.
export default defineNuxtConfig({})

devtools/lib//rpc.ts

import { useDevtoolsConnection } from 'nuxtseo-layer-devtools/composables/rpc'

// The layer's connection plugin already wires appFetch + route tracking and refreshes
// on connect; state.ts watches refreshTime to reload data, so no module host access here.
useDevtoolsConnection()

devtools/lib//state.ts

import type { DebugData } from './types'
import { appFetch } from 'nuxtseo-layer-devtools/composables/rpc'
import { path, productionUrl, refreshTime } from 'nuxtseo-layer-devtools/composables/state'
import { ref, watch } from 'vue'

export const data = ref<DebugData | null>(null)

export async function refreshSources() {
  if (!appFetch.value)
    return
  data.value = await appFetch.value('/__<mod>__/debug.json', { query: { path: path.value } }).catch(() => null)
  if (data.value?.siteConfig?.url)
    productionUrl.value = data.value.siteConfig.url
}

watch([path, appFetch, refreshTime], () => {
  refreshSources()
})

devtools/pages/.vue (shell)

<script setup lang="ts">
import { isProductionMode } from 'nuxtseo-layer-devtools/composables/state'
import { computed, watch } from 'vue'
import { navigateTo, useRoute } from '#imports'
import { data, refreshSources } from '../lib/<mod>/state'
import '../lib/<mod>/rpc'

const route = useRoute()
const currentTab = computed(() => {
  const p = route.path
  if (p.startsWith('/<mod>/debug'))
    return 'debug'
  if (p.startsWith('/<mod>/docs'))
    return 'docs'
  return 'overview'
})
const navItems = [
  { value: 'overview', to: '/<mod>', icon: 'carbon:dashboard', label: 'Overview', devOnly: false },
  { value: 'debug', to: '/<mod>/debug', icon: 'carbon:debug', label: 'Debug', devOnly: true },
  { value: 'docs', to: '/<mod>/docs', icon: 'carbon:book', label: 'Docs', devOnly: false },
]
const version = computed(() => data.value?.runtimeConfig?.version || '')

watch(isProductionMode, (isProd) => {
  if (isProd && currentTab.value === 'debug')
    return navigateTo('/<mod>')
})
</script>

<template>
  <DevtoolsLayout
    v-model:active-tab="currentTab"
    module-name="nuxt-<module>"
    title="Title"
    icon="carbon:icon"
    :version="version"
    :nav-items="navItems"
    github-url="https://github.com/..."
    :loading="!data"
    @refresh="refreshSources"
  >
    <NuxtPage />
  </DevtoolsLayout>
</template>

DevtoolsLayout derives the npm package + update-check and renders DevtoolsTroubleshooting in the debug tab automatically from module-name — do not pass an npmPackage prop or hand-roll troubleshooting.

src/module.ts (dev only)

if (nuxt.options.dev) {
  addServerHandler({ route: '/__<module>__/debug.json', handler: resolve('./runtime/server/routes/__<module>__/debug.json') })
  setupDevToolsUI(config, resolve)
}