docs(react): warn that _gt files must be generated before first run#392
Closed
JoshKappler wants to merge 1 commit into
Closed
docs(react): warn that _gt files must be generated before first run#392JoshKappler wants to merge 1 commit into
JoshKappler wants to merge 1 commit into
Conversation
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this fixes
Following the Next.js App Router quickstart step by step and then running
npm run devfor the first time returns HTTP 500. TheloadTranslationsfile added in step 4 imports../public/_gt/${locale}.json, but nothing on the page has created those files yet.npx gt generateis 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:
nextjs-quickstart.mdx): the dynamic import has no fallback, so the firstnpm run devfails to compile and the page returns HTTP 500. Creating empty{}stub files flips it from 500 to 200 with no other change.tanstack-start-quickstart.mdx): the root route loader importssrc/_gt/${locale}.jsonwith 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-quickstart.mdx): the loader uses staticrequire('./src/_gt/es.json')calls, and Metro refuses to bundle the app at all until those files exist.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 missingpublic/_gtdirectory.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 generatewith no key, ornpx gt translatewith 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.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.