@a1local/next-adpages

Dependency-light helpers for Next.js local-service landing pages. The package avoids a hard dependency on Next and exports plain TypeScript helpers that fit App Router metadata, JSON-LD script rendering, and middleware-style UTM capture.

What is included

• LocalBusiness JSON-LD helpers for Next/React <script> rendering.
• A small LocalBusinessJsonLd() descriptor helper for projects that want to wrap the script in their own component.
• Local service metadata generation for generateMetadata() or static metadata exports.
• Metadata checklist helpers for title, description, canonical, Open Graph, local service signals, and indexability.
• UTM capture helpers that can be used from middleware.ts without importing Next types.

Install

npm install @a1local/next-adpages

This package does not import next or react. It returns script props and metadata-shaped objects that are compatible with Next apps.

LocalBusiness JSON-LD

Use the prop helper directly in a Next page or layout:

import { createLocalBusinessJsonLdProps } from "@a1local/next-adpages";

export default function Page() {
  const jsonLd = createLocalBusinessJsonLdProps({
    name: "Example Plumbing",
    businessType: "Plumber",
    url: "https://example.com",
    telephone: "+61 8 0000 0000",
    areaServed: ["Perth", "Fremantle"],
    services: ["Emergency plumbing", "Blocked drains"]
  });

  return <script {...jsonLd} />;
}

If a project wants to centralize rendering, wrap the descriptor helper:

import { LocalBusinessJsonLd } from "@a1local/next-adpages";

function JsonLdScript() {
  const script = LocalBusinessJsonLd({
    name: "Example Plumbing",
    areaServed: ["Perth"],
    services: ["Hot water repairs"]
  });

  return <script {...script.props} />;
}

Metadata helpers

Generate Next-compatible metadata without importing Next types:

import { buildLocalServiceMetadata, checkNextLocalPageMetadata } from "@a1local/next-adpages";

export const metadata = buildLocalServiceMetadata({
  businessName: "Example Plumbing",
  service: "Emergency plumber",
  area: "Perth",
  baseUrl: "https://example.com",
  path: "/emergency-plumber/perth/"
});

const result = checkNextLocalPageMetadata(metadata, {
  service: "Emergency plumber",
  area: "Perth",
  businessName: "Example Plumbing"
});

The checklist result includes ok, score, missing, warnings, and item-level messages suitable for CLI output, build logs, or a future dev overlay.

UTM middleware notes

The UTM helpers deliberately return plain data so they can be wired into Next middleware without this package importing next/server:

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { createUtmMiddlewarePlan } from "@a1local/next-adpages";

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  const plan = createUtmMiddlewarePlan(request.url);

  if (plan.setCookieHeader) {
    response.headers.append("Set-Cookie", plan.setCookieHeader);
  }

  return response;
}

For App Router server components, read the adpages_utm cookie with next/headers and attach it to lead forms or analytics events. Do not treat the cookie as verified attribution data; it is a lightweight capture aid.

Publish status

This is an initial scaffold. Before publishing, add final package ownership, public docs URL, examples from a real Next app, and any marketplace-specific support/privacy links.