SEO, document metadata, and analytics

Supacharger installs src/app/layout.tsx as a developer-editable root-layout template. It is explicitly excluded from CLI-managed updates because applications need different fonts, body classes, theme providers, route providers, and occasional extra head content.

The reusable behaviour lives in the protected src/supacharger/root-document.tsx module. Core updates keep that helper and the SupachargerConfig contract aligned across applications. The helper provides:

• a validated metadataBase from the canonical application URL;
• a default title and configurable child-page title template;
• description, application name, Open Graph, and Twitter defaults;
• production-aware robots metadata;
• the standard favicon and manifest declarations when enabled;
• colour-scheme and browser theme-colour viewport metadata; and
• optional Google Analytics and Vercel Analytics providers.

Next.js generates the charset, standard viewport, and other resulting head elements from its Metadata API. Do not duplicate them with hand-written <meta> tags.

Global metadata configuration

Configure global defaults in the developer-owned src/supacharger.config.ts:

METADATA: {
  SITE_URL: process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000',
  TITLE_TEMPLATE: '%s | My Product',
  INDEXING_ENABLED: process.env.VERCEL_ENV
    ? process.env.VERCEL_ENV === 'production'
    : process.env.NODE_ENV === 'production',
  FAVICON_SET_ENABLED: true,
  SOCIAL_IMAGE: {
    URL: '/opengraph-image.png',
    ALT: 'My Product',
    WIDTH: 1200,
    HEIGHT: 630,
  },
  COLOR_SCHEME: 'light dark',
  THEME_COLOR: {
    LIGHT: '#ffffff',
    DARK: '#111111',
  },
},

Use the stable public production origin for SITE_URL. Preview deployment URLs must not become canonical production URLs. INDEXING_ENABLED defaults to production-only behaviour in the supplied template, including Vercel preview protection.

Keep public/favicon.ico at the public root. Store favicon.svg, favicon-96x96.png, apple-touch-icon.png, both web-app manifest PNGs, and site.webmanifest under public/favicons/. Set FAVICON_SET_ENABLED only when that complete standard set exists. The protected metadata helper and web manifest use /favicons/... URLs for every asset except /favicon.ico.

A relative social-image URL is resolved against SITE_URL. Keep the image descriptive, product-owned, and suitable for social sharing.

The root helper deliberately does not declare one global canonical pathname: doing so would incorrectly make every route canonical to the home page.

Page titles and canonical URLs

A child layout or page can export ordinary Next.js metadata:

import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'Pricing',
};

This becomes Pricing | My Product through the root template. Use title.absolute only when a page deliberately needs a title outside that template.

For a page that also needs consistent canonical and social metadata, use the protected helper:

import { SC_CONFIG } from '@/supacharger/supacharger-config';
import { createSupachargerPageMetadata } from '@/supacharger/root-document';

export const metadata = createSupachargerPageMetadata(SC_CONFIG, {
  title: 'Pricing',
  description: 'Compare plans for My Product.',
  canonicalPath: '/pricing',
});

Dynamic pages may call the same helper from generateMetadata. Supply a canonical path only when it is the preferred public URL for that content. When overriding nested openGraph or twitter objects manually, remember that Next.js merges nested metadata shallowly.

Public content sites should also add accurate Next.js robots.ts and sitemap.ts files for their real route policy. Do not publish authenticated or private application routes in a sitemap.

Exclude the complete /_next/ framework namespace, /robots.txt, /sitemap.xml, /.well-known/, and .webmanifest files from the application's Proxy matcher. Framework assets, HMR, crawler metadata, association documents, and install manifests must return their direct responses without session refresh, localisation, authentication, onboarding, rewrite, or redirect handling. When development requests originate from the loopback alias rather than the hostname used to start Next.js, add only 127.0.0.1 to allowedDevOrigins.

For the Supacharger documentation site's own XML sitemap, agent-facing Markdown index, and raw page endpoints, see Agent-readable documentation.

Root providers

The editable layout reads the common provider switches:

ROOT_PROVIDERS: {
  INTERNATIONALISATION: true,
  THEME: true,
  TOASTS: true,
},

These switches determine whether the template mounts the standard layer. The concrete theme implementation, provider props, product route/context providers, fonts, and body classes remain application-owned. Specdrive can therefore retain its product-specific provider tree while using the same protected document and analytics helper.

Analytics

Google Analytics is opt-in and uses the integration recommended for Next.js App Router:

ANALYTICS: {
  GOOGLE_ANALYTICS_ID: process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID || null,
  VERCEL_ANALYTICS_ENABLED: true,
},

Set a GA4 measurement ID in the deployment environment:

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

The measurement ID is public configuration rather than a secret. When it is empty, Supacharger emits no Google Analytics component. When configured, the protected helper loads GoogleAnalytics from @next/third-parties/google; do not add duplicate inline gtag.js scripts. Vercel Analytics remains independently configurable.

Analytics configuration does not replace consent, privacy, retention, or regional compliance decisions. Add the consent mechanism required by the application's audience before enabling analytics where applicable.

Security controls such as Content Security Policy, HSTS, Permissions Policy, and Referrer Policy belong in HTTP response headers, not in the root metadata object.