Skip to content

docs(react): warn that _gt files must be generated before first run#392

Closed
JoshKappler wants to merge 1 commit into
mainfrom
docs-missing-gt-warnings
Closed

docs(react): warn that _gt files must be generated before first run#392
JoshKappler wants to merge 1 commit into
mainfrom
docs-missing-gt-warnings

Conversation

@JoshKappler

Copy link
Copy Markdown
Contributor

What this fixes

Following the Next.js App Router quickstart step by step and then running npm run dev for the first time returns HTTP 500. The loadTranslations file added in step 4 imports ../public/_gt/${locale}.json, but nothing on the page has created those files yet. npx gt generate is only mentioned much later, inside a collapsed accordion. A first-time reader hits the failure before they ever see the command.

The same root cause affects three more React quickstarts, with the symptom verified per page:

  • Next.js App Router (nextjs-quickstart.mdx): the dynamic import has no fallback, so the first npm run dev fails to compile and the page returns HTTP 500. Creating empty {} stub files flips it from 500 to 200 with no other change.
  • TanStack Start (tanstack-start-quickstart.mdx): the root route loader imports src/_gt/${locale}.json with no try/catch, and the files are generated only in a later step. The default locale still renders, but selecting a target locale in the language switcher returns HTTP 500 until the files exist.
  • React Native (react-native-quickstart.mdx): the loader uses static require('./src/_gt/es.json') calls, and Metro refuses to bundle the app at all until those files exist.
  • Next.js Pages Router (nextjs-pages-router-quickstart.mdx): same root cause, softer symptom. The loader already wraps the import in try/catch, so the app still runs with untranslated content, but the bundler warns about the missing public/_gt directory.

All four failures reproduced twice in clean sandboxes and are present on the current SHA. This is a fix for verified first-run failures, not a stylistic preference.

These quickstarts were created in the #354 docs refactor merged July 16 and had not been walked end to end yet. The docs bots do mechanical sync and grammar passes (open PR #390 is a grammar-only pass on one of these same files), so a first-run 500 like this survives them.

The change

Four callouts, one per page, inserted at the point where the failing code is introduced. Each one states that the translation files do not exist yet, how to create them (npx gt generate with no key, or npx gt translate with credentials, plus the empty {} stub option on the App Router page where it was verified), and the exact symptom for that page.

Three pages use a Warning callout because the app is broken until the files exist. The Pages Router page uses a Note instead: its loader degrades gracefully, so the honest symptom there is a build warning and untranslated content, not breakage. If you'd rather it match the others as a Warning, say so and I'll change it.

These are pure insertions. No steps were reordered, no accordion was moved, and no behavior or API claim was changed.

Verification

  • npm run validate:unsafe-html: pass (418 MDX files).
  • javascript: URL check: clean.
  • npx tsx validate-links.ts: pass, all links valid.
  • pnpm build:content (full Next.js production build): pass, 434 pages generated, TypeScript clean, all MDX compiled.
  • Merge-checked against the open PRs touching these files (381, 383, 390, and 372) with real 3-way merges: all four edited files merge cleanly with every one of them.

If this was intentional

If the intent is that readers always reach the generate/translate step before they run the app, I'm happy to rescope this to reordering the steps instead of adding callouts. The callouts felt like the smaller, lower-risk change, but the reordering is a fair alternative if you prefer it.

@JoshKappler

Copy link
Copy Markdown
Contributor Author

Folding this into #391 so the quickstart fixes are one review instead of four. The commit is cherry-picked there unchanged and the write-up moved into that PR's body.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant