feat(local-explorer-ui): Add R2 support (#12888)

Co-authored-by: Ben Dixon <ben@nuro.dev>
Co-authored-by: Ben <4991309+NuroDev@users.noreply.github.com>

Author: emily-shen

.changeset/sour-sides-enjoy.md

@@ -0,0 +1,14 @@
+---
+"@cloudflare/local-explorer-ui": minor
+"miniflare": minor
+---
+
+Add R2 support to the local explorer.
+
+The local explorer now supports the following:
+
+- Viewing, modifying & deleting objects
+- Uploading files
+- Creating directories / prefixes
+
+Note: The local explorer is an experimental WIP feature that is now enabled by default. This can still be opt-ed out of by using `X_LOCAL_EXPLORER=false` to disable it.

fixtures/worker-with-resources/src/index.ts

@@ -26,6 +26,19 @@ export default {
 				return new Response(`Seeded ${SEED_DATA.length} KV entries`);
 			}
 
+			// R2 routes
+			case "/r2/seed": {
+				await Promise.all(
+					R2_SEED_DATA.map(({ key, content, contentType, customMetadata }) =>
+						env.BUCKET.put(key, content, {
+							httpMetadata: { contentType },
+							customMetadata,
+						})
+					)
+				);
+				return new Response(`Seeded ${R2_SEED_DATA.length} R2 objects`);
+			}
+
 			// D1 database route
 			case "/d1": {
 				await env.DB.exec(`
@@ -202,3 +215,134 @@ const SEED_DATA: [string, string][] = [
 	["number-float", "3.14159"],
 	["number-negative", "-273.15"],
 ];
+
+interface R2SeedItem {
+	key: string;
+	content: string | ArrayBuffer;
+	contentType: string;
+	customMetadata?: Record<string, string>;
+}
+
+const R2_SEED_DATA: R2SeedItem[] = [
+	// Root level files
+	{
+		key: "readme.txt",
+		content: "Welcome to the R2 bucket! This is a sample readme file.",
+		contentType: "text/plain",
+	},
+	{
+		key: "config.json",
+		content: JSON.stringify(
+			{ version: "1.0.0", environment: "development" },
+			null,
+			2
+		),
+		contentType: "application/json",
+		customMetadata: { author: "admin", created: "2025-01-15" },
+	},
+
+	// Images folder
+	{
+		key: "images/logo.svg",
+		content:
+			'<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><circle cx="50" cy="50" r="40" fill="orange"/></svg>',
+		contentType: "image/svg+xml",
+	},
+	{
+		key: "images/banner.svg",
+		content:
+			'<svg xmlns="http://www.w3.org/2000/svg" width="300" height="100"><rect width="300" height="100" fill="blue"/></svg>',
+		contentType: "image/svg+xml",
+	},
+	{
+		key: "images/icons/home.svg",
+		content:
+			'<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><path d="M12 3L2 12h3v9h6v-6h2v6h6v-9h3L12 3z"/></svg>',
+		contentType: "image/svg+xml",
+	},
+	{
+		key: "images/icons/settings.svg",
+		content:
+			'<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><circle cx="12" cy="12" r="3"/></svg>',
+		contentType: "image/svg+xml",
+	},
+
+	// Documents folder
+	{
+		key: "documents/report.txt",
+		content:
+			"Annual Report 2024\n\nThis is a sample annual report with important business metrics.",
+		contentType: "text/plain",
+		customMetadata: { department: "finance", year: "2024" },
+	},
+	{
+		key: "documents/notes.md",
+		content:
+			"# Meeting Notes\n\n## Action Items\n- Review budget\n- Update roadmap\n- Schedule follow-up",
+		contentType: "text/markdown",
+	},
+	{
+		key: "documents/data.csv",
+		content: "id,name,value\n1,Alpha,100\n2,Beta,200\n3,Gamma,300",
+		contentType: "text/csv",
+	},
+
+	// Data folder with nested structure
+	{
+		key: "data/users.json",
+		content: JSON.stringify(
+			[
+				{ id: 1, name: "Alice", role: "admin" },
+				{ id: 2, name: "Bob", role: "user" },
+			],
+			null,
+			2
+		),
+		contentType: "application/json",
+	},
+	{
+		key: "data/backup/2024/january.json",
+		content: JSON.stringify({ month: "January", records: 150 }),
+		contentType: "application/json",
+		customMetadata: { backup: "true", period: "2024-01" },
+	},
+	{
+		key: "data/backup/2024/february.json",
+		content: JSON.stringify({ month: "February", records: 175 }),
+		contentType: "application/json",
+		customMetadata: { backup: "true", period: "2024-02" },
+	},
+
+	// Logs folder
+	{
+		key: "logs/access.log",
+		content:
+			"2025-01-15 10:00:00 GET /api/users 200\n2025-01-15 10:01:00 POST /api/login 200\n2025-01-15 10:02:00 GET /api/products 200",
+		contentType: "text/plain",
+	},
+	{
+		key: "logs/error.log",
+		content:
+			"2025-01-15 09:30:00 ERROR Connection timeout\n2025-01-15 09:45:00 ERROR Invalid token",
+		contentType: "text/plain",
+	},
+
+	// Assets with various content types
+	{
+		key: "assets/styles.css",
+		content:
+			"body { font-family: sans-serif; }\n.container { max-width: 1200px; margin: 0 auto; }",
+		contentType: "text/css",
+	},
+	{
+		key: "assets/script.js",
+		content: 'console.log("Hello from R2!");\nfunction init() { return true; }',
+		contentType: "application/javascript",
+	},
+	{
+		key: "assets/template.html",
+		content:
+			"<!DOCTYPE html>\n<html><head><title>Template</title></head><body><h1>Hello</h1></body></html>",
+		contentType: "text/html",
+	},
+];

fixtures/worker-with-resources/worker-b/wrangler.jsonc

@@ -23,6 +23,7 @@
 			},
 		],
 	},
+	"r2_buckets": [{ "bucket_name": "bucket-b", "binding": "BUCKET_B" }],
 	"migrations": [
 		{
 			"new_sqlite_classes": ["WorkerBDurableObject"],

fixtures/worker-with-resources/worker-configuration.d.ts

@@ -1,5 +1,5 @@
 /* eslint-disable */
-// Generated by Wrangler by running `wrangler types --no-include-runtime` (hash: 1af53220e7fe93ac70789822977c3be3)
+// Generated by Wrangler by running `wrangler types --no-include-runtime` (hash: 9b4b1032686eb7f16ed05d3e59c53f88)
 declare namespace Cloudflare {
 	interface GlobalProps {
 		mainModule: typeof import("./src/index");
@@ -8,6 +8,7 @@ declare namespace Cloudflare {
 	interface Env {
 		KV: KVNamespace;
 		KV_WITH_ID: KVNamespace;
+		BUCKET: R2Bucket;
 		DB: D1Database;
 		BACKUP_DB: D1Database;
 		DO: DurableObjectNamespace<import("./src/index").MyDurableObject>;

fixtures/worker-with-resources/wrangler.jsonc

@@ -3,6 +3,12 @@
 	"name": "worker-w-resources",
 	"main": "src/index.ts",
 	"compatibility_date": "2023-05-04",
+	"r2_buckets": [
+		{
+			"bucket_name": "my-bucket",
+			"binding": "BUCKET",
+		},
+	],
 	"kv_namespaces": [
 		{
 			"binding": "KV",

packages/local-explorer-ui/package.json

@@ -36,6 +36,7 @@
 		"@tailwindcss/vite": "^4.0.15",
 		"@tanstack/react-router": "^1.158.0",
 		"immer": "^11.1.4",
+		"pretty-bytes": "^7.1.0",
 		"react": "^19.2.0",
 		"react-dom": "^19.2.0",
 		"tailwindcss": "^4.0.15"

packages/local-explorer-ui/src/__tests__/utils/format.test.ts

@@ -0,0 +1,48 @@
+import { describe, test } from "vitest";
+import { formatDate } from "../../utils/format";
+
+describe("formatDate", () => {
+	test("`undefined` returns '-'", ({ expect }) => {
+		expect(formatDate(undefined)).toBe("-");
+	});
+
+	test("empty string returns '-'", ({ expect }) => {
+		expect(formatDate("")).toBe("-");
+	});
+
+	test("valid ISO date string", ({ expect }) => {
+		expect(formatDate("2025-05-13T01:11:37.000Z")).toBe(
+			"13 May 2025, 01:11:37 UTC"
+		);
+	});
+
+	test("different month (January)", ({ expect }) => {
+		expect(formatDate("2024-01-05T12:30:45.000Z")).toBe(
+			"5 Jan 2024, 12:30:45 UTC"
+		);
+	});
+
+	test("single-digit day (no leading zero)", ({ expect }) => {
+		expect(formatDate("2025-03-01T00:00:00.000Z")).toBe(
+			"1 Mar 2025, 00:00:00 UTC"
+		);
+	});
+
+	test("end of year date", ({ expect }) => {
+		expect(formatDate("2025-12-31T23:59:59.000Z")).toBe(
+			"31 Dec 2025, 23:59:59 UTC"
+		);
+	});
+
+	test("invalid date string returns '-'", ({ expect }) => {
+		expect(formatDate("not-a-date")).toBe("-");
+	});
+
+	test("malformed date string returns '-'", ({ expect }) => {
+		expect(formatDate("2025-13-45")).toBe("-");
+	});
+
+	test("random string returns '-'", ({ expect }) => {
+		expect(formatDate("hello world")).toBe("-");
+	});
+});