Client bundle lists collections in load-completion order, so identical builds get different chunk hashes
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 89/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- bun, node.js, nuxt, typescript, vite
- Domain
- build-system, performance
Research direction
Read src/core/bundle.ts around resolveBundleIcons and test/bundle.test.ts; the issue includes a reproduction and a proposed deterministic ordering. Start by running the provided test scenario and checking the existing collection order. Done means collections resolve in a stable code point order and the regression test passes.
Written by the indexing model from the issue text.
Description
Environment
@nuxt/icon2.6.3 (the same code is onmainat 28c9943)nuxt4.6.4,vite8.3.8,@iconify/utils3.1.7- Linux x64, Bun 1.4.4 (
bun --bun nuxt build) and Node 22.23.4
Reproduction
nuxt.config.ts, with @iconify-json/lucide, @iconify-json/ph, @iconify-json/cib and @iconify-json/simple-icons installed:
export default defineNuxtConfig({
modules: ['@nuxt/icon'],
icon: {
clientBundle: {
icons: [
'lucide:arrow-down', 'lucide:x', 'lucide:check',
'ph:gear', 'ph:house', 'ph:user',
'cib:ideal', 'cib:bancontact',
'simple-icons:github', 'simple-icons:americanexpress',
],
},
},
compatibilityDate: '2026-11-01',
})
The order is easiest to see with the exported resolver. order.mjs in the project root:
import { resolveBundleIcons } from '@nuxt/icon/utils'
const { collections } = await resolveBundleIcons({
icons: [
'lucide:arrow-down', 'lucide:x', 'lucide:check',
'ph:gear', 'ph:house', 'ph:user',
'cib:ideal', 'cib:bancontact',
'simple-icons:github', 'simple-icons:americanexpress',
],
})
console.log(collections.map(c => c.prefix).join(','))
Each run needs its own process, because the collection loader caches within one:
seq 64 | xargs -P 8 -I{} bun order.mjs | sort | uniq -c
44 lucide,cib,ph,simple-icons
18 lucide,cib,simple-icons,ph
1 cib,lucide,simple-icons,ph
1 cib,lucide,ph,simple-icons
node order.mjs gives three orders as well (61 / 2 / 1 out of 64), less often.
Effect on builds
The resolved collections are serialized as they are into nuxt-icon-client-bundle.mjs. When their order changes, the chunk that holds the client bundle changes, though its only difference is the order of the collections inside JSON.parse(...). Every chunk that imports it then gets a new hash as well.
I built three identical copies of the app above at the same time, as on a busy CI runner, round after round with bun --bun nuxt build:
| Builds | Collection orders | Distinct sets of _nuxt/*.js names |
|
|---|---|---|---|
| 2.6.3 | 36 | 3 | 3 |
| 2.6.3 with the fix below | 36 | 1 | 1 |
The two most common orders differ in 8 of this app's 13 chunk names. Six sequential builds on an idle machine all matched, which makes the problem easy to miss.
In a larger app (115 chunks), two builds whose only difference was a stylesheet that no script references renamed 51 chunks. The only root of those renames was the chunk holding the client bundle. Returning visitors download those chunks again after each deploy, even though their code is unchanged.
Expected
Identical inputs produce identical chunk names.
Cause
resolveBundleIcons loads collections inside Promise.all. addIcon adds a collection to the collections map when its first icon resolves, so the map holds the collections in the order their files finished loading:
- https://github.com/nuxt/icon/blob/28c9943893a4f5609b2ec79afe22768170df9fae/src/core/bundle.ts#L115-L123
- https://github.com/nuxt/icon/blob/28c9943893a4f5609b2ec79afe22768170df9fae/src/core/bundle.ts#L145-L170
#446 (for #445) sorted the icons inside each collection, but the collections are still returned in insertion order:
With scan: true, the order in which the loads start varies too, because scanned files are read in parallel. Both the module's client bundle (src/context.ts) and the standalone Vite plugin (src/vite.ts) use this function.
Suggested fix
return {
- collections: [...collections.values()],
+ collections: [...collections.values()].sort((a, b) => a.prefix < b.prefix ? -1 : a.prefix > b.prefix ? 1 : 0),
count,
The test below, for test/bundle.test.ts, fails today: custom collections resolve immediately, so without the sort they come back in request order (['zeta', 'alpha']).
it('returns collections in a stable order', async () => {
const collection = (prefix: string) => ({
prefix,
icons: { foo: { body: '<path d="M0 0h24v24H0z"/>' } },
width: 24,
height: 24,
})
const result = await resolveBundleIcons({
icons: ['zeta:foo', 'alpha:foo'],
customCollections: [collection('zeta'), collection('alpha')],
resolvePaths: [root],
})
expect(result.collections.map(c => c.prefix)).toEqual(['alpha', 'zeta'])
})
The comparison is by code point on purpose. Under Node, localeCompare() follows the build machine's locale: LANG=et_EE.UTF-8 sorts zondicons before tabler, and LANG=da_DK.UTF-8 sorts names starting with aa last. The icon-name sort from #446 uses localeCompare(), so it can also differ between machines.
- Dominant language
- TypeScript
- Stars
- 1.2k
- Forks
- 103
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 32
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from nuxt/icon
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
nuxt/icon#585 · 1 comment · 1 reaction ·
Maintainers usually reply within 1 day
-
Difficulty 4/5 3-5 days Newbie friendliness 45/100
Maintainers usually reply within 1 day
-
Difficulty 4/5 3-5 days Newbie friendliness 38/100
nuxt/icon#492 · 1 comment · 2 reactions ·
Maintainers usually reply within 1 day
-
Difficulty 3/5 1-2 days Newbie friendliness 35/100
Maintainers usually reply within 1 day
-
Difficulty 3/5 1-2 days Newbie friendliness 30/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
liberation-data/drivine#826 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
zhitongblog/solomd#623 ·
Maintainers usually reply within 1 day
-
aufwand: klein documentation Einsteiger-Familie freigegeben Haushalts-Admin
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
enhancement frontend
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
openwallet-foundation/eudiplo#1600 ·
-
docs(website): add a GitLab CI/CD button next to the GitHub Action button on the homepagePossibly taken @shryssssss-maker claimed this today. Opendocumentation enhancement first-timers-only good first issue
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
OWASP/cve-lite-cli#1739 · 2 comments ·
Maintainers usually reply within 2 days