メモリの問題を避けて React で大容量ファイルをストリーミング
React で大容量ファイルをダウンロードする際は、レスポンスを Blob にまとめず、ユーザーが選択したファイルへの書き込みを毎回 await します。このチュートリアルでは、完全な React アプリをマウントし、内容が既知の 256 MiB のバイナリストリームをローカルで配信して、保存したファイルのバイト数と SHA-256 を確認します。ストリーミング方式では、アプリが保持するチャンク量を制限します。ただし、ブラウザー、ネットワーク、ファイルシステムのバッファーもメモリを使用します。
従来の Blob ダウンロードが大容量ファイルでうまくいかない理由
よく使われる fetch → blob → link.click() パターンは、レスポンス全体を待ってからブラウザーに渡します。Response.blob() は、本文を最後まで読み取ります。Blob の実際の保存先はブラウザーが選ぶため、必ずしも JavaScript ヒープに巨大な領域を一度に割り当てるわけではありませんが、ファイル全体を実体化することに変わりはありません。
対応するデスクトップ版 Chromium ブラウザーで、保存先ピッカーとアプリ内の進捗表示が必要な場合は、File System Access API を使用します。Firefox や Safari で大容量ファイルを扱う場合は、添付ファイル用エンドポイントへの通常のリンクを用意します。転送は JavaScript のチャンク配列の外でブラウザーが管理します。この例には、小容量ファイルに限定した Blob フォールバックも含めています。ここで扱うのは、新しいダウンロード先への保存です。ローカルファイルのハンドルを保存して再度開く処理は、別の永続的なファイル処理ワークフローです。
fetch と Streams API によるデータのストリーミング
Bash、メンテナンス対象の 24 LTS 系列の Node.js 24.15 以降、Corepack と Yarn 4.12.0 を使用してください。Node ディストリビューションに Corepack が含まれていない場合は、Corepack を別途インストールしてください。ネイティブピッカーを使う方式は Linux 上の Chromium 145 で、リンクと Blob を使う方式は Firefox でテストしました。既存のプロジェクトやワークスペースの外にある新しいディレクトリを使用してください。次の作成処理にはガードがあり、書き込みを始める前に前提条件と親階層のパッケージ設定を確認します。
(
command -v node >/dev/null && command -v corepack >/dev/null &&
node --input-type=module -e '
import { existsSync } from "node:fs"
import { dirname, join, resolve } from "node:path"
const [major, minor] = process.versions.node.split(".").map(Number)
if (!(major === 24 && minor >= 15 || major >= 26)) throw Error("Use Node 24.15+ or 26+")
for (let dir = resolve("."); ; dir = dirname(dir)) {
if (["package.json", ".yarnrc.yml", ".pnp.cjs"].some(name => existsSync(join(dir, name)))) {
throw Error("Choose a directory outside an existing project or workspace")
}
if (dirname(dir) === dir) break
}
' && COREPACK_ENABLE_AUTO_PIN=0 corepack yarn --version && mkdir react-stream-demo
) && cd react-stream-demo
react-stream-demo ディレクトリがすでにある場合、処理を拒否します。そのファイルは削除せずに残し、別の空の親ディレクトリを選んでください。後でインストールに失敗した場合は、この新しいプロジェクトでインストールを再試行します。以降の手順でプロジェクトを作り直す必要はありません。
新しいディレクトリに次のファイルを保存してください。package.json はデモの依存関係を固定します。
{
"name": "react-stream-demo",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"typecheck": "tsc --noEmit",
"build": "yarn typecheck && vite build",
"start": "node server.ts"
},
"dependencies": { "react": "19.2.6", "react-dom": "19.2.6" },
"devDependencies": {
"@types/node": "24.10.1",
"@types/react": "19.2.14",
"@types/react-dom": "19.2.3",
"@types/wicg-file-system-access": "2023.10.7",
"typescript": "6.0.3",
"vite": "7.3.1"
}
}
tsconfig.json を保存してください。これは完全な設定で、継承する extends はありません。
{
"compilerOptions": {
"target": "ES2024",
"lib": ["ES2024", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "Bundler",
"jsx": "react-jsx",
"strict": true,
"noEmit": true,
"allowImportingTsExtensions": true,
"types": ["node", "react", "react-dom", "wicg-file-system-access"]
},
"include": ["*.ts", "*.tsx"]
}
インストール、ビルド、起動で同じリンカーを使うように、.yarnrc.yml を保存してください。
nodeLinker: node-modules
index.html を保存してください。Vite が TypeScript のエントリーポイントをバンドルします。
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1"><title>React download demo</title></head>
<body><main id="root"></main><script type="module" src="/main.tsx"></script></body>
</html>
ブラウザー対応の概要
| ブラウザー | 保存先ピッカー | この例での大容量ファイルの処理 |
|---|---|---|
| デスクトップ版 Chrome と Edge | showSaveFilePicker を検出 | 選択したファイルにストリーミング |
| Firefox と Safari | showSaveFilePicker なし | 添付ファイルのリンク |
最新の対応状況は MDN のピッカーのドキュメントで確認してください。オリジン専用ファイルシステムへの対応は、保存先ピッカーへの対応を意味しません。ピッカーにはセキュアコンテキストとユーザー操作が必要です。このローカルデモには、ループバックの HTTP が適しています。Node 24 はメンテナンス対象の LTSです。サーバーと検証ツールにはネイティブの TypeScript 実行機能で十分ですが、ブラウザー向けの TSX は Vite でコンパイルします。
downloads.ts を保存してください。両方式で同じ読み取りループを使います。次のチャンクを要求する前にコンシューマーを待ち、失敗時はレスポンスをキャンセルし、リーダーを解放します。Content-Length がない場合や、圧縮時の値の場合は、バイト数のみで進捗を表示します。fetch が公開するのはデコード後の本文のバイト列なので、圧縮された転送時の長さは分母として使えません。
export type Progress = { received: number; total: number | null }
export type DownloadResult = { bytes: number; kind: 'saved' | 'handed-off' }
const MAX_BLOB_BYTES = 50 * 1024 * 1024
async function receive(
url: string,
consume: (chunk: Uint8Array<ArrayBuffer>) => Promise<void>,
onProgress: (progress: Progress) => void,
signal: AbortSignal,
limit = Infinity,
): Promise<number> {
signal.throwIfAborted()
const response = await fetch(url, { signal })
if (!response.ok) {
await response.body?.cancel()
throw new Error(`HTTP ${response.status}`)
}
if (!response.body) throw new Error('The response has no readable body')
const reader = response.body.getReader()
const cancelReader = () => { void reader.cancel(signal.reason).catch(() => {}) }
signal.addEventListener('abort', cancelReader, { once: true })
try {
const length = response.headers.get('Content-Length')
const parsed = length === null ? NaN : Number(length)
const encoding = response.headers.get('Content-Encoding')
const total = (!encoding || encoding === 'identity') && Number.isSafeInteger(parsed) && parsed >= 0
? parsed : null
if (total !== null && total > limit) throw new Error('Use the direct download link for this file')
let received = 0
onProgress({ received, total })
while (true) {
signal.throwIfAborted()
const { value, done } = await reader.read()
signal.throwIfAborted()
if (done) break
if (received + value.byteLength > limit) throw new Error('Use the direct download link for this file')
await consume(value)
received += value.byteLength
onProgress({ received, total })
}
if (total !== null && received !== total) throw new Error('Incomplete response')
return received
} finally {
signal.removeEventListener('abort', cancelReader)
await reader.cancel().catch(() => {})
reader.releaseLock()
}
}
export async function streamToDisk(
url: string,
filename: string,
onProgress: (progress: Progress) => void,
signal: AbortSignal,
): Promise<DownloadResult> {
signal.throwIfAborted()
const handle = await window.showSaveFilePicker({ suggestedName: filename })
signal.throwIfAborted()
const writable = await handle.createWritable()
try {
const bytes = await receive(url, (chunk) => writable.write(chunk), onProgress, signal)
signal.throwIfAborted()
await writable.close()
signal.throwIfAborted()
return { bytes, kind: 'saved' }
} catch (error) {
await writable.abort(error).catch(() => {})
throw error
}
}
export async function saveWithFallback(
url: string,
filename: string,
onProgress: (progress: Progress) => void,
signal: AbortSignal,
): Promise<DownloadResult> {
const chunks: ArrayBuffer[] = []
const bytes = await receive(url, async (chunk) => {
chunks.push(chunk.slice().buffer)
}, onProgress, signal, MAX_BLOB_BYTES)
signal.throwIfAborted()
const objectUrl = URL.createObjectURL(new Blob(chunks))
const link = document.createElement('a')
link.href = objectUrl
link.download = filename
try {
document.body.appendChild(link)
link.click()
} finally {
link.remove()
setTimeout(() => URL.revokeObjectURL(objectUrl), 60000)
}
return { bytes, kind: 'handed-off' }
}
Blob 方式は、長さのないレスポンスも含め、実際にデコードされたバイト数を 50 MiB に制限します。Blob 作成時には追加のコピーが必要になる場合があるため、これはアプリへの入力上限であり、ブラウザーの RAM 使用量の上限ではありません。ネイティブ方式は、書き込み可能ストリームが閉じてから戻ります。サーバーのコンテンツは検証しません。その検証は、後述するチェックサムの手順で独立して行います。
再利用可能な React フックの作成
useDownload.ts を保存してください。start はクリックハンドラーから直接呼び出します。ネットワーク処理を await する前にピッカーを開くことで、ユーザーアクティベーションを維持します。実行中のガードが重複した開始を防ぎ、アンマウント時には実行中の処理を中止します。これにより、古い転送が後のコンポーネントを更新するのを防ぎます。
import { useEffect, useRef, useState } from 'react'
import { saveWithFallback, streamToDisk } from './downloads.ts'
import type { DownloadResult, Progress } from './downloads.ts'
type UseDownloadReturn = {
progress: Progress | null
result: DownloadResult | null
message: string
busy: boolean
start: (url: string, filename: string) => Promise<void>
cancel: () => void
}
export function useDownload(): UseDownloadReturn {
const [progress, setProgress] = useState<Progress | null>(null)
const [result, setResult] = useState<DownloadResult | null>(null)
const [message, setMessage] = useState('Ready')
const [busy, setBusy] = useState(false)
const active = useRef<AbortController | null>(null)
useEffect(() => () => {
active.current?.abort()
active.current = null
}, [])
async function start(url: string, filename: string): Promise<void> {
if (active.current) return
const controller = new AbortController()
active.current = controller
setBusy(true)
setProgress(null)
setResult(null)
setMessage('Choose a destination or wait for the download…')
const onProgress = (value: Progress) => {
if (active.current === controller && !controller.signal.aborted) setProgress(value)
}
try {
const download = window.isSecureContext && typeof window.showSaveFilePicker === 'function'
? streamToDisk : saveWithFallback
const completed = await download(url, filename, onProgress, controller.signal)
controller.signal.throwIfAborted()
if (active.current !== controller) return
setResult(completed)
setMessage(completed.kind === 'saved'
? `Saved ${completed.bytes.toLocaleString()} bytes. Verify the file below.`
: 'Handed to browser. Check your downloads; disk saving is not confirmed.')
} catch (error) {
if (active.current !== controller) return
setProgress(null)
setMessage(controller.signal.aborted || error instanceof DOMException && error.name === 'AbortError'
? 'Canceled. Saving is not confirmed.'
: 'Download failed. Retry or use the direct download link.')
} finally {
if (active.current === controller) {
active.current = null
setBusy(false)
}
}
}
function cancel(): void { active.current?.abort() }
return { progress, result, message, busy, start, cancel }
}
main.tsx を保存してください。256 MiB の選択肢ではネイティブ方式を試せます。Firefox で Blob フォールバックを試すには
1 MiB を選択してください。大容量ファイルには、通常のリンクも引き続き使用できます。
import { useState } from 'react'
import type { ReactNode } from 'react'
import { createRoot } from 'react-dom/client'
import { useDownload } from './useDownload.ts'
function App(): ReactNode {
const [mib, setMib] = useState('256')
const { progress, message, busy, start, cancel } = useDownload()
const url = `/file?mib=${mib}`
const filename = `fixture-${mib}.bin`
const percent = progress?.total !== null && progress?.total !== undefined && progress.total > 0
? Math.min(99, progress.received / progress.total * 100) : undefined
return (
<section>
<h1>React download demo</h1>
<label>File size (MiB) <select value={mib} disabled={busy} onChange={(event) => setMib(event.target.value)}>
<option value="1">1</option><option value="256">256</option><option value="512">512</option>
</select></label>
<p><button disabled={busy} onClick={() => { void start(url, filename) }}>Save with progress</button>{' '}
<button disabled={!busy} onClick={cancel}>Cancel transfer</button></p>
<p><a href={url}>Direct download</a></p>
{busy && progress !== null ? (
<p><progress aria-label="Download progress" value={percent} max={100} />{' '}
{progress.received.toLocaleString()} bytes received</p>
) : null}
<p role="status">{message}</p>
</section>
)
}
const root = document.getElementById('root')
if (!root) throw new Error('Missing root element')
createRoot(root).render(<App />)
内容が既知のバイナリストリームの配信
server.ts を保存してください。ビルド済みアプリと非圧縮の添付ファイルを同一オリジンで配信するため、このローカルの例では CORS も認証も必要ありません。各 64 KiB ブロックには、ゼロバイトを含むバイナリパターンが繰り返し格納されています。Node のパイプはレスポンスのバックプレッシャーに従い、クライアントが切断すると生成元を破棄します。/manifest?mib=256 はファイル自体を送信せずに、期待されるバイト数と SHA-256 を返します。
import { createHash } from 'node:crypto'
import { readFile } from 'node:fs/promises'
import { createServer } from 'node:http'
import type { ServerResponse } from 'node:http'
import { join } from 'node:path'
import { Readable } from 'node:stream'
import { setTimeout as delay } from 'node:timers/promises'
const block = Buffer.from(Uint8Array.from({ length: 64 * 1024 }, (_, i) => i % 251))
function manifest(bytes: number) {
const hash = createHash('sha256')
for (let offset = 0; offset < bytes; offset += block.length) {
hash.update(block.subarray(0, Math.min(block.length, bytes - offset)))
}
return { bytes, sha256: hash.digest('hex') }
}
async function serve(url: URL, response: ServerResponse): Promise<void> {
if (url.pathname === '/file' || url.pathname === '/manifest') {
const mib = Number(url.searchParams.get('mib') ?? 256)
if (!Number.isInteger(mib) || mib < 0 || mib > 1024) {
response.writeHead(400).end('Choose an integer size from 0 to 1024 MiB')
return
}
const bytes = mib * 1024 * 1024
if (url.pathname === '/manifest') {
response.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(manifest(bytes)))
return
}
response.setHeader('Content-Type', 'application/octet-stream')
response.setHeader('Content-Disposition', `attachment; filename="fixture-${mib}.bin"`)
response.setHeader('Cache-Control', 'no-store')
if (url.searchParams.get('length') !== 'unknown') response.setHeader('Content-Length', bytes)
async function* chunks() {
for (let offset = 0; offset < bytes; offset += block.length) {
yield block.subarray(0, Math.min(block.length, bytes - offset))
await delay(1)
}
}
const source = Readable.from(chunks())
response.on('close', () => source.destroy())
source.on('error', () => response.destroy())
source.pipe(response)
return
}
const asset = url.pathname === '/' ? 'index.html' : url.pathname.slice(1)
if (asset !== 'index.html' && !/^assets\/[a-zA-Z0-9._-]+$/.test(asset)) {
response.writeHead(404).end('Not found')
return
}
const body = await readFile(join(import.meta.dirname, 'dist', asset))
response.writeHead(200, { 'Content-Type': asset.endsWith('.js') ? 'text/javascript' : 'text/html' }).end(body)
}
async function main(): Promise<void> {
const server = createServer((request, response) => {
void serve(new URL(request.url ?? '/', 'http://localhost'), response).catch(() => {
if (response.headersSent) response.destroy()
else response.writeHead(500).end('Could not serve the demo. Build it first.')
})
})
await new Promise<void>((resolve, reject) => {
server.once('error', reject)
server.listen(Number(process.env.PORT ?? 8787), '127.0.0.1', resolve)
})
const address = server.address()
if (!address || typeof address === 'string') throw new Error('Missing listening address')
console.log(`Open http://127.0.0.1:${address.port}`)
}
main().catch((error: unknown) => { console.error(error); process.exitCode = 1 })
Yarn の node-modules リンカーでローカルにインストールし、型チェック、ビルド、サーバーの起動を実行してください。
corepack yarn install
corepack yarn build && corepack yarn start
http://127.0.0.1:8787 を開き、Save with progressをクリックして、ネイティブの保存ダイアログで fixture-256.bin という名前の新しいパスを選択します。ブラウザーが書き込み権限を求めたら許可してください。Savedで始まるステータスを待ちます。検証のため、サーバーは起動したままにしてください。Ctrl+C で停止できます。ポート 8787 が使用中の場合は、PORT=8788 corepack yarn start を使い、検証ツールでも対応するオリジンを指定してください。
セキュリティ、権限、エラー処理
保存先ピッカーにはユーザーアクティベーションが必要です。クリック処理の中で開き、その前に API リクエストを await しないでください。デプロイしたサイトでは HTTPS を使用します。出力先には、破棄してもよい新しいパスを選んでください。置き換えを許可すると、成功する前から既存ファイルが失われるおそれがあります。テストした Linux の GTK ダイアログでは、最後のクローズが拒否された際、許可済みの保存先が空のまま残りました。失敗した書き込みを中止しても、そのファイルが復元される保証はありません。新しいパスへの保存をキャンセルした場合も、空のファイルが残ることがあります。ファイルシステムへの最終コミット中にキャンセルしても、すでにコミットされたバイト列を元に戻せる保証はありません。
ピッカーのキャンセル、進捗開始後のキャンセル、再保存を試してください。キャンセルや HTTP、読み取り、書き込み、最終クローズのエラーが発生した場合は、保存済みステータスを決して表示してはいけません。フックは開始のたびに前回の結果をリセットします。毎回新しくピッカーを開き、再読み込みやブラウザー再起動をまたぐ場合も含めて、ハンドルや権限の状態は保存しません。保存済みハンドルを使うワークフローには、独自の権限チェックが必要です。
独自の API では、失敗時に意味のあるステータスを返してください。信頼できる長さやチェックサムがなければ、エラーなしで途中終了したレスポンスと、正常な短いファイルは区別できません。クロスオリジンの fetch では、CORS を設定し、進捗表示に使うヘッダーを公開します。直接リンクにはカスタムの Authorization ヘッダーを追加できないため、セッション認証か、認可されたダウンロード URL を使用してください。クロスオリジンのダウンロードでは、Content-Disposition: attachmentが重要です。download 属性だけでは不十分です。
ディスク上の実際のファイルの検証
verify.ts を保存してください。ディスクからファイルをストリーミングで読み取り、サイズとハッシュの両方をローカルのテストデータのマニフェストと比較します。別に生成したファイルやブラウザーのステータスではなく、渡したパスを検証します。
import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'
async function main(): Promise<void> {
const [path, mib = '256'] = process.argv.slice(2)
if (!path) throw new Error('Usage: node verify.ts /path/to/fixture-256.bin [MiB]')
const origin = process.env.DOWNLOAD_ORIGIN ?? 'http://127.0.0.1:8787'
const response = await fetch(`${origin}/manifest?mib=${encodeURIComponent(mib)}`)
if (!response.ok) throw new Error(`Manifest HTTP ${response.status}`)
const expected: unknown = await response.json()
if (typeof expected !== 'object' || expected === null || !('bytes' in expected) ||
!('sha256' in expected) || typeof expected.bytes !== 'number' || typeof expected.sha256 !== 'string') {
throw new Error('Invalid manifest')
}
const hash = createHash('sha256')
let bytes = 0
for await (const chunk of createReadStream(path)) {
bytes += chunk.length
hash.update(chunk)
}
const actual = hash.digest('hex')
if (bytes !== expected.bytes || actual !== expected.sha256) throw new Error('Size or SHA-256 mismatch')
console.log(`Verified ${bytes} bytes; SHA-256 ${actual}`)
}
main().catch((error: unknown) => { console.error(error); process.exitCode = 1 })
別のターミナルでプロジェクトのディレクトリに移動し、実際に保存したパスを指定して検証ツールを実行してください。
node verify.ts "/absolute/path/to/fixture-256.bin" 256
Verified 268435456 bytes; SHA-256 … が表示されることを確認します。同じ長さでも内容が異なるファイルは、必ず Size or SHA-256 mismatch で失敗する必要があります。1 MiB の選択肢では、最後の引数に 1 を渡してください。Firefox では、Save with progressが小さな Blob をブラウザーに渡し、Handed to browser. Check your downloads; disk saving is not confirmed.と表示します。256 MiB のファイルにはDirect downloadを使用し、そのディスク上のファイルも検証してください。リンクによるダウンロードの開始も、オブジェクト URL の作成も、保存完了を確認するものではありません。
メモリ使用量の比較
| 方式 | アプリのバッファリング | このアプリで観測できる完了状態 |
|---|---|---|
response.blob() | 引き渡し前にレスポンス全体を保持 | Blob の作成完了 |
| 選択したファイルにストリーミング | 次の読み取り前にチャンクの書き込みを待機 | 書き込み可能ストリームのクローズ成功 |
| 上限付き Blob フォールバック | 最大 50 MiB と Blob のコピー | ブラウザーへの引き渡し |
| 添付ファイルのリンク | ブラウザーが転送を管理 | ブラウザーのダウンロード UI で確認 |
アプリの動作を比較するには、256 MiB と 512 MiB の選択肢を保存し、読み書きループを調べてください。ネイティブ方式ではチャンクを蓄積しません。書き込みが遅いとアプリの次の読み取りも遅れますが、fetch とブラウザーは先行してバッファリングする場合があります。JavaScript ヒープの測定だけでは、ブラウザー全体の RAM 使用量の上限、速度の向上、停電後のファイルシステムの永続性を立証できません。
まとめ
テストデータを実際のエクスポート用エンドポイントに置き換える際も、チェックサム検証を残してください。そのファイルについて、独立して信頼性を確認できる発行元のチェックサムを使用し、ネイティブピッカーがない環境では常に、ブラウザーが管理する添付ファイルのリンクを利用できるようにします。このデモは毎回新しくダウンロードします。キャンセルした転送の再開や、以前の保存先へのアクセスの永続化は行いません。
