Assets out of sync

Use this runbook when a feature does nothing, when the console shows a 404 for a file in assets/, or when a change to src/ has no visible effect on the storefront.

Nearly every case has the same root cause. snippets/vite-tag.liquid and the files in assets/ are generated and committed, and one of them is out of step with the other.

Diagnose

1. Confirm which theme you are on

npm run list

Note the theme ID and role. A preview theme and the live theme carry different builds.

2. Look at the network panel

Open the page, filter the network panel to JS and CSS, and look for a 404.

A 404 on a file with an eight-character hash in its name, such as mini-cart-B1x9dQ2f.js, means Liquid is asking for a bundle that is not in assets/ on this theme.

A request to localhost:5173 or 127.0.0.1:5173 means snippets/vite-tag.liquid was committed while it pointed at the Vite dev server.

No request at all for the bundle means the section that renders it never rendered on this page. Skip to step 5.

3. Check what vite-tag.liquid points at

grep -n "5173\|localhost" snippets/vite-tag.liquid | head

Any output here is the problem. Go to Repair, case A.

Then check the specific entrypoint:

grep -A 3 "entrypoints/mini-cart/elements/mini-cart.ts" snippets/vite-tag.liquid

Note the hashed filename it names.

4. Check that file exists

ls assets/ | grep mini-cart

If the filename from step 3 is missing, the snippet and the assets were built at different times. Go to Repair, case B.

5. Check that a section renders the entrypoint

grep -rn "vite-tag' with '<your-entrypoint-path>'" sections/ snippets/ layout/ blocks/

No result means nothing loads that bundle. Bundles load only where a Liquid file renders them, so correct code can still never reach the page. Go to Repair, case C.

6. Check the theme on the store matches the repository

git status --short

Uncommitted changes in assets/ or snippets/vite-tag.liquid mean your local build has not been pushed.

Repair

Case A: vite-tag.liquid points at the dev server

Stop every dev process, rebuild, and commit.

npm run build
git add snippets/vite-tag.liquid assets
git commit -m "Rebuild theme assets"

Confirm the fix before pushing:

grep -c "5173" snippets/vite-tag.liquid

It should print 0.

Case B: the snippet and assets disagree

Rebuild both together. The same command writes both, so one build fixes them.

npm run build
git status --short assets snippets/vite-tag.liquid

Commit everything the build touched. Committing the snippet without the assets, or the other way round, recreates this exact problem for the next person.

Case C: nothing renders the entrypoint

Add the render to the section that needs it, at the top of the Liquid file:

{%- render 'vite-tag' with 'homepage-redesign/components/my-feature.ts' -%}

Then rebuild and commit.

Case D: the store has an older build

Push the current build to the theme you are testing. Use a preview theme rather than pushing to the live theme directly. See Deployment.

Verify

1. Hard reload the page in a private window.
2. Confirm the network panel shows a 200 for each bundle the page needs.
3. Confirm no request goes to port 5173.
4. Confirm the behaviour works.

Prevent

Run npm run build before committing rather than relying on the pre-commit hook, so you can review the output before it is committed.

Check snippets/vite-tag.liquid in every code review that touches src/. A pull request that changes an entrypoint and does not change that snippet or assets/ is almost certainly missing a build.

Never hand-edit a file in assets/ that has a hash in its name. The next build deletes it.

Background is in How the build works.