docs: expand single-file executable file embedding documentation #25408
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Collaborator
Author
|
Updated 4:42 PM PT - Dec 7th, 2025
✅ @autofix-ci[bot], your commit 35f7f64bbf8124dac57d631ccaab769adc5ba447 passed in 🧪 To try this PR locally: bunx bun-pr 25408That installs a local version of the PR into your bun-25408 --bun |
Contributor
WalkthroughExpanded the "Embed assets & files" documentation in the executables guide with comprehensive step-by-step instructions, detailed explanations of the embedding mechanism, and practical examples including configuration files, static assets, templates, and binary files. Added clarifications about Bun.embeddedFiles and embedded file listing. Changes
Possibly related PRs
Suggested reviewers
Pre-merge checks✅ Passed checks (2 passed)
Comment |
Add comprehensive documentation for embedding files with `with { type: "file" }`:
- Explain how the import attribute works and path transformation
- Show reading embedded files with Bun.file() (arrayBuffer, text, blob)
- Show reading embedded files with Node.js fs APIs (readFileSync, promises.readFile, stat)
- Add practical examples: JSON configs, HTTP static assets, templates, binary files
- Improve Bun.embeddedFiles section with dynamic asset server example
- Add note about source code exclusion from embeddedFiles
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
robobun
force-pushed
the
claude/docs-embed-files-expanded
branch
from
75bc219 to
c5cc800
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/bundler/executables.mdx(2 hunks)
🧰 Additional context used
🧠 Learnings (11)
📓 Common learnings
Learnt from: RiskyMH
Repo: oven-sh/bun PR: 24719
File: docs/bundler/executables.mdx:527-560
Timestamp: 2025-11-14T16:07:01.064Z
Learning: In the Bun repository, certain bundler features like compile with code splitting (--compile --splitting) are CLI-only and not supported in the Bun.build() JavaScript API. Tests for CLI-only features use backend: "cli" flag (e.g., test/bundler/bundler_compile_splitting.test.ts). The CompileBuildConfig interface correctly restricts these with splitting?: never;. When documenting CLI-only bundler features, add a note clarifying they're not available via the programmatic API.
Learnt from: CR
Repo: oven-sh/bun PR: 0
File: .cursor/rules/building-bun.mdc:0-0
Timestamp: 2025-11-24T18:34:55.173Z
Learning: Applies to src/**/*.{cpp,zig} : Execute files using `bun bd <file> <...args>`; never use `bun <file>` directly as it will not include your changes
📚 Learning: 2025-11-14T16:07:01.064Z
Learnt from: RiskyMH
Repo: oven-sh/bun PR: 24719
File: docs/bundler/executables.mdx:527-560
Timestamp: 2025-11-14T16:07:01.064Z
Learning: In the Bun repository, certain bundler features like compile with code splitting (--compile --splitting) are CLI-only and not supported in the Bun.build() JavaScript API. Tests for CLI-only features use backend: "cli" flag (e.g., test/bundler/bundler_compile_splitting.test.ts). The CompileBuildConfig interface correctly restricts these with splitting?: never;. When documenting CLI-only bundler features, add a note clarifying they're not available via the programmatic API.
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-11-24T18:37:11.466Z
Learnt from: CR
Repo: oven-sh/bun PR: 0
File: src/js/CLAUDE.md:0-0
Timestamp: 2025-11-24T18:37:11.466Z
Learning: Write JS builtins for Bun's Node.js compatibility and APIs, and run `bun bd` after changes
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-11-13T07:23:11.159Z
Learnt from: RiskyMH
Repo: oven-sh/bun PR: 24668
File: docs/quickstart.mdx:181-197
Timestamp: 2025-11-13T07:23:11.159Z
Learning: In Bun.serve's routes configuration, imported HTML files can be assigned directly to routes without wrapping them in a function that returns a Response. For example, `import index from './index.html'` followed by `"/": index` in the routes object is valid Bun syntax for serving HTML content.
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-10-15T04:01:16.478Z
Learnt from: AmanVarshney01
Repo: oven-sh/bun PR: 23580
File: docs/guides/ecosystem/prisma.md:21-26
Timestamp: 2025-10-15T04:01:16.478Z
Learning: For Prisma with Bun runtime and Rust-free client (engineType "client"), when using local SQLite files (file:// URLs), use either prisma/adapter-better-sqlite3 or the Bun-native synapsenwerkstatt/prisma-bun-sqlite-adapter. The prisma/adapter-libsql adapter is only for remote libSQL/Turso endpoints and will not work with local SQLite file URLs.
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-10-19T02:52:37.412Z
Learnt from: theshadow27
Repo: oven-sh/bun PR: 23798
File: packages/bun-otel/tsconfig.json:1-15
Timestamp: 2025-10-19T02:52:37.412Z
Learning: In the Bun repository, packages under packages/ (e.g., bun-otel) can follow a TypeScript-first pattern where package.json exports point directly to .ts files (not compiled .js files). Bun natively runs TypeScript, so consumers import .ts sources directly and receive full type information without needing compiled .d.ts declaration files. For such packages, adding "declaration": true or "outDir" in tsconfig.json is unnecessary and would break the export structure.
<!-- [remove_learning]
ceedde95-980e-4898-a2c6-40ff73913664
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-11-24T18:34:55.173Z
Learnt from: CR
Repo: oven-sh/bun PR: 0
File: .cursor/rules/building-bun.mdc:0-0
Timestamp: 2025-11-24T18:34:55.173Z
Learning: Applies to src/**/*.{cpp,zig} : Execute files using `bun bd <file> <...args>`; never use `bun <file>` directly as it will not include your changes
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-10-19T02:44:46.354Z
Learnt from: theshadow27
Repo: oven-sh/bun PR: 23798
File: packages/bun-otel/context-propagation.test.ts:1-1
Timestamp: 2025-10-19T02:44:46.354Z
Learning: In the Bun repository, standalone packages under packages/ (e.g., bun-vscode, bun-inspector-protocol, bun-plugin-yaml, bun-plugin-svelte, bun-debug-adapter-protocol, bun-otel) co-locate their tests with package source code using *.test.ts files. This follows standard npm/monorepo patterns. The test/ directory hierarchy (test/js/bun/, test/cli/, test/js/node/) is reserved for testing Bun's core runtime APIs and built-in functionality, not standalone packages.
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-11-24T18:37:30.259Z
Learnt from: CR
Repo: oven-sh/bun PR: 0
File: test/CLAUDE.md:0-0
Timestamp: 2025-11-24T18:37:30.259Z
Learning: Applies to test/**/*.test.{ts,js,jsx,tsx,mjs,cjs} : Use `bun:test` with files that end in `*.test.{ts,js,jsx,tsx,mjs,cjs}`
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-10-08T13:56:00.875Z
Learnt from: Jarred-Sumner
Repo: oven-sh/bun PR: 23373
File: src/bun.js/api/BunObject.zig:2514-2521
Timestamp: 2025-10-08T13:56:00.875Z
Learning: For Bun codebase: prefer using `bun.path` utilities (e.g., `bun.path.joinAbsStringBuf`, `bun.path.join`) over `std.fs.path` functions for path operations.
Applied to files:
docs/bundler/executables.mdx
📚 Learning: 2025-11-24T18:35:39.205Z
Learnt from: CR
Repo: oven-sh/bun PR: 0
File: .cursor/rules/registering-bun-modules.mdc:0-0
Timestamp: 2025-11-24T18:35:39.205Z
Learning: Reference existing modules like Valkey, S3Client, or SQLite as guides when implementing new Bun features
Applied to files:
docs/bundler/executables.mdx
🪛 LanguageTool
docs/bundler/executables.mdx
[style] ~570-~570: Try using a synonym here to strengthen your writing.
Context: ...ing embedded files Bun.embeddedFiles gives you access to all embedded files as Blob ...
(GIVE_PROVIDE)
🔇 Additional comments (1)
docs/bundler/executables.mdx (1)
385-620: Excellent expansion of embedding documentation with clear examples and explanations.The restructured section is well-organized and comprehensive:
- The "How it works" explanation clearly describes the path transformation mechanism at build time
- Separate subsections for
Bun.file()and Node.jsfsAPIs address both use cases- Practical examples (JSON config, static assets, templates, binary files) are concrete and immediately useful
- The dynamic asset server example (lines 596–616) effectively demonstrates real-world usage of
Bun.embeddedFiles- The Note clarifying that source files are excluded from
embeddedFilesadds important context for developers concerned about source protectionAll code examples follow Bun's documented patterns correctly, including proper import attribute syntax and the correct type signature (
ReadonlyArray<Blob>).
| ### Listing embedded files | ||
|
|
||
| To get a list of all embedded files, use `Bun.embeddedFiles`: | ||
| `Bun.embeddedFiles` gives you access to all embedded files as `Blob` objects: |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Strengthen the writing with a more precise verb.
The phrase "gives you access to" is slightly redundant. Consider using "provides" for more direct phrasing.
-`Bun.embeddedFiles` gives you access to all embedded files as `Blob` objects:
+`Bun.embeddedFiles` provides access to all embedded files as `Blob` objects:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| `Bun.embeddedFiles` gives you access to all embedded files as `Blob` objects: | |
| `Bun.embeddedFiles` provides access to all embedded files as `Blob` objects: |
🧰 Tools
🪛 LanguageTool
[style] ~570-~570: Try using a synonym here to strengthen your writing.
Context: ...ing embedded files Bun.embeddedFiles gives you access to all embedded files as Blob ...
(GIVE_PROVIDE)
🤖 Prompt for AI Agents
In docs/bundler/executables.mdx around line 570, the phrase "gives you access
to" is wordy; replace it with a more precise verb such as "provides" (e.g.,
"Bun.embeddedFiles provides all embedded files as `Blob` objects" or "provides
access to all embedded files as `Blob` objects") to tighten the wording while
preserving the original meaning.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
with { type: "file" }Bun.file()and Node.jsfsAPIsBun.embeddedFilessection with a dynamic asset server exampleTest plan
bun build --compileBun.file()reads embedded files correctlynode:fsAPIs (readFileSync,promises.readFile,stat) work with embedded filesBun.embeddedFilesreturns correct blob array--asset-namingflag removes content hashes🤖 Generated with Claude Code