SEO Next.js Starter

A head start for your next search result. An open-source Next.js starter with page metadata, sitemaps, social images, and practical examples you can inspect and adapt.

Live demo · Documentation · Examples · Vercel template

What ships with v1

• Page-specific SEO: titles, descriptions, canonical URLs, Open Graph, and Twitter cards through one metadata helper.
• Production-aware indexing: route-based sitemap, robots, local/Preview noindex, and an explicit production URL.
• Dynamic social images: 1200 × 630 PNG images generated with next/og, plus a matching icon.
• Inspectable examples: a journal with static articles and dynamic metadata, plus a product page with a working launch checklist.
• Structured data: WebSite, SoftwareSourceCode, Article, and BreadcrumbList examples with escaped JSON-LD output.
• Bilingual documentation: English and Chinese routes with reciprocal hreflang, working legacy README redirects, and readable code blocks.
• Responsive design: light/dark themes, keyboard navigation, interactive SEO previews, and author project cards.
• Repeatable checks: ESLint, TypeScript, Node tests, production build, and HTTP SEO assertions in GitHub Actions.

Built with Next.js 16, React 19, TypeScript 5, Tailwind CSS 4, Node.js 22, and pnpm 11. This is a set of SEO foundations, not a promise of rankings or a particular performance score.

Quickstart

Create a repository with the Use this template button above, then clone your new repository:

# Node.js 22.x; install pnpm 11.24.0 if needed
npm install --global pnpm@11.24.0
pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm dev

Open localhost:3000. No account, database, or analytics service is needed to run the examples.

Site configuration

Set these in .env.local for development and in your deployment environment for production:

NEXT_PUBLIC_SITE_NAME="Your site"
NEXT_PUBLIC_TITLE="Your page title"
NEXT_PUBLIC_DESCRIPTION="A useful description of your website."
NEXT_PUBLIC_URL="https://example.com"
# Optional: set false to opt out of indexing
# NEXT_PUBLIC_INDEXABLE="false"
# Optional: your own GA measurement ID; leave unset to disable analytics
# NEXT_PUBLIC_GOOGLE_ANALYTICS_ID="G-XXXXXXXXXX"
# Optional: your Plausible script URL
# NEXT_PUBLIC_PLAUSIBLE_SCRIPT=""

Set NEXT_PUBLIC_PLAUSIBLE_SCRIPT at build time to load your Plausible script and initialization snippet in every page's head. Leave it unset to render neither script. Rebuild after changing it; existing Google Analytics configuration is independent.

NEXT_PUBLIC_URL must be an HTTP(S) origin without a path, query, or credentials. Configure your real production domain before publishing. If omitted, Vercel deployments resolve their own project domain; local development falls back to http://localhost:3000. Preview deployments remain noindex even when the production URL is configured. Noindex pages allow crawling so robots can read that directive.

Add a page's metadata in its server component:

import { pageMetadata } from "@/lib/seo";

export const metadata = pageMetadata(
  "About us",
  "/about",
  "Learn about the people and ideas behind our website.",
);

When adding or removing pages, also update src/app/sitemap.ts. Customize src/config.ts, the examples, and the author cards for your own project. The homepage preview is illustrative; search engines can rewrite titles and snippets.

Deploy on Vercel

1. Create your own repository and Vercel project with the button.
2. Set NEXT_PUBLIC_URL to your production origin and customize your site name, title, and description. Add your custom domain in Vercel if using one.
3. Deploy, then inspect /sitemap.xml, /robots.txt, and /api/og. Check the rendered HTML for canonical and social tags.
4. After changing environment variables, redeploy. Keep Preview deployments noindex; do not copy the demo's domain or analytics ID into your project.

The maintained demo is seo-nextjs.alin.run; the existing Vercel demo URL also remains available. The marketplace listing is maintained separately from Git deployments.

Check your changes

pnpm check        # lint, route types, TypeScript, tests, production build
pnpm start        # in a second terminal
pnpm test:seo     # checks actual HTTP responses at localhost:3000
# Optional: SEO_CHECK_URL=https://your-site.com pnpm test:seo

The HTTP checks cover example routes, canonical and sharing metadata, document language alternates, sitemap/robots, PNG assets, redirects, 404 responses, and the bundled author links. Adapt the route and author-link expectations when you customize the template. See migration notes and the changelog when upgrading from 0.2.x.

Project map

Path	Purpose
src/config.ts	Site identity and resolved URL
src/lib/seo.ts	Page metadata and breadcrumb helpers
src/app/sitemap.ts, robots.ts	Discovery and indexing policy
src/app/api/og/route.tsx	Dynamic social PNG
src/content/articles.ts	Journal example content
src/content/docs.*.md	Bilingual website documentation
tests/, scripts/check-seo.mjs	Configuration and HTTP checks

Projects from the Author

A few other tools and creative experiments by Leo Wang:

• Toolbox Hub — Free online tools.
• H3Run — AI video creation.
• H3MaxLive — Interactive AI video.
• Image 2.5 — AI image creation and editing.

These are author projects, not claims that they use this starter. You can remove or replace the showcase in your own site; keep the copyright and license notice as required by the MIT license.

Share what you build

Have a project built with this template? Submit your website or report an issue. Contributions are welcome; run the checks and keep changes focused. Commit messages follow this public repository's English Conventional Commits style.

License

MIT. Free to use, modify, and build on.