# 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.

# 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`:

```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:

```ts
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:

```ts
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](./agent-discovery.md).

## Root providers

The editable layout reads the common provider switches:

```ts
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:

```ts
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:

```bash
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.