docs: file upload example (BLO-1311)

[matthewlipski]

Summary

This PR fixes the file upload example and related file upload code as tmpfiles changed their API and it no longer works for our use. To prevent issues like that happening in the future, we now just save the file as a base64 URL.

Closes @2967

Rationale

The example is broken.

Changes

• Updated docs demo.
• Updated file upload example.
• Updated Uppy file panel example.
• Updated and renamed uploadFilesToTmpFilesDotOrg_DEV_ONLY to uploadFile_DEV_ONLY.

Impact

N/A

Testing

N/A - TODO?

Screenshots/Video

N/A

Checklist

• Code follows the project's coding standards.
• Unit tests covering the new feature have been added.
• All existing tests pass.
• The documentation has been updated to reflect the new feature

Additional Notes

N/A

Summary by CodeRabbit

• New Features

  • File uploads in development examples now use local base64 data URLs, enabling image previews without an external temporary file service.
  • Upload guidance now explains how to replace the local approach with a production backend.

• Bug Fixes

  • Improved handling of file-reading failures during uploads.

• Documentation

  • Updated examples and file-upload documentation to reflect local data URL encoding.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blocknote	Ready	Preview	Aug 24, 2026 1:56pm
blocknote-website	Ready	Preview	Aug 24, 2026 1:56pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 77b02566-b1ad-4bb5-819b-76c4c8dca591

📥 Commits

Reviewing files that changed from the base of the PR and between 9ccd1f8 and 32019b0.

📒 Files selected for processing (7)

• docs/app/demo/_components/utils.ts
• docs/content/docs/react/components/image-toolbar.mdx
• examples/01-basic/testing/src/App.tsx
• examples/02-backend/01-file-uploading/src/App.tsx
• examples/03-ui-components/11-uppy-file-panel/src/UppyFilePanel.tsx
• packages/core/src/blocks/index.ts
• tests/src/unit/core/createTestEditor.ts

💤 Files with no reviewable changes (1)

• packages/core/src/blocks/index.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/content/docs/react/components/image-toolbar.mdx

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

File uploads now use local FileReader conversion to base64 data URLs across demos, Uppy, documentation, and tests. The development-only temporary-file uploader and its export were removed.

Changes

Local data URL uploads

Layer / File(s)	Summary
Remove temporary-file helper packages/core/src/blocks/index.ts	Removes the development-only temporary-file upload export.
Adopt local data URL conversion docs/app/demo/_components/utils.ts, examples/01-basic/testing/src/App.tsx, examples/02-backend/01-file-uploading/src/App.tsx, tests/src/unit/core/createTestEditor.ts	Replaces the removed helper with FileReader-based upload functions that resolve with data URLs and reject on read errors.
Uppy local upload flow examples/03-ui-components/11-uppy-file-panel/src/UppyFilePanel.tsx	Removes remote XHR uploading and updates blocks with locally generated data URLs.
Documentation and validation examples/02-backend/01-file-uploading/README.md, playground/src/examples.gen.tsx, docs/content/docs/react/components/image-toolbar.mdx, tests/src/end-to-end/images/images.test.tsx	Updates descriptions and image detection to refer to data URLs and backend replacement.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 32019

The file-upload example changes do not leave an actionable merge-blocking risk based on the supplied evidence; the PR is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Uppy
  participant UppyFilePanel
  participant FileReader
  participant BlockNoteEditor
  Uppy->>UppyFilePanel: Report completed file
  UppyFilePanel->>FileReader: Read file as data URL
  FileReader-->>UppyFilePanel: Return data URL or read error
  UppyFilePanel->>BlockNoteEditor: Update block with file data URL
  UppyFilePanel->>Uppy: Remove processed file

Loading

Suggested reviewers: nperez0111

Poem

I’m a rabbit with files in my den,
Data URLs hop out again.
No temp-file trail, no distant flight,
FileReader makes each image bright.
Thump, test, and docs all align!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the file upload example fix and includes the related issue identifier.
Description check	✅ Passed	The description includes all required sections and explains the change, but testing details and checklist updates are incomplete.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-file-upload

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[nperez0111]

Can we change it from being exported? Otherwise fine to move off the actual upload path

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@2996

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@2996

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@2996

@blocknote/diagram-block

npm i https://pkg.pr.new/@blocknote/diagram-block@2996

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@2996

@blocknote/math-block

npm i https://pkg.pr.new/@blocknote/math-block@2996

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@2996

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@2996

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@2996

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@2996

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@2996

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@2996

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@2996

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@2996

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@2996

commit: 32019b0

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://TypeCellOS.github.io/BlockNote/pr-preview/pr-2996/
Built to branch gh-pages at 2026-08-25 07:53 UTC. Preview will be ready when the GitHub Pages deployment is complete.