LTRAC-1343: docs - Settle whether scaffolded projects commit GraphQL artifacts - #3195
Merged
Merged
Conversation
🦋 Changeset detectedLatest commit: ed62f8a The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Bundle Size ReportComparing against baseline from No bundle size changes detected. |
chanceaclark
approved these changes
Aug 26, 2026
jorgemoya
marked this pull request as ready for review
August 26, 2026 20:36
chanceaclark
approved these changes
Aug 26, 2026
…artifacts `npm run generate` writes `bigcommerce.graphql` and `bigcommerce-graphql.d.ts` to the project root, and `catalyst create` makes its initial commit before anything runs `generate`. Both files therefore appear as untracked the first time a merchant runs `pnpm run dev`, with nothing in the project saying what they are, whether they are read at runtime, or whether the intent was to commit or ignore them. Document in the scaffolded project's README that both files should be committed, name `generate` as the command that produces them, and describe local versus build-time regeneration. Record the same decision in `core/.gitignore`, where their absence otherwise looks like an oversight. Explain in CONTRIBUTING.md why the monorepo does the opposite: contributors work against unreleased Storefront API schemas on their own test stores, so a committed schema here would generate diffs belonging to no change and conflict between `canary` and the `integrations/*` branches. CI regenerates from store credentials before it lints and typechecks. Refs LTRAC-1343 Co-Authored-By: Claude <noreply@anthropic.com>
jorgemoya
force-pushed
the
jorgemoya/ltrac-1343-graphql-artefacts
branch
2 times, most recently
from
August 26, 2026 20:37
5912171 to
ed62f8a
Compare
jorgemoya
enabled auto-merge
August 26, 2026 20:38
Contributor
Unlighthouse Performance Comparison — VercelComparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores. Summary ScoreAggregate score across all categories as reported by Unlighthouse.
Category Scores
Core Web Vitals
|
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
2 participants
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.
Linear: LTRAC-1343
What/Why?
A merchant reported
bigcommerce.graphqlandbigcommerce-graphql.d.tsshowing up untracked right after setup, and asked the reasonable question: commit them, or gitignore them? Nothing in a scaffolded project answers that.Documentation only — no behaviour change.
Two details that make the report legitimate rather than user error:
core/directory, so its.gitignoreiscore/.gitignore, which doesn't list either file. The monorepo's root.gitignoredoes. Merchants are supposed to commit them; contributors aren't. From inside a scaffolded project the omission is indistinguishable from an oversight, which is why this PR records the decision incore/.gitignoreitself and warns inCONTRIBUTING.mdagainst propagating the root entries down into it.pnpm run dev, not aftercreate.initGitRepomakes the initial commit before anything runsgenerate, so the files are always born untracked. The README now covers that moment explicitly with thegit addto run.The substantive argument for committing (the decision the ticket asked me to document) is that
client/graphql.tsimports~/bigcommerce-graphql, solintandtypecheckcan't resolve without the.d.ts. Committing it means a merchant's CI can typecheck a PR with no store credentials — which is exactly the problembasic.ymlsolves the other way in this repo, by runningpnpm run -r generatebefore lint and typecheck. Neither file is read at request time;build/deployregenerate, so the committed copy is never what ships.Included a
@bigcommerce/catalyst-corepatch changeset so the guidance reaches existing projects through the changelog, not just new ones.Not addressed here
Two adjacent problems I found and left alone as out of scope, both worth their own tickets:
graphql.config.jsonpoints atcore/schema.graphql, which doesn't exist anywhere in the repo.core/README.md's footer links to/docs, so that link is broken in every scaffolded project.Also worth considering: the CLI's post-create "Next steps" output is where the merchant actually hits this, so a line there would catch people who never open the README. The ticket scoped this to docs, so the CLI is untouched.
Testing
npx prettier --check core/README.mdpasses.CONTRIBUTING.mdhas one pre-existing prettier warning atcanary(a list-continuation blank line in the release section) that I deliberately left in place rather than reformatting an unrelated part of the file; the section I added is prettier-clean.Worth a reviewer's eye on the accuracy of the claims rather than the prose:
core/scripts/generate.cjswrites both files and requiresBIGCOMMERCE_STORE_HASH+BIGCOMMERCE_STOREFRONT_TOKEN(channel ID optional), a subset ofREQUIRED_BUILD_ENV_VARS.git check-ignore -v core/bigcommerce.graphqlin the monorepo resolves to the root.gitignore— confirming the comment lands in the file that actually does the ignoring.Migration
None. No files moved, no breaking changes.
🤖 Generated with Claude Code