Sorted remotes for deterministic builds

[andrebaerlocher]

Hiya, first time potentially contributing to such a huge project, so I'd rather ask instead of imposing weird ideas, opening a PR, etc.

The reason is, I've currently Ko for SvelteKit in the works, i.e. an image builder. And, in order to make it deterministic, the remotes would need to be sorted.

Is there a need or want for such a feature (or tool)? There seems to be some want for deterministic behaviour and builds according to some discussions.

The PR would be really small, one addition to packages/kit/src/core/generate_manifest/index.js:

const sorted_remotes = [...remotes].sort((a, b) =>
	a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0
);

Then replace remotes in

${remotes.map((remote) => `'${remote.hash}': ${loader(join_relative(relative_path, `chunks/remote-${remote.hash}.js`))}`).join(',\n')}

with sorted_remotes

Plus, three tests for packages/kit/src/core/generate_manifest/index.spec.js to verify/ascertain/make sure and changeset.

[skyzhao1223]

Yes — this is a real bug, your one-liner fixes it, and there is direct precedent for exactly this kind of change being merged. I reproduced the non-determinism empirically: six consecutive vite build runs with byte-identical sources produced six different remotes orderings in .svelte-kit/output/server/manifest.js, and applying your exact patch made the whole manifest byte-identical across runs. One caveat up front, so you can scope the PR (and your Ko tool) honestly: sorting remotes is necessary but not sufficient for a byte-reproducible build — a few other inputs to the same file have the same class of problem, and default version.name rotates one output file per build.

Why the order is non-deterministic (source trace, master @ 2752bd8)

• remotes is built in packages/kit/src/exports/vite/plugins/remote.js: a plain array (line 35, let remotes = []) that each *.remote.js module is pushed onto from inside the transform hook (lines 104–111), with hash = djb2 of the posixified path relative to project root, base-36 (packages/kit/src/utils/hash.js).
• So the array order is the order in which Rolldown finishes transforming the remote modules during the SSR build. Rolldown transforms in parallel; nothing sorts the result, so the order can vary run-to-run on the same machine (demonstrated below).
• packages/kit/src/core/generate_manifest/index.js:118 serialises the array straight into the manifest text, so array order becomes file bytes. The same line exists in published 2.70.3, so this affects current stable as well as 3.0.0-next.
• Sorting there is functionally neutral: every consumer either looks up by key or iterates the whole object — packages/kit/src/runtime/server/remote-functions.js:171,544 (remotes[hash]()), packages/kit/src/core/postbuild/analyse.js:143, packages/kit/src/core/postbuild/prerender.js:651 (Object.values). None depend on order.
• generate_manifest is also the right chokepoint: all four disk-written manifests go through it — manifest-full.js (packages/kit/src/exports/vite/build/index.js:481), the post-client-build regeneration (:766), the final output/server/manifest.js (:839), and the adapter-side copy written by builder.generateServerInstance() (packages/kit/src/core/adapt/builder.js:228), which is what ends up inside a Ko image. The dev manifest is a live object built by exports/vite/dev/generate_manifest.js (line 168) and never hits disk, so it doesn't matter here.

Empirical confirmation

Setup: macOS arm64, Node 24.13.0, @sveltejs/kit@3.0.0-next.27 (its generate_manifest/index.js is byte-identical to master — I diffed), vite 8.3.0, svelte 5.57.1, no adapter. Minimal app: eight remote modules src/lib/r01..r08.remote.js, each exporting one query, all imported from +page.svelte, experimental: { remoteFunctions: true } + compilerOptions: { experimental: { async: true } } on the sveltekit() plugin.

Six builds, zero source changes, extracting the key order each time:

for i in 1 2 3 4 5 6; do
	npx vite build >/dev/null 2>&1
	awk '/remotes: \{/,/\},/' .svelte-kit/output/server/manifest.js | grep -o "'[a-z0-9]*'" | tr '\n' ' '; echo
done

Result: six pairwise-distinct orderings of the eight keys. One observed order, hash→file: 1rmowjx(r02) 1tr9n2(r01) xsyevb(r08) 1f9q5e3(r04) 1fr4hoq(r05) 14hgia4(r03) jdpoco(r07) 16iy2mh(r06) — neither file order nor hash order. diff between two full manifests showed differences only inside the remotes: { ... } block; everything else (assets, client entry hashes, routes) was stable across runs.

Then I applied your patch verbatim to node_modules/@sveltejs/kit/src/core/generate_manifest/index.js and rebuilt three times: the remotes block was identical on every run, keys in lexicographic hash order ('14hgia4' '16iy2mh' '1f9q5e3' '1fr4hoq' '1rmowjx' '1tr9n2' 'jdpoco' 'xsyevb'), and a subsequent full-file diff of two patched builds came back empty — byte-identical manifest.js. Since Ko derives image digests from file bytes, this is exactly the property you need.

What sorting remotes does not fix

Other manifest inputs with the same class of ordering problem — worth stating in the PR description so nobody oversells the change:

1. assets — create_assets() (packages/kit/src/core/sync/create_manifest_data/index.js:80-87) uses walk() (packages/kit/src/utils/filesystem.js:84-99), which iterates fs.readdirSync unsorted, and that order lands in assets: new Set([...]) (generate_manifest/index.js:110). Precedent: fix: sort directory entries when building the route manifest #16074 (merged 2026-06-18, closing Dev server hydration errors when using bun #15313) sorted the routes traversal for exactly this reason — "readdirSync order is not guaranteed and differs between runtimes (e.g. Node returns entries alphabetically, Bun in directory order)" — but walk() was not covered. On one machine + runtime it's stable (APFS gave me alphabetical), so this bites mainly across runtimes/filesystems.
2. server_assets — find_server_assets() returns Array.from(Set) (packages/kit/src/core/generate_manifest/find_server_assets.js:56). Insertion order is driven by route order (deterministic, sort_routes) plus .vite/manifest.json traversal, so it's probably fine, but it isn't sorted by construction either.
3. prerendered_routes — prerendered.paths is pushed as pages complete inside a concurrent queue (packages/kit/src/core/postbuild/prerender.js:576,617; queue created at :236). With the default prerender.concurrency: 1 (core/config/options.js:252) it's crawl order; with higher concurrency it's completion order.
4. version.name — the default is still Date.now().toString() (packages/kit/src/core/config/options.js:313-316), emitted into _app/version.json (exports/vite/build/index.js:428-432). For your Ko integration, pin version.name to something stable (e.g. the git commit SHA) regardless of this PR. Good news verified by my builds: in SvelteKit 3 the version value no longer rotates client chunk hashes — it reaches the client via version.json and the inline payload (runtime/server/page/render.js:406), and my six runs with default timestamp versioning produced identical _app/immutable chunk names. That's the residue of Deterministic version.name #14176 (closed as completed), where a commenter observed that with Rolldown's improved determinism, version.name had become the only thing preventing back-to-back bundle builds from being fully reproducible.

Contribution path

• A direct PR is appropriate — no RFC needed. This is precisely the shape of fix: sort directory entries when building the route manifest #16074: small ordering fix + unit test + changeset. I searched open issues/PRs; nothing proposes this yet, so you're not duplicating work. Link this discussion in the PR, and cite Dev server hydration errors when using bun #15313/fix: sort directory entries when building the route manifest #16074 as precedent.
• There is no packages/kit/src/core/generate_manifest/index.spec.js today — yours would be the first, and it's auto-discovered (packages/kit/vitest.kit.config.js, the kit-server-dev project includes src/**/*.spec.js).
• The fixture is easy, and I verified it works: call generate_manifest() directly with a minimal build_data (empty manifest_data.assets/nodes/routes, params: null, service_worker: null, client: null, server_manifest: {}) plus a deliberately unsorted remotes array, then assert the key order in the returned string. With empty server assets, find_server_assets() never touches the filesystem, so no mocks are needed — and the test fails without your patch, which is what the PR template asks for. For mocking-style precedent see the reversed-readdir test at core/sync/create_manifest_data/index.spec.js:107.
• House checklist (CONTRIBUTING.md + PR template): pnpm changeset (bug fix → patch, message prefixed fix: — fix: sort directory entries when building the route manifest #16074 shipped .changeset/sort-manifest-readdir.md), and before submitting pnpm format, pnpm lint, pnpm check, pnpm -F @sveltejs/kit test:unit. Your sorted_remotes naming already matches the snake_case-for-internals convention.
• Two small design notes: your comparator ties only on equal hashes, which is benign (Array#sort is stable, and a genuine hash collision would mean two remotes emitting the same chunks/remote-<hash>.js — a pre-existing, separate problem). And sorting by hash rather than file is the right call anyway, since the hash is the emitted key, so the generated manifest also reads sorted.

If you feel like closing the assets gap too, I'd keep this PR to remotes and follow up with a second one sorting walk() output (or sorting in create_assets) — #16074 shows the maintainers evaluate these ordering fixes one at a time on their merits, and small diffs merge faster.