@stackonward/nuxt-site-shell

@stackonward/nuxt-site-shell

Brand-free Nuxt product-site layer for shared modules, runtime configuration, SEO defaults, theme seams, assets, and cache policy. It extends @stackonward/nuxt-layer-base but does not ship product pages or business workflows.

Install

pnpm add @stackonward/nuxt-site-shell @stackonward/nuxt-layer-base @nuxt/image @nuxt/ui @nuxtjs/seo @pinia/colada-nuxt @vueuse/nuxt @iconify-json/lucide pinia tailwindcss unhead

Nuxt and Vue are peer dependencies of the consuming application.

Extend the layer

export default defineNuxtConfig({
  extends: ["@stackonward/nuxt-site-shell"],
});

Set the public site values through the deployment environment:

NUXT_PUBLIC_SITE_URL=https://product.example
NUXT_PUBLIC_SITE_NAME=Product Name
NUXT_PUBLIC_SITE_DESCRIPTION=What the product helps people accomplish.
NUXT_PUBLIC_SITE_ENV=production
NUXT_PUBLIC_APP_VERSION=1.2.3

Included stack

The layer composes:

• Nuxt UI with system color mode and Lucide icons;
• VueUse and Pinia Colada;
• Nuxt Image with no provider selected by default;
• the Nuxt SEO module suite;
• strict TypeScript and Nuxt 4 layer semantics;
• compression, immutable built assets, no-cache application/API routes, and sitemap caching.

Non-production environments are non-indexable and add noindex,nofollow. Production enables indexability and sitemap output based on NUXT_PUBLIC_SITE_ENV=production.

Public runtime configuration

Open Graph image generation and Schema.org identity are opt-in through NUXT_PUBLIC_OG_IMAGE_ENABLED and NUXT_PUBLIC_SCHEMA_ORG_ENABLED.

Override product-owned decisions

A consuming application should replace the generic site name, description, URL, logo, icons, default Open Graph image, organization identity, locales, image provider, and any external connection hints it does not use. Nuxt layer merging keeps those decisions in the product repository.

The layer exposes configuration seams for Google identity and checkout URLs; it does not implement authentication or payment flows. Add the corresponding product modules and server APIs explicitly.

Runtime entry

import { formatTitle, type NavItem } from "@stackonward/nuxt-site-shell/runtime";

const title = formatTitle("Pricing", "Product Name");
const item: NavItem = { label: "Pricing", to: "/pricing" };

The runtime entry exports brand-neutral navigation, footer, content-summary, article, and Config types plus formatTitle. These are contracts for consumer-owned shells; this layer does not render them.

Optional Web Push worker build

The @stackonward/nuxt-site-shell/web-push module bundles a product-owned worker entry into a standalone same-origin script:

export default defineNuxtConfig({
  modules: [["@stackonward/nuxt-site-shell/web-push", { entry: "app/web-push/worker.ts" }]],
});

The exported WorkerModuleOptions accepts a project-relative entry and an optional single .js filename (default push-sw.js). No entry means no build effect. The module publishes the bundle through Nitro public assets, prevents conflicting existing public files, emits production output after Nuxt CLI cleanup, and disposes its development watcher on Nuxt close. Keep the browser registration URL consistent with the selected filename and application base URL.

This module does not request permission, create subscriptions, send messages or select a provider. Use @stackonward/web-push/worker for generic worker behavior and a named protocol decoder such as @stackonward/onex-web-push. Consent UI, brand text and destinations remain product-owned. The CLI Nuxt template includes editable composition and worker sources with runtime activation disabled by default.

Compatibility

• Nuxt >=3.15.0
• Vue ^3.5.0
• Nuxt UI >=4.9.0 <5
• Nuxt Image >=2.0.0 <3
• Nuxt SEO >=5.3.0 <6
• Pinia >=3.0.4 <4 and Pinia Colada Nuxt >=1.0.0 <2
• VueUse Nuxt >=14.0.0 <15
• Tailwind CSS >=4.0.0 <5
• Unhead >=3.1.7 <4

Related packages

• @stackonward/nuxt-layer-base owns the smaller API/session/i18n foundation.

License

MIT