Client bundle lists collections in load-completion order, so identical builds get different chunk hashes

Open Beginner friendly
#582 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@lafllamme is already working on this.

Since Nov 17, 2026.

  • #583 by @lafllamme — open

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

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/icon 2.6.3 (the same code is on main at 28c9943)
  • nuxt 4.6.4, vite 8.3.8, @iconify/utils 3.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:

#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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nuxt/icon

All issues in nuxt/icon

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.