Hono R2 Integration

Hono + Cloudflare R2 Integration Skill

Purpose

You are a specialized assistant for using Cloudflare R2 (S3-compatible object storage) inside a Hono + TypeScript app running on Cloudflare Workers / Pages.

Use this skill to:

• Wire R2 bucket bindings into a Hono app (c.env.BUCKET)
• Design upload/download/delete flows from Hono routes
• Structure storage service modules on top of R2
• Handle content types, metadata, and folder-like key prefixes
• Implement presigned URL-style access patterns where appropriate
• Work safely within Workers constraints (streaming, body limits)

Do not use this skill for:

• Hono app scaffolding → use hono-app-scaffold
• D1/database access → use hono-d1-integration
• Frontend file handling/UI → use frontend/Next skills

If CLAUDE.md exists, obey its rules for bucket naming, storage paths, and access patterns.

When To Apply This Skill

Trigger this skill when the user asks for things like:

• “Use R2 to store files for this Hono API.”
• “Add upload/download endpoints backed by R2.”
• “Serve user avatars or documents from R2 in a Worker.”
• “Organize stored files by user/tenant/date.”
• “Refactor my raw R2 calls into a clean service.”

Avoid this skill when:

• Storage is not R2 (e.g., S3, Supabase Storage) for this service.
• The project doesn’t run on Cloudflare Workers/Pages.

Runtime & Binding Assumptions

Assume:

• App runs on Cloudflare Workers or Pages Functions.

• R2 is configured as a binding in wrangler.toml, e.g.:

  [[r2_buckets]]
  binding = "BUCKET"
  bucket_name = "my-bucket"
  preview_bucket_name = "my-bucket-dev"
  

• In code, the bucket is available as c.env.BUCKET and has type R2Bucket.

We type Env and encapsulate R2 access in services where possible.

Project Structure

This skill expects or creates something like:

src/
  app.ts
  index.ts
  routes/
    v1/
      upload.routes.ts
      files.routes.ts
  storage/
    r2-client.ts       # helpers & Env typings
    file-storage.service.ts
  types/
    env.d.ts           # Env interface with BUCKET binding

Adjust paths to match the existing project.

Typing Env and R2 Binding

Define Env with an R2 bucket binding:

// src/types/env.d.ts
export interface Env {
  BUCKET: R2Bucket;
  // other bindings (DB, KV, etc)
}

Integrate with Hono context typing:

// src/types/app.ts
import type { Env } from "./env";

export type AppContext = {
  Bindings: Env;
};

Use when creating the app:

import { Hono } from "hono";
import type { AppContext } from "./types/app";

export const app = new Hono<AppContext>();

This skill should ensure c.env.BUCKET is fully typed.

R2 Helper Module

Create a small helper to access the bucket and wrap common operations:

// src/storage/r2-client.ts
import type { Env } from "../types/env";

export function getBucket(env: Env): R2Bucket {
  return env.BUCKET;
}

export type R2ObjectInfo = {
  key: string;
  size: number;
  uploaded: string;
  etag?: string;
  httpEtag?: string;
  checksums?: Record<string, string>;
};

This module can be extended with helper functions such as putObject, getObject, deleteObject etc., but often we call bucket methods directly from a service class.

Storage Service Layer

Create a service that receives Env and encapsulates R2 operations.

// src/storage/file-storage.service.ts
import type { Env } from "../types/env";
import { getBucket } from "./r2-client";

export class FileStorageService {
  constructor(private env: Env) {}

  private bucket() {
    return getBucket(this.env);
  }

  buildKey(prefix: string, filename: string): string {
    // Example: "users/<prefix>/<filename>"
    return `${prefix}/${filename}`;
  }

  async uploadObject(
    prefix: string,
    filename: string,
    body: ReadableStream | ArrayBuffer | Uint8Array,
    contentType?: string,
  ) {
    const key = this.buildKey(prefix, filename);
    const bucket = this.bucket();

    const putResult = await bucket.put(key, body, {
      httpMetadata: contentType ? { contentType } : undefined,
    });

    return { key, etag: putResult?.etag };
  }

  async getObject(key: string) {
    const bucket = this.bucket();
    const obj = await bucket.get(key);
    if (!obj) return null;

    return {
      key,
      body: obj.body,
      size: obj.size,
      uploaded: obj.uploaded,
      httpMetadata: obj.httpMetadata,
    };
  }

  async deleteObject(key: string) {
    const bucket = this.bucket();
    await bucket.delete(key);
  }

  async list(prefix: string) {
    const bucket = this.bucket();
    const res = await bucket.list({ prefix });
    return res.objects;
  }
}

This skill should:

• Encourage key naming conventions: e.g., users/<userId>/avatars/<file> or tenants/<tenantId>/...
• Use Stream bodies (obj.body) correctly for Workers.

Hono Routes: Upload & Download

Upload Route Example

Supports multipart/form-data uploads using c.req.parseBody() or c.req.formData() depending on Hono version.

// src/routes/v1/upload.routes.ts
import { Hono } from "hono";
import type { AppContext } from "../../types/app";
import { FileStorageService } from "../../storage/file-storage.service";

export function uploadRoutes() {
  const app = new Hono<AppContext>();

  app.post("/files", async (c) => {
    const formData = await c.req.formData();
    const file = formData.get("file");

    if (!(file instanceof File)) {
      return c.json({ message: "file field is required" }, 400);
    }

    const userId = "anonymous"; // or from auth middleware, e.g. c.get("user").id

    const storage = new FileStorageService(c.env);
    const key = storage.buildKey(`users/${userId}`, file.name);

    const arrayBuffer = await file.arrayBuffer();

    await storage.uploadObject(`users/${userId}`, file.name, arrayBuffer, file.type);

    return c.json({ key }, 201);
  });

  return app;
}

This skill should:

• Recommend secure naming (no direct user input as raw key without sanitizing).
• Encourage deriving prefixes from authenticated user/tenant.

Download Route Example

// src/routes/v1/files.routes.ts
import { Hono } from "hono";
import type { AppContext } from "../../types/app";
import { FileStorageService } from "../../storage/file-storage.service";

export function filesRoutes() {
  const app = new Hono<AppContext>();

  app.get("/files/:key", async (c) => {
    const keyParam = c.req.param("key");
    // You may want to decode / validate this; often we pass encoded keys or IDs instead
    const key = decodeURIComponent(keyParam);

    const storage = new FileStorageService(c.env);
    const obj = await storage.getObject(key);

    if (!obj) {
      return c.json({ message: "Not found" }, 404);
    }

    const headers: Record<string, string> = {};
    if (obj.httpMetadata?.contentType) {
      headers["Content-Type"] = obj.httpMetadata.contentType;
    }

    return new Response(obj.body, {
      status: 200,
      headers,
    });
  });

  return app;
}

Important: Exposing raw keys in URLs may not be ideal; many apps use an opaque ID that maps to a key. This skill can recommend a mapping layer if needed.

Presigned-URL Style Patterns (Optional)

R2 doesn’t provide S3-style presigned URLs in the same way out of the box, but you can:

• Generate a short-lived signed token (JWT) containing the key + permission.
• Use a Hono route to validate that token and stream the object.

Example idea:

// pseudo-code
app.get("/download/:token", async (c) => {
  const token = c.req.param("token");
  const { key } = await verifyDownloadToken(token); // JWT or similar
  const storage = new FileStorageService(c.env);
  const obj = await storage.getObject(key);
  // stream object if valid
});

This skill should:

• Suggest this pattern when the user wants “presigned URLs” behavior.
• Defer actual token signing/verification to an auth/signing skill.

Folder-Like Organization & Multi-Tenancy

This skill should help you design key schemes like:

• Per-user:
  • users/<userId>/avatars/<filename>
  • users/<userId>/documents/<id>.pdf
• Per-tenant:
  • tenants/<tenantId>/exports/<timestamp>.json
• Public vs private:
  • public/<whatever> vs private/<userId>/<file>

It should:

• Encourage not leaking sensitive identifiers where not needed.
• Suggest using random IDs or hashed filenames for users’ private content.

Integration with Auth

When hono-authentication is present, this skill can:

• Use c.get("user") to determine userId or roles.
• Enforce access control for:
  • Upload (who can write to which prefixes)
  • Download (who can read which keys)

Example pattern:

const user = c.get("user");
if (!user) return c.json({ message: "Unauthorized" }, 401);

// build prefix from user.id
const prefix = `users/${user.id}`;

Local Development & Testing

This skill may recommend:

• Using R2’s local dev via wrangler dev and preview buckets.
• Mocking R2Bucket methods in unit tests:

const mockBucket: Partial<R2Bucket> = {
  put: jest.fn().mockResolvedValue({ etag: "etag" } as any),
  get: jest.fn().mockResolvedValue(null),
  list: jest.fn().mockResolvedValue({ objects: [] } as any),
  delete: jest.fn().mockResolvedValue(undefined),
};

• For integration tests, run wrangler dev and hit endpoints that talk to R2 directly.

Error Handling & Limits

This skill must consider:

• File size limits; large uploads should be constrained (and perhaps chunked in more advanced setups).
• Graceful error handling when bucket operations fail:

try {
  await bucket.put(key, body);
} catch (err) {
  console.error("R2 upload failed:", err);
  return c.json({ message: "Upload failed" }, 500);
}

• Avoid echoing internal R2 errors directly to clients.

Example Prompts That Should Use This Skill

• “Store user uploads in R2 from this Hono API.”
• “Add endpoints to upload and download files using Cloudflare R2.”
• “Organize R2 keys by user/tenant in my Workers app.”
• “Refactor my R2 calls into a reusable service in Hono.”
• “Implement a safe download route for R2-stored documents.”

For these tasks, rely on this skill to build a clean, typed, and secure R2 integration inside your Hono + Cloudflare Workers/Pages application.