Next.js 15React 19PWASEO-firstEnv-driven
SEO-First PWA Starter — AIFA
Production-ready Next.js starter with battle-tested SEO infrastructure, Progressive Web App core, and env-driven configuration. Ship search-optimized, installable apps instantly — Next.js 15 + React 19.
15+
Core features
A+
SEO score ready
PWA
Installable
Env
Config-only
What you get out of the box
SEO Kernel
Metadata API, i18n alternates, OpenGraph/Twitter, JSON-LD builders, robots with AI crawlers.
Learn more →PWA Stack
Manifest, icons, shortcuts, screenshots, SW caching for fonts/images/API, install-ready.
Learn more →DX & Structure
App Router, Env-only branding, semantic routes, error/not-found pages, ISR-friendly.
Learn more →AI-ready
AI bots access rules, knowledge routes (blog/news/docs), and performance baseline.
Learn more →Security Headers
nosniff, XSS, frame options, referrer policy, permissions policy baked-in.
Learn more →Deep-dive quick panels
SEO Core
- • Metadata API with env-driven branding
- • robots.txt with AI crawlers allowlists
- • sitemap.ts with i18n alternates and priority
- • JSON-LD builders: Article, FAQ, Product, Breadcrumb
Setup hints
- Set NEXT_PUBLIC_SITE_URL and NEXT_PUBLIC_APP_NAME in .env.local
- Configure title template in pageDefaults.titleTemplate
- Add Search Console codes when ready
SEO Core
- • Metadata API with env-driven branding
- • robots.txt with AI crawlers allowlists
- • sitemap.ts with i18n alternates and priority
- • JSON-LD builders: Article, FAQ, Product, Breadcrumb
Setup hints
- Set NEXT_PUBLIC_SITE_URL and NEXT_PUBLIC_APP_NAME in .env.local
- Configure title template in pageDefaults.titleTemplate
- Add Search Console codes when ready
Configure in minutes
Brand & SEO via .env
- • NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_APP_DESCRIPTION
- • NEXT_PUBLIC_DEFAULT_LOCALE, NEXT_PUBLIC_TWITTER_HANDLE
- • NEXT_PUBLIC_GOOGLE_VERIFICATION, NEXT_PUBLIC_YANDEX_VERIFICATION
PWA in production
- • Manifest with 192/512 icons and maskable variants
- • SW: Google Fonts, images, API caching strategies
- • Screenshots for install prompt (env-driven)
Core features
Core Features FAQ
How does the Sitemap generation work?
- The starter generates a dynamic sitemap.xml using app/sitemap.ts. It supports static routes, dynamic routes from databases, i18n alternates, and priority/lastModified timestamps. Maximum 50,000 URLs per sitemap with automatic pagination.
Can I customize sitemap priorities and update frequency?
- Yes. The sitemap.ts file exposes lastModified, changeFrequency, and priority fields for each route. Update these values based on your content strategy to signal freshness to search engines.
Does the sitemap include hreflang alternates for multi-language sites?
- Yes. The sitemap automatically includes hreflang alternates when configured with locales. This helps search engines understand language variations and canonical relationships.
Where can I find the generated sitemap?
- Access it at /sitemap.xml. The starter provides cache headers: public, max-age=3600, ensuring crawlers always get a reasonably fresh copy without overwhelming your server.
How can I control which bots can access my site?
- Edit app/robots.ts to set allowlist/disallowlist for crawlers. By default, search engines and AI bots (GPTBot, PerplexityBot) are allowed. Disallow sensitive paths like /admin, /api, /auth.
Can I block AI bots while allowing Google?
- Absolutely. In app/robots.ts, create separate rules: Allow Googlebot, disallow GPTBot, PerplexityBot, etc. Use userAgent arrays for granular control over each bot type.
What do noindex and nofollow directives do?
- noindex tells crawlers "do not include this page in search results." nofollow tells crawlers "do not follow links on this page." Both can be set per-route or globally in app/robots.ts.
Do I need to keep robots.txt and app/robots.ts in sync?
- No. In Next.js 15+, app/robots.ts generates robots.txt automatically during build. Just maintain one source of truth in app/robots.ts and the generated file serves as the public endpoint.
What is a Web App Manifest and why is it important?
- A manifest.webmanifest file tells browsers how to install your PWA on user devices. It includes app name, icons, colors, start URL, and display mode. Without it, your app cannot be installed.
How do I provide multiple icon sizes?
- The starter includes 192x192, 512x512, and maskable variants. Define them in manifest.webmanifest with purpose: "any" for standard icons and purpose: "maskable" for adaptive icons that adapt to device shape.
What is a maskable icon?
- A maskable icon is a circular icon with transparent padding. Devices cut it into different shapes (square, circle) depending on OS. Provide both standard and maskable variants for maximum compatibility.
Can I customize the app display mode?
- Yes. Set display: "standalone" (full screen, hides browser chrome), "minimal-ui" (minimal browser UI), or "browser" (standard browser). The starter defaults to "standalone" for better UX.
What goes into App Config?
- App Config centralizes branding, SEO, PWA, and feature flags. It reads from environment variables (NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_TWITTER_HANDLE, etc.) and provides type-safe access throughout your app.
How do I change the site branding without code changes?
- Update .env.local: NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_APP_DESCRIPTION, NEXT_PUBLIC_APP_SHORT_NAME, NEXT_PUBLIC_PWA_THEME_COLOR. Rebuild and all pages automatically reflect the new branding.
Can I use App Config for feature toggles?
- Yes. Add custom flags to appConfig object. For example, NEXT_PUBLIC_ENABLE_ANALYTICS, NEXT_PUBLIC_MAINTENANCE_MODE. Access them conditionally in components: if (appConfig.enableAnalytics) { ... }
Is App Config safe to expose to the client?
- Only use NEXT_PUBLIC_ prefix for client-side variables. Private env vars (without NEXT_PUBLIC_) stay on the server. The starter respects this boundary automatically.
What optimizations does Next Config provide?
- Next Config enables SWC minification, image optimization (WebP/AVIF), security headers (CSP, HSTS), cache strategies for static assets, fonts, and APIs. All reduce page size and improve Core Web Vitals.
How are images optimized automatically?
- next/image component resizes images for each device size (640px to 3840px), converts to modern formats (WebP/AVIF), lazy-loads off-screen images, and generates blurred placeholders for instant perception of load.
What security headers does the config include?
- CSP (Content Security Policy) restricts resource loading, HSTS forces HTTPS, X-Frame-Options prevents clickjacking, Referrer-Policy controls link referrer info, Permissions-Policy restricts camera/microphone access.
How do cache headers improve performance?
- Static assets (public/) are cached 1 year (immutable), images 1 year, fonts 1 year. API responses use no-cache/no-store to stay fresh. Browsers skip network requests for cached assets, reducing latency 90%+.
What is a PWA install prompt?
- An install prompt is a browser dialog offering to add your app to the home screen. The starter detects when users are likely to install and shows a custom prompt, dramatically increasing installation rates.
Does the install prompt work on all browsers?
- Install prompts are native on Android Chrome and desktop Edge/Chrome. On iOS Safari, the component shows step-by-step instructions via alert, as iOS does not support the native beforeinstallprompt API. Unsupported browsers gracefully degrade.
Can I customize the install prompt appearance?
- Yes. The PWAInstallPrompt component accepts custom text, icons, and colors. You can match it to your brand and adjust timing via deferPrompt logic.
How do users uninstall after installing?
- Users uninstall like any app: long-press app icon → remove (mobile) or Settings → Apps → Uninstall (desktop). No special code needed; the browser handles all lifecycle management.
What caching strategies does the Service Worker use?
- Cache-First for static assets (images, fonts, CSS, JS) — serve from cache, fallback to network. Network-First for pages and APIs — try network first, fallback to cache. Custom strategies implemented in public/sw.js without external dependencies.
Does the Service Worker support push notifications?
- Yes. The Service Worker includes handlers for push events and notification clicks. Configure push subscriptions via Web Push API. The starter provides boilerplate code in public/sw.js, but server-side push integration requires additional setup.
How does the Service Worker handle offline?
- If the network fails, the SW checks the cache. If found, serves cached version. If not found, shows an offline fallback page. Users stay productive even without internet, reconnecting automatically when possible.
Can I clear caches and force a fresh install?
- Yes. The Service Worker activation hook cleans old cache versions. Users see an update prompt, click "skip waiting" to activate new version. register-sw.js checks for updates hourly.
Does the Service Worker break SEO?
- No. The SW only handles runtime caching. SEO relies on HTML delivered server-side (SSR/SSG). Crawlers see full HTML before JS runs. The SW improves performance, which improves SEO rankings.
What does constructMetadata() do?
- It generates all metadata for a page: title template, meta description, OpenGraph tags, Twitter Cards, canonical URL, icons, robots directives, and verification codes. One function call replaces 20+ lines of boilerplate.
How does constructMetadata prevent duplicate content?
- It automatically sets canonical URL to the current route, preventing search engines from indexing duplicates. For multi-locale sites, it adds hreflang alternates.
Can I override defaults for a specific page?
- Yes. Pass parameters: constructMetadata({ title: "Custom Title", description: "...", pathname: "/custom", contentType: "article" }). Unspecified fields use app-config defaults.
Does constructMetadata handle social media previews?
- Yes. It generates OpenGraph (Facebook, LinkedIn) and Twitter Card metadata. When users share links, platforms show rich previews: image, title, description. Vastly improves click-through rates.
What JSON-LD schemas are available?
- WebSite, Organization, Person, Article, BlogPosting, Product, FAQPage, BreadcrumbList, CollectionPage, VideoObject. Each generator ensures valid schema.org structure and auto-fills URLs.
Why use JSON-LD instead of microdata?
- JSON-LD is cleaner (separate from HTML), easier to maintain, less error-prone. Search engines treat both equally, but JSON-LD is recommended by Google and Schema.org.
How do schemas improve search results?
- Schemas enable Rich Snippets: prices/ratings for products, question/answer accordion for FAQs, navigation breadcrumbs, author info for articles. These stand out in SERP, increasing click-through rates 20-40%.
Can I use multiple schemas on one page?
- Yes. Combine Article + BreadcrumbList + Organization. The starter provides mergeSchemas() to combine multiple schemas. Each <script type="application/ld+json"> block is separate and valid.
What happens if JavaScript is disabled?
- The page still renders. All content in semantic HTML (article, section, h1, p, etc.) is immediately visible. Navigation works via links. Forms work if server-side handlers exist. Graceful degradation, not total failure.
Why should I care about noscript users?
- Search engines often crawl without JS execution (especially Bing, smaller engines). Users on slow networks disable JS to reduce data. Accessibility tools (screen readers) work better with semantic HTML.
How do I test my site without JavaScript?
- Disable JS in DevTools (F12 → Settings → Disable JavaScript). Reload. If layout breaks or content disappears, refactor to use semantic HTML, CSS layout, and server-side rendering.
Should I remove interactive features if JS is disabled?
- No. Degrade gracefully: buttons become links, modals become pages, carousels become static lists. Show a noscript warning if core functionality requires JS. The starter includes a helpful noscript fallback.
What is Static Generation (SSG)?
- Pages are pre-rendered at build time into static HTML. Each request serves the same HTML from a cache. Zero server-side processing, instant load times, perfect for blogs, marketing sites.
What is Incremental Static Regeneration (ISR)?
- Set revalidate = 3600 (seconds) on a page. First request after 3600s triggers a rebuild in the background. Users see old cached page (fast), next user sees fresh version. Best of both worlds.
When should I use Static Generation vs. Server-Rendering?
- Static: blogs, landing pages, docs, products (content changes infrequently). Server-rendering: dashboards, user-specific content, real-time data. Combine both: static homepage + SSR for dynamic sections.
How do I regenerate a page when content changes?
- Use ISR with revalidate export (e.g., export const revalidate = 3600). For on-demand revalidation, add Server Actions with revalidatePath("/blog") or revalidateTag("blog"). This requires additional setup beyond the starter.
What is Content Security Policy (CSP)?
- CSP restricts where resources (scripts, styles, images) can load from. Prevents malicious scripts from injecting code. Example: script-src self → only your own scripts run.
What does HSTS do?
- HTTP Strict-Transport-Security forces HTTPS only. After first visit, browsers refuse to load your site over HTTP, blocking man-in-the-middle attacks. Set max-age to 31536000 (1 year).
What is Referrer-Policy?
- Controls what referrer info is sent when users click your links. strict-origin-when-cross-origin only sends domain name (not full URL) to external sites, protecting privacy.
Do security headers harm performance?
- No. They add tiny response headers, negligible overhead. The upside: blocked XSS attacks, clickjacking prevention, protection against malicious ads. Security headers have 0 downside.
Ship your AI app with confidence
Start with an installable PWA, SEO kernel, and production conventions. Configure everything through environment variables and scale without rewrites.