[robobun]

Problem

• blob.name on an entry of Bun.embeddedFiles is error TS2339: Property 'name' does not exist on type 'Blob'. Two samples of docs/compiler/executables.mdx read it (lines 1016 and 1042).
• The declaration is ReadonlyArray<Blob> (packages/bun-types/bun.d.ts:5198). Blob declares no name.

Fix

• Declare ReadonlyArray<Blob & { readonly name: string }>, and show that type on the page.
• Correct: in an executable from bun build --compile (canary 98cda0d), each entry is a Blob, not a File, and typeof blob.name is "string". template_blob sets the name from the embedded path (src/runtime/api/standalone_graph_jsc.rs:64). Both samples run as written.
• Verified: test/integration/bun-types/fixture/bun.ts (the new lines report TS2339 and TS2578 with the declaration of main). bun test test/integration/bun-types/bun-types.test.ts: 30 pass.

Background

• Bun.embeddedFiles lists the files that a standalone executable embeds, for example an import with { type: "file" }.
• A Blob has no name in the types, and new Blob(["x"]).name is undefined at runtime.
• Considered BunFile: it promises writer() and unlink(), which throw for an embedded file, and stat(), which resolves to undefined. Considered File: blob instanceof File is false.

Downsides

• A plain Blob no longer fits where an entry is expected: const one: (typeof Bun.embeddedFiles)[number] = new Blob(["x"]) is TS2322. 3 of 15 usage shapes that compile on main fail. One is a // @ts-expect-error above blob.name, which is now unused.
• blob.name = "x" works at runtime. It is TS2540 now, and TS2339 on main.
• builtin_sources.bin grows 6 bytes and the package tarball 82 bytes.

Notes

Origin. The type check of the docs code blocks in #48479 found the two samples. With this change, that check reports nothing for the two samples and for the type listing of the page. If #48479 lands first, this pull request also removes those three entries of docs/compiler/executables.mdx from docs-samples.inventory.json.

Runtime probe (canary 1.4.4-canary.1+98cda0d8b, Linux x64). index.ts imports ./icon.png, ./data.json and ./template.html with { type: "file" }, then prints each entry of embeddedFiles. Built with bun build --compile ./index.ts --outfile ./app:

data-dwdzq42g.json - 8 bytes       constructor Blob, instanceof File false, typeof name string
icon-7zjyd5xx.png - 7 bytes        constructor Blob, instanceof File false, typeof name string
template-tsyv6076.html - 12 bytes  constructor Blob, instanceof File false, typeof name string

Run with bun index.ts, the array is empty. On an entry, writer() and unlink() throw ERR_INVALID_ARG_TYPE ("Cannot write to a Blob backed by bytes, which are always read-only"), await stat() is undefined, and await exists() is true. The second sample of the page (static routes from the embedded files) answers 200 for /favicon.ico, /logo.png and /styles.css and 404 for another path.

Why name is always a string. template_blob sets the blob's name to display_name(), the embedded path without /$bunfs/root/. The name getter of Blob returns that string (src/runtime/webcore/Blob.rs:1753).

readonly. BunFile.name and the File.name of the web platform are read-only in the types. The setter of Blob.prototype.name exists at runtime today. #32434 proposes to move name to File.prototype.

Measurements (TypeScript 6.0.2, the bun init tsconfig, main at 89452d2)

• The two samples of docs/compiler/executables.mdx: TS2339 each on main, 0 diagnostics with this change. The type listing of the page was embeddedFiles: ReadonlyArray<Blob>;, which is TS2689 as a program. It is a declare const now, 0 diagnostics.
• Usage shapes (22 small programs that use Bun.embeddedFiles): 15 compile on main, 3 of them fail with this change (the unused @ts-expect-error, a plain Blob assigned to the element type, a plain Blob pushed into a copy of the array). 4 that fail on main compile with this change.
• bun.d.ts without comments: 85,099 to 85,127 bytes. Its zstd frame in builtin_sources.bin: 16,805 to 16,811 bytes (the parameters of src/codegen/builtins-manifest.ts).
• bun pm pack of packages/bun-types: 82 bytes more (1,522,674 to 1,522,756, measured at 2596ac5).
• Per type-check program that loads bun-types: +6 nodes, +2 symbols, +0 types (of 250,318 nodes).
• The same program with lib.dom: covered by the checks with lib.dom.d.ts case of the test.

---

no test proof · iteration 0 · no src or test change; test-proof not applicable

[robobun]

Status

How it was reproduced: blob.name on an entry of Bun.embeddedFiles is TS2339 with the bun init tsconfig and the types of main (89452d2). In an executable from bun build --compile (canary 98cda0d), each entry is a Blob whose name is a string. The two samples of docs/compiler/executables.mdx run as written.

Pull request: #48483

[robobun]

^{Updated 10:51 AM PT - Nov 10th, 2026}

✅ @robobun, your commit e907ecd6e80857cfb2d66d2d891883a90157ba4d passed in Build #139792! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 48483

That installs a local version of the PR into your bun-48483 executable, so you can run:

bun-48483 --bun

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

Bun.embeddedFiles is now documented and typed as a readonly array of Blob values with a readonly name property. Type assertions check the entry shape.

Changes

Embedded file name type

Layer / File(s)	Summary
Declare and validate embedded file entry type packages/bun-types/bun.d.ts, docs/compiler/executables.mdx, test/integration/bun-types/fixture/bun.ts	The public type and documentation add a readonly name property to each embedded file Blob. Type assertions check that entries have a string name, extend Blob, and reject a plain Blob as an entry.

Possibly related PRs

• oven-sh/bun#46007: Changes how --asset files are mounted in executable output, including their paths and basenames, which define the name covered by the new declaration.
• oven-sh/bun#47895: Refactors get_embedded_files, which constructs the results described by the updated declaration.

Suggested reviewers: jarred-sumner

Merge Risk: Minimal · up to e907e

Embedded file names are now exposed in the public types. No merge-blocking issue was identified.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title clearly identifies the change: adding the name property to each Bun.embeddedFiles entry.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description is complete and relevant. It explains the problem, proposed fix, runtime behavior, tradeoffs, and verification results. It does not use the template headings exactly, but it provides t…

Full details: Description check

Explanation

The description is complete and relevant. It explains the problem, proposed fix, runtime behavior, tradeoffs, and verification results. It does not use the template headings exactly, but it provides the required information under equivalent sections.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

Recent review info

Run configuration

• Source mode: Auto
• Repository: oven-sh/bun
• Branch: robobun/a4122461/embedded-files-name-type
• File: .coderabbit.yaml
• Commit: e907ecd
• Layers: Repository YAML
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 1c467a45-aef5-43fd-8116-28bbce66bc72

Commits

Reviewing files that changed from the base of the PR and between 89452d2 and e907ecd.

Files selected for processing: 3

• docs/compiler/executables.mdx
• packages/bun-types/bun.d.ts
• test/integration/bun-types/fixture/bun.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 1 remain after this review.