Nuxt Layer Base (@tgmc/nuxt-layer-base)
@tgmc/nuxt-layer-base is the Nuxt 4 layer every TGMC app extends. It loads the theme, wires Sass for Vue styles, provides two accessibility components and the shared overlay and motion helpers, and sets up @nuxt/a11y, the tgmc: feature flags and (unless icon: false) @nuxt/icon. core/web and core/admin get it through @tgmc/nuxt-layer-ui (admin via @tgmc/web-layer-admin), which extends it and adds PrimeVue and the Ui* kit.
What it provides
Feature flags
- Module:
src/module/tgmc-features.ts(configKey: 'tgmc') stands in themoduleslist where@nuxt/iconstood. It readstgmc: { theme, icon, primevue, media }from the app’snuxt.config.ts(every flag defaults totrue) and publishes the resolved flags asappConfig.tgmc. Nuxt generates thetgmc?:config type from the module. useTgmcFeatures()(auto-imported): a computed ref of the flags with every missing one on. Kit components use it to drop icons (UiIcon,UiButton,UiChip).- Package check: a switched-on
themeoriconwhose packages aren’t installed (@tgmc/theme;@nuxt/iconand@iconify-json/lucide) fails the build with the missing names and thetgmc: { … : false }that turns the feature off. The ui layer runs the same check forprimevueandmedia. The names per flag areTGMC_FEATURE_PACKAGES(@tgmc/nuxt-layer-base/features). - PrimeVue bridge: with
primevue: falsethe module setsruntimeConfig.public.theme.bridges.primevuetofalse, souseUiStack()renders native markup. - Icons and the theme:
@nuxt/iconis installed in place withinstallModule(module and CSS order stay unchanged) or replaced by a null<Icon>stub;theme: falseswaps in the fallback (below). - Nitro: the layer adds
nitro.externals.inline: ['nuxt']. Without it, Nuxt 4.6’s server renderer returns 500 “Either manifest or precomputed data must be provided” for a minimal app, innuxt devand from the production server. Withnuxtinlined, PrimeVue pages also need@primeuix/utilsinlined, which the ui layer adds (nuxt-46-renderer-externalized-500.md). Arrays concatenate, socore/webandcore/admin, which list both themselves, get a harmless duplicate. - Module helpers for the ui layer:
@tgmc/nuxt-layer-base/module-kitexportsassertFeaturePackages,nodeModulesDirsandregisterFeatureOff.
What each flag turns off, and how the build matrix proves it: nuxt-layers.md § 1a.
Theme stylesheet and Sass
- Theme stylesheet: the first
cssentry is the alias#tgmc-theme-stylesheet, which defaults toapp/assets/css/theme.scss(@use 'pkg:@tgmc/theme/scss';). An app with its own theme entry points the alias at it.core/webandcore/adminboth point it atcore/web/assets/css/styles.scss, so their CSS order is unchanged. - Vue SFC styles get
@use "pkg:@tgmc/theme/scss/nuxt-auto" as *;(tokens, colour helpers, button and focus mixins; no CSS output) fromtgmcScssAdditionalData(). Only.vuestyle blocks are injected. Standalone sheets,node_modules, theme sources and blocks that already mentionnuxt-autoare skipped. Thepkg:URL resolves through the theme’s wildcard./scss/*export; the theme has no separate./scss/nuxt-autoexport. - Nuxt replaces a layer’s
additionalDatafunction with an app’s. An app that needs more@uses callstgmcScssAdditionalData(['@use "…" as *;'])from@tgmc/nuxt-layer-base/configinstead of writing its own.core/web/config-properties/scss-additional-data.tsdoes this for the app mixins. pkg:URLs resolve throughtgmcScssImporters, asass-embeddedNodePackageImporter(Vite compiles withsass-embeddedand only accepts that class). Importer arrays concatenate across layers, so apps don’t pass their own.- The layer also sets
quietDepsandsilenceDeprecationsfor the Sass compiler. These arrays concatenate too, so an app that repeats an entry gets a harmless duplicate. - With
tgmc: { theme: false }the alias points atscss/fallback.cssand the header becomes@use "pkg:@tgmc/nuxt-layer-base/scss/fallback" as *;(the focus mixins only).tgmcScssAdditionalData(extraUses, { theme })builds either header and tags the function so the module can rebuild it with the same extra@uses.scss/fallback.cssdeclares the theme custom properties the layers and generated apps read, each colour as a CSS system colour (Canvas,CanvasText,LinkText,ButtonFace…, withcolor-scheme: light dark, so light, dark and forced-colors modes follow the user’s settings), plus the floors (--touch-target,--type-min), radii, shadows (none), three font sizes and the.sr-onlyclass.scss/_fallback.scssholdsfocus-ringandfocus-ring-shadow, compiling to the same CSS as the theme’s. The theme exposes no breakpoint or floor mixins to SFCs either (nuxt-autodoesn’t forwardglobals/_mixins), so the fallback has none.tests/fallback-contract.spec.tsholds “used ⊆ fallback ⊆ theme”: every name the fallback declares exists in the theme, each fallback colour is exactly one system colour, and every mixin, custom property and utility class the layers and generated templates use is in the fallback. A layer that starts using another theme member adds it to the fallback in the same change.- The build fails for an app that points the alias at its own sheet or passes its own
additionalDatafunction, because neither can be switched safely.
Accessibility
<UiSkipLink target-id="main-content" label="Skip to main content" />: put it first in the layout. It stays above the viewport until focused, uses the theme contrast roles,--touch-targetand thefocus-ring-shadowmixin (visible in forced-colors mode), and moves focus to the target without changing the URL. The target needstabindex="-1"; the link adds it if it is missing.<UiAnnouncer />: mount it once, inapp.vue. It renders two live regions from the first paint, a politerole="status"and an assertiverole="alert", visually hidden with the theme’s.sr-onlyclass. Extra instances render nothing.useA11yAnnouncer():announce(text, 'polite' | 'assertive')andclear(politeness?). Each message is its own node, so back-to-back and repeated messages are all read, and a region empties after 7 seconds of quiet. State is per request (useState), and nothing is announced during SSR.@nuxt/a11yruns axe in the browser duringnuxt devwith the tagswcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aaandbest-practice. It highlights and logs violations in development and is off in production builds. The module has no report or fail-on-violation option, so builds rely on the axe checks in Vitest and Cypress (core/web-e2e/src/e2e/ui-audit.cy.ts).core/webkeeps its own skip link inapp/layouts/site.vueand does not useUiSkipLink.core/adminusesUiSkipLink. The web link hides the same way (app/layouts/site.scss): it is moved up by its own height plus 1rem until focused, so no part of its 44px box shows above the header; a fixed negativetopshorter than the box left a 4px sliver (fixed 2026-10-19,core/web/tests/a11y-shell.spec.ts).
Overlay and motion helpers
One copy of each, shared by core/web and core/admin. Utilities live in app/utils and composables in app/composables, all auto-imported.
inertOutside(el, keep = INERT_OUTSIDE_KEEP): makes every sibling ofeland of its ancestors up to<body>inert and returns an idempotent restore function. It is duck-typed (InertElement), skips non-rendered siblings (SCRIPT,STYLE,TEMPLATE,LINK,META,NOSCRIPT) and leaves elements that were already inert alone.INERT_OUTSIDE_KEEPmatches live regions and teleport hosts ([aria-live],role="status"/"alert",[data-ui-announcer],.p-toast,.ui-toast-host,#teleports,#__nuxt-route-announcer), so announcements and toasts stay live behind an overlay. A kept subtree is not inert, sokeepmust match announcement-only nodes.focusTrapTarget(focusables, active, shift)andFOCUSABLE_SELECTOR: the pure wrap rule for a Tab focus trap.useFocusTrap(container): returns{ onTab }to bind to the container’s Tabkeydown; only rendered controls count.useInertOutside(keep?): returns{ apply(el), release(), isApplied }aroundinertOutside, and releases on unmount, so a route change with the overlay open never leaves the page inert. Used by the web/galleryfull view (GalleryViewer) and the admin media drawer sheet; PrimeVue’s own Dialog and Drawer manage their own focus.useMatchMedia(query): reactivematchMedia(query).matches;falseon the server and until mount.usePrefersReducedMotion(): the app’s motion preference (useState('tgmc-motion'), defaultsystem), and undersystemthe OSprefers-reduced-motionsetting. The state key,MotionPreferenceandprefersReducedMotion(preference, osReduced)are exported from@tgmc/nuxt-layer-base/motion(src/runtime/motion.ts). The key only names in-memory Nuxt state; the saved choice stays inlocalStorageundertgmc-preferences(fieldmotion), andcore/web’susePersonalizationwrites the same state key (pinned bycore/web/tests/motion-state-key.spec.ts).
Icons
@nuxt/icon with Lucide as inline SVG from the app’s own server bundle (tgmcIconConfig() in src/config/icons.ts). TGMC_BASE_ICONS lists the names pre-bundled for every app; each app lists only its extra names in icon.clientBundle.icons. See icons.md. The feature module installs @nuxt/icon unless tgmc: { icon: false }; then <Icon> renders nothing.
Head
charset and viewport come from Nuxt’s app.head defaults. html lang belongs to the app (it conflicts with @nuxtjs/i18n).
Utilities
The layer auto-imports no utilities. Import SSR-safe helpers explicitly from @tgmc/utilities/universal (utilities.md), and never import @tgmc/utilities/browser into SSR code.
Usage
import { defineNuxtConfig } from 'nuxt/config';
export default defineNuxtConfig({
extends: ['@tgmc/nuxt-layer-base'],
});
An app with a UI (PrimeVue and the Ui* kit) extends @tgmc/nuxt-layer-ui instead, which extends this layer. core/web and core/admin both do.
@tgmc/theme, @nuxt/icon and @iconify-json/lucide are optional peers: declare the ones whose feature the app keeps on, or turn the feature off with tgmc: { theme: false } / tgmc: { icon: false } (nuxt-layers.md § 1a).
Development
- Nx targets:
build(a no-op, because the layer ships source),lint,testandtypecheck(coverssrc/**). The Nx Nuxt plugin is excluded for the layer innx.json. Until the workspace sync drift and the@tgmc/themespec type errors are fixed, runtypecheckasnpx nx run @tgmc/nuxt-layer-base:typecheck --skip-sync --excludeTaskDependencies. - Tests:
npx nx run @tgmc/nuxt-layer-base:test(Vitest and jsdom;#importsis a small stand-in intests/support/nuxt-imports.ts). Rootnpm testruns them (18 files, 79 tests). A spec that importssrc/config/scss.tsneeds// @vitest-environment node.tests/features-module.spec.tsboots the layer withloadNuxt(about 1 s) to check what each flag installs and registers. npm run prepare:types --workspace=@tgmc/nuxt-layer-basegenerates.nuxttypes for editing the SFCs.- Dependency ranges must equal the root’s (
core/web/tests/layer-dependency-ranges.spec.ts);@tgmc/*packages are*. - Open follow-ups: interaction-redesign.md § Nuxt layers and § Optional layer features. The wider layer design is in nuxt-layers.md.