belt 0.6.5 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39a9c396d05b2acfc5c69adc875f0050beb9395a2dc9f31dd4ac2d2221e011db
-  data.tar.gz: ddf3e2d95ea98eafc808f0d2e144196257f4880fb1b8d65ae063dd27becb9213
+  metadata.gz: ef904a59417a3f019eab7e6339fc6d13290bf05ff3d1d435c434834cea189bc2
+  data.tar.gz: 93a8820ef48b523d41e7a4aa8d0544090b2472bc7805b96bfee9f0f45c8e8114
 SHA512:
-  metadata.gz: f3463e2d5e75fc653437accecb76a3a66683cd28bf7781a9aadbef167b2cf3f18ad4d5e32fb3cb5f57c6e406929253f6f762ebecec5a4d20b2723c9a8118efd8
-  data.tar.gz: f1ccdeca8439a8063940c981f9c05a24abb319bcb0aa76c7212e0883fc6a9c4db7ee10f0e2da1f93105d1bca68844bd108ca7e820b8a462c900d309d35231905
+  metadata.gz: b562534dbed0dcad13db7d4e6f0ff9ff99f469af4de025a682902375d39ffe0bf73447a749674443acb81632e40f2f2c4b0e34ceced872a37d4a904dd5725b7f
+  data.tar.gz: d0915177422b65ef6f9a2dfb542cdd63b578acdbae1abf97cc4699354400b046e507818f71f7756a73f54183916921d2ad6862c877c4b8385fc6feb22ebd7b2d

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.7
+
+### Changed
+
+- **Non-prod deploys auto-approve by default.** `belt deploy <env>` no longer
+  prompts for confirmation when the environment isn't `prod`/`production` — the
+  Terraform plan is applied straight away. `prod` still prompts unless you pass
+  `--auto`. Pass `--confirm` (alias `--no-auto`) to force the prompt on any
+  environment. No more typing `--auto` on every dev deploy.
+
+## 0.6.6
+
+### Added
+
+- **SEO/AEO by default for React frontends.** `belt generate frontend react` now
+  prerenders every public page listed in `src/seo.js` at build time (React SSR via
+  `src/entry-server.jsx` + `scripts/prerender.js`), so crawlers and AI answer engines
+  that don't run JavaScript get real content plus a per-page `<title>`, description,
+  canonical URL, Open Graph tags and JSON-LD. The build also writes `robots.txt`,
+  `sitemap.xml` and `llms.txt`. Only `prod` is indexable by default; every other
+  environment ships `Disallow: /` + `noindex`. `belt explain seo`. (Fizzy #1385)
+- **`belt deploy frontend` uploads prerendered pages** to their extensionless S3 keys
+  as `text/html`, passes `BELT_ENV` and `VITE_SITE_URL` to the build, and serves HTML,
+  `robots.txt`, `sitemap.xml` and `llms.txt` with `no-cache` instead of the immutable
+  header meant for hashed assets.
+
 ## 0.6.5
 
 ### Added

data/SKILL.md

@@ -56,6 +56,7 @@ belt doctor            # check deps + AWS config
 | Deploy to AWS | `belt deploy <env>` (`--auto` to skip prompt) |
 | Poke at data live | `belt console <env>` |
 | Run a local frontend | `belt server` (see references for env targeting) |
+| Make a public page findable (SEO/AEO) | Add it to `frontend/src/seo.js` → `pages`; see `belt explain seo` |
 | Add Cognito auth | `belt generate auth` → `cognito_authenticatable` in a model |
 | Build a plugin | `belt plugin new <name>` |
 | Learn a concept | `belt explain <topic>` |

data/lib/belt/cli/deploy_command.rb

@@ -32,6 +32,7 @@ module Belt
         end
 
         auto_approve = false
+        force_confirm = false
         rebuild = false
         skip_backup = false
         backup_only = false
@@ -42,6 +43,8 @@ module Belt
           case arg
           when '--auto', '--yes', '-y'
             auto_approve = true
+          when '--confirm', '--no-auto'
+            force_confirm = true
           when '--rebuild'
             rebuild = true
           when '--skip-backup', '--no-backup'
@@ -69,13 +72,14 @@ module Belt
             puts 'Usage: belt deploy [environment] [options]'
             puts "\nDefaults to BELT_ENV or the first available environment."
             puts "\nOptions:"
-            puts '  --auto, --yes, -y    Skip confirmation prompt (auto-approve)'
+            puts '  --auto, --yes, -y    Skip confirmation prompt (prod only; non-prod auto-approves)'
+            puts '  --confirm, --no-auto Force the confirmation prompt even for non-prod envs'
             puts '  --rebuild            Rebuild and push Lambda code directly (bypasses Terraform)'
             puts '  -h, --help           Show this help'
             puts "\nExamples:"
-            puts '  belt deploy                # Deploy dev (or BELT_ENV)'
-            puts '  belt deploy prod           # Deploy to prod'
-            puts '  belt deploy dev --auto     # Deploy without confirmation'
+            puts '  belt deploy                # Deploy dev (or BELT_ENV), no prompt'
+            puts '  belt deploy prod           # Deploy to prod (prompts)'
+            puts '  belt deploy prod --auto    # Deploy prod without confirmation'
             puts '  belt deploy --rebuild      # Fast code push (no infra changes)'
             puts '  belt deploy frontend dev              # Deploy frontend(s)'
             puts '  belt deploy frontend dev --frontend ops'
@@ -84,6 +88,10 @@ module Belt
           end
         end
 
+        # Non-prod environments auto-approve by default — prod always prompts
+        # unless --auto is explicit. Pass --confirm to force the prompt anywhere.
+        auto_approve = true if !force_confirm && !%w[prod production].include?(env)
+
         options = { auto_approve: auto_approve, skip_migrations: skip_migrations, extra_args: filtered_args }
         if backup_only
           new(env, **options, skip_backup: false).run_backup_only
@@ -108,13 +116,16 @@ module Belt
             4. Build sidecar Lambda zips Terraform needs at plan time
             5. terraform init    (initialize providers/modules)
             6. terraform plan    (preview changes)
-            7. Prompt for confirmation (unless --auto)
+            7. Prompt for confirmation (prod only; non-prod auto-approves)
             8. terraform apply   (deploy changes)
             9. Nested envs: share parent Cognito + copy DynamoDB if empty
            10. Run pending data migrations in db/migrate (see `belt db:migrate`)
 
           Options:
-            --auto, --yes, -y    Skip confirmation prompt (auto-approve)
+            --auto, --yes, -y    Skip confirmation prompt (auto-approve). Non-prod
+                                 environments auto-approve by default, so this is only
+                                 needed for prod.
+            --confirm, --no-auto Force the confirmation prompt even for non-prod envs
             --rebuild            Rebuild and push Lambda code directly (bypasses Terraform).
                                  Much faster for code-only changes — packages gems via Docker,
                                  zips, and pushes with `aws lambda update-function-code`.
@@ -140,9 +151,10 @@ module Belt
               end
 
           Examples:
-            belt deploy                # Deploy dev (or BELT_ENV)
-            belt deploy prod           # Deploy to prod
-            belt deploy dev --auto     # Deploy without confirmation (CI mode)
+            belt deploy                # Deploy dev (or BELT_ENV), no prompt
+            belt deploy prod           # Deploy to prod (prompts for confirmation)
+            belt deploy prod --auto    # Deploy to prod without confirmation (CI mode)
+            belt deploy dev --confirm  # Force the confirmation prompt on dev
             belt deploy --rebuild      # Fast code push to dev (no infra changes)
             belt deploy prod --rebuild # Fast code push to prod
             belt deploy prod --skip-backup  # Skip backups for this deploy

data/lib/belt/cli/explain_command.rb

@@ -45,6 +45,8 @@ module Belt
         'repl' => 'console',
         'frontends' => 'frontend',
         'spa' => 'frontend',
+        'seo' => 'frontend',
+        'aeo' => 'frontend',
         'seeds' => 'data_seeding',
         'seed' => 'data_seeding',
         'seeding' => 'data_seeding',

data/lib/belt/cli/frontend_deploy_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'shellwords'
 require 'open3'
 require_relative 'app_detection'
@@ -14,6 +15,10 @@ module Belt
     class FrontendDeployCommand
       include AppDetection
 
+      PAGES_MANIFEST = '.belt-pages.json'
+      # Uploaded with no-cache instead of the immutable header hashed assets get
+      REVALIDATED_FILES = %w[*.html robots.txt sitemap.xml llms.txt].freeze
+
       def self.run(args)
         frontend_name = FrontendRegistry.extract_flag!(args, '--frontend')
         env = EnvResolver.resolve(args)
@@ -109,12 +114,19 @@ module Belt
         run!(env, 'npm', 'run', 'build', chdir: @frontend.path)
       end
 
+      # BELT_ENV and VITE_SITE_URL drive the SEO prerender step (scripts/prerender.js):
+      # only indexable environments get crawled, and canonical/sitemap URLs need the
+      # site's origin. The env map or the shell can override either.
       def frontend_build_env
-        FrontendEnvMap.new(
+        env = FrontendEnvMap.new(
           @env,
           env_dir: @env_dir,
           frontend_path: @frontend.path
         ).process_env
+        env['BELT_ENV'] ||= @env
+        site_url = ENV['VITE_SITE_URL'] || fetch_frontend_url
+        env['VITE_SITE_URL'] ||= site_url if site_url
+        env
       end
 
       def sync_to_s3
@@ -130,18 +142,49 @@ module Belt
         puts "☁️  Deploying to S3... (#{bucket})"
 
         dist_prefix = dist.end_with?('/') ? dist : "#{dist}/"
+        pages = prerendered_pages(dist)
 
-        # Hashed assets get immutable cache headers
+        # Hashed assets get immutable cache headers. Prerendered page keys are
+        # excluded so --delete doesn't remove them before they're re-uploaded.
         run!('aws', 's3', 'sync', dist_prefix, "s3://#{bucket}", '--delete',
              '--size-only', '--cache-control', 'public, max-age=31536000, immutable',
-             '--exclude', 'index.html')
+             *[*REVALIDATED_FILES, PAGES_MANIFEST].flat_map { |f| ['--exclude', f] },
+             *pages.keys.flat_map { |key| ['--exclude', key] })
 
         index = File.join(dist, 'index.html')
         abort "Error: #{index} not found after build." unless File.exist?(index)
 
-        # index.html always revalidates
-        run!('aws', 's3', 'cp', index, "s3://#{bucket}/index.html",
-             '--cache-control', 'no-cache')
+        # HTML and crawler files (robots.txt, sitemap.xml, llms.txt) always revalidate
+        run!('aws', 's3', 'sync', dist_prefix, "s3://#{bucket}", '--delete',
+             '--cache-control', 'no-cache', '--exclude', '*',
+             *REVALIDATED_FILES.flat_map { |f| ['--include', f] })
+
+        upload_prerendered_pages(dist, bucket, pages)
+      end
+
+      # scripts/prerender.js writes dist/.belt-pages.json mapping each page's S3 key
+      # to its file ({ "about" => "about.html" }). CloudFront has no directory
+      # indexes, so /about must be an object named `about` served as text/html.
+      def prerendered_pages(dist)
+        manifest = File.join(dist, PAGES_MANIFEST)
+        return {} unless File.file?(manifest)
+
+        pages = JSON.parse(File.read(manifest))
+        pages.is_a?(Hash) ? pages : {}
+      rescue JSON::ParserError => e
+        warn "⚠️  Ignoring #{manifest}: #{e.message}"
+        {}
+      end
+
+      def upload_prerendered_pages(dist, bucket, pages)
+        return if pages.empty?
+
+        puts "🔎 Uploading #{pages.size} prerendered page(s)..."
+        pages.each do |key, file|
+          run!('aws', 's3', 'cp', File.join(dist, file), "s3://#{bucket}/#{key}",
+               '--content-type', 'text/html; charset=utf-8', '--cache-control', 'no-cache',
+               '--only-show-errors')
+        end
       end
 
       def invalidate_cloudfront

data/lib/belt/docs/deployment.md

@@ -7,13 +7,21 @@ Lambda packaging, and pre-deploy backups.
 ## Quick Deploy
 
 ```bash
-belt deploy <env>              # init → plan → apply (interactive)
-belt deploy prod --auto        # skip confirmation prompt
+belt deploy <env>              # init → plan → apply
+belt deploy prod               # prod prompts for confirmation
+belt deploy prod --auto        # skip prod's confirmation prompt (CI)
+belt deploy dev                # non-prod auto-approves — no prompt
+belt deploy dev --confirm      # force the prompt on a non-prod env
 belt deploy prod --skip-backup # skip pre-deploy backup
 belt deploy --backup-only      # create recovery point without deploying
 belt deploy dev --skip-migrations # don't run pending db/migrate migrations
 ```
 
+Non-prod environments auto-approve the Terraform plan by default — only `prod`
+(and `production`) prompt. Pass `--confirm` (alias `--no-auto`) to force the
+prompt anywhere; `--auto` still works everywhere and is what you want in CI for
+prod.
+
 ## First-Time Setup
 
 ```bash

data/lib/belt/docs/frontend.md

@@ -85,6 +85,41 @@ The default `frontend/` directory also accepts `.belt/frontend_env.yml` as a
 fallback. See the existing env-map behavior: only mapped keys are written into
 `.env`; missing terraform outputs warn and do not clobber local values.
 
+## SEO and AI answer engines
+
+Search crawlers and AI answer engines (ChatGPT, Claude, Perplexity, Google AI)
+mostly don't run JavaScript, so an SPA that ships an empty `<div id="root">` is
+invisible to them. React frontends from `belt generate frontend react` prerender
+their public pages at build time:
+
+```
+src/seo.js             # site name/description, public pages, private paths
+src/entry-server.jsx   # renders <App /> at a URL (build time only)
+scripts/prerender.js   # runs at the end of `npm run build`
+```
+
+For every entry in `seo.pages`, `npm run build` writes real HTML with the page's
+rendered content, `<title>`, meta description, canonical URL, Open Graph tags and
+JSON-LD. It also writes `robots.txt`, `sitemap.xml` (needs a site URL) and
+`llms.txt`. `belt deploy frontend` uploads each page to its extensionless S3 key
+(`/pricing` → `pricing`, served as `text/html`) and serves HTML and crawler files
+with `no-cache`.
+
+**When you add a public route, add it to `seo.pages`** with a specific title and a
+one- or two-sentence description that says plainly what the page is. Login-gated
+routes go in `privatePaths`. Components on public pages must render without
+`window`/`document`/`localStorage` — touch those in `useEffect`. A page that throws
+during prerender still gets its tags, but no content, and the build warns.
+
+Only environments in `seo.indexableEnvironments` (default `['prod']`) are
+indexable; every other environment and local builds ship `Disallow: /` and
+`noindex`, so dev and ephemeral environments stay out of search results.
+`belt deploy frontend` sets `BELT_ENV` and `VITE_SITE_URL` (the frontend URL) for
+the build; set `SEO_INDEXABLE=true|false` to override.
+
+After the first prod deploy, submit `https://<domain>/sitemap.xml` to Google
+Search Console and Bing Webmaster Tools.
+
 ## Infrastructure
 
 `belt setup frontend` (and `belt generate frontend`) writes S3 + CloudFront into

data/lib/belt/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.6.5'
+  VERSION = '0.6.7'
 
   # Ruby version new apps run on in Lambda. Rendered into the conveyor-belt
   # provider block (`ruby_version`) by `belt new` / `belt generate environment`.

data/lib/templates/frontend/react/index.html.erb

@@ -4,6 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title><%= @module_name %></title>
+    <meta name="description" content="<%= @module_name %>" />
   </head>
   <body>
     <div id="root"></div>

data/lib/templates/frontend/react/package.json.erb

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "vite build && vite build --ssr src/entry-server.jsx --outDir dist-ssr && node scripts/prerender.js",
     "preview": "vite preview"
   },
   "dependencies": {

data/lib/templates/frontend/react/scripts/prerender.js

@@ -0,0 +1,172 @@
+/**
+ * Post-build SEO/AEO step (runs as part of `npm run build`).
+ *
+ * Search and AI answer-engine crawlers mostly don't run JavaScript, so an SPA's
+ * empty <div id="root"> tells them nothing. Using src/seo.js, this writes into dist/:
+ *
+ *   index.html, <path>.html  — each page in seo.pages rendered to HTML (via
+ *                              dist-ssr/entry-server.js) with its own <title>,
+ *                              description, canonical URL, Open Graph tags and JSON-LD
+ *   robots.txt               — allows crawlers in indexable environments, `Disallow: /` elsewhere
+ *   sitemap.xml              — every public page (needs a site URL)
+ *   llms.txt                 — plain-text site summary for LLMs (https://llmstxt.org)
+ *   .belt-pages.json         — S3 key → file map; `belt deploy frontend` uploads each page
+ *                              to its extensionless key (/about → about.html) as text/html
+ *
+ * Environment:
+ *   VITE_SITE_URL   canonical origin (belt deploy injects the frontend URL)
+ *   BELT_ENV        environment being built (belt deploy injects it)
+ *   SEO_INDEXABLE   "true"/"false" to override seo.indexableEnvironments
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import seo from '../src/seo.js'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const DIST = join(ROOT, 'dist')
+const SSR_ENTRY = join(ROOT, 'dist-ssr', 'entry-server.js')
+
+const siteUrl = (process.env.VITE_SITE_URL || seo.siteUrl || '').replace(/\/+$/, '')
+const indexable = process.env.SEO_INDEXABLE
+  ? process.env.SEO_INDEXABLE === 'true'
+  : (seo.indexableEnvironments || ['prod']).includes(process.env.BELT_ENV)
+
+const normalize = (path) => `/${path.replace(/^\/+|\/+$/g, '')}`
+const privatePaths = (seo.privatePaths || []).map(normalize)
+const isPrivate = (path) => privatePaths.some((p) => path === p || path.startsWith(`${p}/`))
+const pages = (seo.pages || [])
+  .map((page) => ({ ...page, path: normalize(page.path) }))
+  .filter((page) => !isPrivate(page.path))
+
+const escapeHtml = (s) =>
+  String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+const absolute = (path) => `${siteUrl}${path === '/' ? '/' : path}`
+
+async function loadRenderer() {
+  if (!existsSync(SSR_ENTRY)) {
+    console.warn(`⚠️  ${SSR_ENTRY} not found — pages get SEO tags but no prerendered content`)
+    return null
+  }
+  try {
+    return (await import(pathToFileURL(SSR_ENTRY).href)).render
+  } catch (error) {
+    console.warn(`⚠️  Could not load the SSR bundle (${error.message}) — pages get SEO tags but no prerendered content`)
+    return null
+  }
+}
+
+function renderBody(render, path) {
+  if (!render) return ''
+  try {
+    return render(path)
+  } catch (error) {
+    // Usually a component touching window/document/localStorage during render.
+    // Move that into useEffect to get the content prerendered.
+    console.warn(`⚠️  Prerender failed for ${path} (${error.message}) — serving SEO tags only`)
+    return ''
+  }
+}
+
+function jsonLd(page) {
+  const data = page.jsonLd || {
+    '@context': 'https://schema.org',
+    '@type': page.path === '/' ? 'WebSite' : 'WebPage',
+    name: page.title,
+    description: page.description,
+    ...(siteUrl ? { url: absolute(page.path) } : {})
+  }
+  return JSON.stringify(data).replace(/</g, '\\u003c')
+}
+
+function headTags(page) {
+  const tags = []
+  if (siteUrl) tags.push(`<link rel="canonical" href="${absolute(page.path)}" />`)
+  if (!indexable) tags.push('<meta name="robots" content="noindex, nofollow" />')
+  tags.push(
+    `<meta property="og:type" content="website" />`,
+    `<meta property="og:site_name" content="${escapeHtml(seo.siteName)}" />`,
+    `<meta property="og:title" content="${escapeHtml(page.title)}" />`,
+    `<meta property="og:description" content="${escapeHtml(page.description)}" />`
+  )
+  if (siteUrl) tags.push(`<meta property="og:url" content="${absolute(page.path)}" />`)
+  if (page.image) tags.push(`<meta property="og:image" content="${escapeHtml(page.image)}" />`)
+  tags.push(
+    `<meta name="twitter:card" content="${page.image ? 'summary_large_image' : 'summary'}" />`,
+    '<link rel="alternate" type="text/plain" href="/llms.txt" title="llms.txt" />',
+    `<script type="application/ld+json">${jsonLd(page)}</script>`
+  )
+  return tags.map((tag) => `    ${tag}\n`).join('')
+}
+
+function pageHtml(template, page, body) {
+  return template
+    .replace(/<title>[\s\S]*?<\/title>/, () => `<title>${escapeHtml(page.title)}</title>`)
+    .replace(/\s*<meta name="description"[^>]*>/, '')
+    .replace(
+      '</head>',
+      () => `  <meta name="description" content="${escapeHtml(page.description)}" />\n${headTags(page)}  </head>`
+    )
+    .replace(
+      '<div id="root"></div>',
+      // data-prerendered tells main.jsx to hydrate rather than render fresh
+      () => (body ? `<div id="root" data-prerendered="${escapeHtml(page.path)}">${body}</div>` : '<div id="root"></div>')
+    )
+}
+
+function robotsTxt() {
+  if (!indexable) return 'User-agent: *\nDisallow: /\n'
+  const lines = ['User-agent: *', 'Allow: /', ...privatePaths.map((p) => `Disallow: ${p}`)]
+  if (siteUrl) lines.push('', `Sitemap: ${siteUrl}/sitemap.xml`)
+  return `${lines.join('\n')}\n`
+}
+
+function sitemapXml() {
+  const urls = pages.map((page) => `  <url><loc>${escapeHtml(absolute(page.path))}</loc></url>`).join('\n')
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`
+}
+
+function llmsTxt() {
+  const lines = [`# ${seo.siteName}`, '', `> ${seo.description}`, '', '## Pages', '']
+  for (const page of pages) lines.push(`- [${page.title}](${absolute(page.path)}): ${page.description}`)
+  return `${lines.join('\n')}\n`
+}
+
+async function main() {
+  const indexFile = join(DIST, 'index.html')
+  if (!existsSync(indexFile)) {
+    console.error('dist/index.html not found — run `vite build` first')
+    process.exit(1)
+  }
+  if (!pages.some((page) => page.path === '/')) pages.unshift({ path: '/', title: seo.siteName })
+  for (const page of pages) {
+    page.title ||= seo.siteName
+    page.description ||= seo.description
+  }
+
+  const template = readFileSync(indexFile, 'utf-8')
+  const render = await loadRenderer()
+  const manifest = {}
+
+  for (const page of pages) {
+    const html = pageHtml(template, page, renderBody(render, page.path))
+    const key = page.path.slice(1)
+    const file = key ? `${key}.html` : 'index.html'
+    mkdirSync(dirname(join(DIST, file)), { recursive: true })
+    writeFileSync(join(DIST, file), html)
+    if (key) manifest[key] = file
+  }
+
+  writeFileSync(join(DIST, '.belt-pages.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  writeFileSync(join(DIST, 'robots.txt'), robotsTxt())
+  writeFileSync(join(DIST, 'llms.txt'), llmsTxt())
+  if (siteUrl) writeFileSync(join(DIST, 'sitemap.xml'), sitemapXml())
+
+  if (!siteUrl) console.warn('⚠️  No site URL (VITE_SITE_URL or seo.siteUrl) — skipped canonical URLs and sitemap.xml')
+  console.log(
+    `SEO: prerendered ${pages.length} page(s), ${indexable ? 'indexable' : 'noindex'}` +
+      `${process.env.BELT_ENV ? ` (${process.env.BELT_ENV})` : ''}`
+  )
+}
+
+main()

data/lib/templates/frontend/react/src/App.jsx

@@ -1,13 +1,12 @@
-import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import { Routes, Route } from 'react-router-dom'
 import Home from './pages/Home'
 
+// The router lives in main.jsx (browser) and entry-server.jsx (prerender).
 function App() {
   return (
-    <BrowserRouter>
-      <Routes>
-        <Route path="/" element={<Home />} />
-      </Routes>
-    </BrowserRouter>
+    <Routes>
+      <Route path="/" element={<Home />} />
+    </Routes>
   )
 }
 

data/lib/templates/frontend/react/src/entry-server.jsx

@@ -0,0 +1,12 @@
+import { renderToString } from 'react-dom/server'
+import { StaticRouter } from 'react-router-dom/server'
+import App from './App'
+
+// Build-time render used by scripts/prerender.js — not shipped to the browser.
+export function render(url) {
+  return renderToString(
+    <StaticRouter location={url}>
+      <App />
+    </StaticRouter>
+  )
+}

data/lib/templates/frontend/react/src/main.jsx

@@ -1,10 +1,23 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
 import App from './App'
 import './index.css'
 
-ReactDOM.createRoot(document.getElementById('root')).render(
+const root = document.getElementById('root')
+const app = (
   <React.StrictMode>
-    <App />
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
   </React.StrictMode>
 )
+
+// Pages prerendered at build time hydrate. Anything else (including the SPA
+// fallback serving index.html for a deep link) renders fresh.
+const normalize = (path) => path.replace(/\/+$/, '') || '/'
+if (root.dataset.prerendered && normalize(root.dataset.prerendered) === normalize(window.location.pathname)) {
+  ReactDOM.hydrateRoot(root, app)
+} else {
+  ReactDOM.createRoot(root).render(app)
+}

data/lib/templates/frontend/react/src/pages/Home.jsx.erb

@@ -211,7 +211,7 @@ function Home() {
   if (loading) {
     return (
       <div className="belt-welcome">
-        <style>{welcomeStyles}</style>
+        <style dangerouslySetInnerHTML={{ __html: welcomeStyles }} />
         <main className="status-main">
           <p className="muted">Connecting to API…</p>
         </main>
@@ -222,7 +222,7 @@ function Home() {
   if (error) {
     return (
       <div className="belt-welcome">
-        <style>{welcomeStyles}</style>
+        <style dangerouslySetInnerHTML={{ __html: welcomeStyles }} />
         <main className="status-main">
           <h1><%= @module_name %></h1>
           <p className="error">Could not load welcome data from the API.</p>
@@ -242,7 +242,7 @@ function Home() {
 
   return (
     <div className="belt-welcome">
-      <style>{welcomeStyles}</style>
+      <style dangerouslySetInnerHTML={{ __html: welcomeStyles }} />
 
       <div className="hero">
         {welcome.background_image ? (

data/lib/templates/frontend/react/src/seo.js.erb

@@ -0,0 +1,27 @@
+// SEO/AEO config — what search engines and AI answer engines (Google, Bing,
+// ChatGPT, Claude, Perplexity) see. Most of those crawlers don't run JavaScript,
+// so `npm run build` prerenders every page listed here to real HTML.
+//
+// For each page the build writes static HTML with its own <title>, description,
+// canonical URL, Open Graph tags and JSON-LD, plus robots.txt, sitemap.xml and
+// llms.txt for the whole site (scripts/prerender.js).
+//
+// Rules of thumb:
+//   - Every public route gets an entry in `pages` with a specific title and a
+//     one- or two-sentence description that says plainly what the page is.
+//   - Login-gated or app-only routes go in `privatePaths` (disallowed in robots.txt).
+//   - Only `indexableEnvironments` are indexable. Every other environment, and
+//     local builds, ship `Disallow: /` and <meta name="robots" content="noindex">
+//     so dev and ephemeral environments never end up in search results.
+export default {
+  siteName: '<%= @module_name %>',
+  description: '<%= @module_name %> — say what this app does and who it is for in one or two plain sentences.',
+  // Canonical production URL, e.g. 'https://example.com'. `belt deploy frontend`
+  // injects VITE_SITE_URL from terraform, which wins when set.
+  siteUrl: '',
+  indexableEnvironments: ['prod'],
+  pages: [
+    { path: '/', title: '<%= @module_name %>', description: '' }
+  ],
+  privatePaths: ['/login', '/signup', '/confirm']
+}

data/lib/templates/new_app/AGENTS.md.erb

@@ -259,6 +259,23 @@ belt setup tables <env>           # Generate DynamoDB table resources
 belt deploy <env>                 # Deploy everything (init → plan → apply)
 ```
 
+## SEO / AEO (public pages)
+
+If the app has a React frontend, its public pages are prerendered for search and AI
+answer engines (`belt explain frontend`). When you add or change a public page:
+
+- Add it to `frontend/src/seo.js` → `pages` with a specific `title` and a one- or
+  two-sentence `description` that names what the page is and who it's for.
+- Put login-gated routes in `privatePaths` (they're disallowed in `robots.txt`).
+- Keep the page's content in the rendered markup — no `window`/`document`/
+  `localStorage` during render (use `useEffect`), and no content that only appears
+  after an API call if crawlers need to see it.
+- Use one `<h1>` per page and real links (`<Link>`/`<a href>`), not click handlers.
+- Check `npm run build` output: `SEO: prerendered N page(s)` with no warnings, and
+  `dist/<page>.html` contains the content.
+
+Only `prod` is indexable; other environments ship `noindex`.
+
 ## Key Differences from Rails
 
 | Rails | Belt |

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.6.5
+  version: 0.6.7
 platform: ruby
 authors:
 - Stowzilla
@@ -213,11 +213,14 @@ files:
 - lib/templates/frontend/react/env.yml.example
 - lib/templates/frontend/react/index.html.erb
 - lib/templates/frontend/react/package.json.erb
+- lib/templates/frontend/react/scripts/prerender.js
 - lib/templates/frontend/react/src/App.jsx
+- lib/templates/frontend/react/src/entry-server.jsx
 - lib/templates/frontend/react/src/index.css
 - lib/templates/frontend/react/src/lib/apiClient.js.erb
 - lib/templates/frontend/react/src/main.jsx
 - lib/templates/frontend/react/src/pages/Home.jsx.erb
+- lib/templates/frontend/react/src/seo.js.erb
 - lib/templates/frontend/react/vite.config.js
 - lib/templates/frontend_infra/frontend.tf.erb
 - lib/templates/generate/auth/cognito.tf.erb