belt 0.6.4 → 0.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fcb629702530cd06ffb9af298dcd259c4fc0503107ef19ab58a58da476617b4
-  data.tar.gz: 167a12259478e5079620446f76dad474cde1d456f08b328663fe11f82860fa66
+  metadata.gz: dd4b86a1b7dc7acf4f88189a24b5d39c5cfcf71f512aafb5f04fb0af6d558a65
+  data.tar.gz: cdc8752352bca6b2ff3cce8a9abcf249c6975c0949d3a95b745be7fc2096544c
 SHA512:
-  metadata.gz: bb37dd0fe9e0cd392a0824d14b0ab4c51c5d002b36240fc7795ad11ce2313dd0014bea535c020fab6e4ec8988c7cf4d5a90992e2f8cfcdbcea35bc780586592f
-  data.tar.gz: d8d7423e5b3cd0c3d1598ff7b9e82446c9de4705b68313ade0ee0479ec26a87b5d4e3acd23a52b664ec2f50fd37e66cb046e1383f18bbf696cd01a13d24b140e
+  metadata.gz: 380937f0579d856a0f34407d5d1496306d5c9be64fb192d409e0bb78d2f6faea1d2016ae7db773312d92ff3f71876681b8e0d0384f2fc9127abd7eca386f5fbc
+  data.tar.gz: 927a7c107926e787be5fe8ade9a0df86429b75ece20468176d4afa8de6ef15ccd10b3d99471c3cc52f3f7870dc6e5c18486a1578d0c6a8a58565a0d06c93023d

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 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
+
+- **Per-route throttling in `routes.rb`.** Any route or resource accepts
+  `throttle: { rate: 2, burst: 5 }` (requests/second + burst). `belt routes -f json` emits it
+  as `throttle` on the route and conveyor-belt 0.0.20+ applies it as API Gateway stage method
+  settings, winning over the Lambda's `throttle:` in `config/lambda/<fn>.yml`. Malformed values
+  raise at load time. (Fizzy #1756)
+
 ## 0.6.4
 
 ### Added

data/README.md

@@ -209,6 +209,15 @@ end
 
 **Key point:** `namespace` and `scope` are purely organizational — they affect URL paths and controller module resolution but never change which Lambda handles the request. Use `function` when you need routes to go to a different Lambda.
 
+**Per-route throttling:** any route or resource accepts `throttle: { rate:, burst: }` (steady-state requests per second plus the burst the token bucket absorbs). `belt routes -f json` emits it and the conveyor-belt provider (0.0.20+) applies it as API Gateway stage method settings. A route's `throttle` wins over the serving Lambda's `throttle:` in `config/lambda/<fn>.yml`, which in turn wins over the provider's stage-level `throttle` block.
+
+```ruby
+gateway :api, auth: :none do
+  post '/connect/chat', to: 'chat#create', throttle: { rate: 2, burst: 5 }
+  resources :leads, only: [:create], throttle: { rate: 1, burst: 3 }
+end
+```
+
 ### Nested Resource DSL
 
 Inside a `resources` block, you can use Rails-like `member`, `collection`, `scope`, and singular `resource` for DRYer route definitions:

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/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/cli/routes_command.rb

@@ -165,6 +165,7 @@ module Belt
         }
         rc = route.response_context.to_s
         hash[:response_context] = rc unless rc.empty?
+        hash[:throttle] = route.throttle if route.throttle
         hash
       end
 

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/route_dsl.rb

@@ -9,7 +9,7 @@ module Belt
 
   class Route
     attr_reader :method, :path, :auth, :lambda, :cors, :tables, :route_type,
-                :controller, :action, :request_model, :response_model, :response_context
+                :controller, :action, :request_model, :response_model, :response_context, :throttle
 
     def initialize(method, path, options = {})
       @method = method.to_s.upcase
@@ -17,6 +17,7 @@ module Belt
       @auth = options[:auth]
       @lambda = options[:lambda]
       @cors = options.fetch(:cors, true)
+      @throttle = self.class.normalize_throttle(options[:throttle])
       @tables = options[:tables] || []
       @route_type = options[:route_type] || :action
       @controller = options[:controller]
@@ -26,6 +27,31 @@ module Belt
       @response_context = options[:response_context]&.to_s
     end
 
+    # Per-route API Gateway limit: `throttle: { rate: 2, burst: 5 }` (requests per
+    # second, token bucket). Emitted by `belt routes -f json` and applied by the
+    # conveyor-belt provider (0.0.20+) as stage method settings; it wins over the
+    # Lambda's `throttle:` in config/lambda/<fn>.yml. Returns nil when unset.
+    def self.normalize_throttle(raw)
+      return nil if raw.nil?
+
+      unless raw.is_a?(Hash)
+        raise ArgumentError, "throttle must be a Hash like { rate: 2, burst: 5 } (got #{raw.inspect})"
+      end
+
+      rate = raw[:rate] || raw['rate']
+      burst = raw[:burst] || raw['burst']
+      raise ArgumentError, 'throttle needs rate (requests/second) and burst' if rate.nil? || burst.nil?
+
+      unless rate.is_a?(Numeric) && rate.positive?
+        raise ArgumentError, "throttle rate must be a number > 0 (got #{rate.inspect})"
+      end
+      unless burst.is_a?(Integer) && burst.positive?
+        raise ArgumentError, "throttle burst must be an integer > 0 (got #{burst.inspect})"
+      end
+
+      { rate: rate, burst: burst }
+    end
+
     def resource?
       @route_type == :resource || @route_type == :resources
     end
@@ -494,7 +520,8 @@ module Belt
         action: action,
         request_model: options[:request_model],
         response_model: options[:response_model],
-        response_context: options[:response_context]
+        response_context: options[:response_context],
+        throttle: options[:throttle]
       }
 
       @routes << Belt::Route.new(method, path, route_options)

data/lib/belt/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.6.4'
+  VERSION = '0.6.6'
 
   # 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.4
+  version: 0.6.6
 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