@opennextjs/cloudflare 1.17.3 → 1.18.0

package/dist/cli/commands/populate-cache.d.ts

@@ -12,7 +12,7 @@ export type CacheAsset = {
     buildId: string;
 };
 export declare function getCacheAssets(opts: BuildOptions): CacheAsset[];
-type PopulateCacheOptions = {
+export type PopulateCacheOptions = {
     /**
      * Whether to populate the local or remote cache.
      */
@@ -26,9 +26,11 @@ type PopulateCacheOptions = {
      */
     wranglerConfigPath?: string;
     /**
-     * Chunk sizes to use when populating KV cache. Ignored for R2.
+     * Number of concurrent requests when populating the cache.
+     * For KV this is the chunk size passed to `wrangler kv bulk put`.
+     * For R2 this is the number of concurrent requests to the local worker.
      *
-     * @default 25 for KV, 50 for R2
+     * @default 25
      */
     cacheChunkSize?: number;
     /**
@@ -51,4 +53,3 @@ export declare function withPopulateCacheOptions<T extends yargs.Argv>(args: T):
 } & {
     cacheChunkSize: number | undefined;
 }>;
-export {};

package/dist/cli/commands/populate-cache.js

@@ -2,14 +2,19 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { Readable } from "node:stream";
+import { setTimeout } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
 import logger from "@opennextjs/aws/logger.js";
 import { globSync } from "glob";
 import { tqdm } from "ts-tqdm";
+import { unstable_startWorker } from "wrangler";
 import { BINDING_NAME as KV_CACHE_BINDING_NAME, NAME as KV_CACHE_NAME, PREFIX_ENV_NAME as KV_CACHE_PREFIX_ENV_NAME, } from "../../api/overrides/incremental-cache/kv-incremental-cache.js";
 import { BINDING_NAME as R2_CACHE_BINDING_NAME, NAME as R2_CACHE_NAME, PREFIX_ENV_NAME as R2_CACHE_PREFIX_ENV_NAME, } from "../../api/overrides/incremental-cache/r2-incremental-cache.js";
 import { CACHE_DIR as STATIC_ASSETS_CACHE_DIR, NAME as STATIC_ASSETS_CACHE_NAME, } from "../../api/overrides/incremental-cache/static-assets-incremental-cache.js";
 import { computeCacheKey } from "../../api/overrides/internal.js";
 import { BINDING_NAME as D1_TAG_BINDING_NAME, NAME as D1_TAG_NAME, } from "../../api/overrides/tag-cache/d1-next-tag-cache.js";
+import { ensureR2Bucket } from "../utils/ensure-r2-bucket.js";
 import { normalizePath } from "../utils/normalize-path.js";
 import { getEnvFromPlatformProxy, quoteShellMeta } from "./utils/helpers.js";
 import { runWrangler } from "./utils/run-wrangler.js";
@@ -36,8 +41,7 @@ async function populateCacheCommand(target, args) {
 export async function populateCache(buildOpts, config, wranglerConfig, populateCacheOptions, envVars) {
     const { incrementalCache, tagCache } = config.default.override ?? {};
     if (!fs.existsSync(buildOpts.outputDir)) {
-        logger.error("Unable to populate cache: Open Next build not found");
-        process.exit(1);
+        throw new Error("Unable to populate cache: Open Next build not found");
     }
     if (!config.dangerous?.disableIncrementalCache && incrementalCache) {
         const name = await resolveCacheName(incrementalCache);
@@ -106,63 +110,228 @@ export function getCacheAssets(opts) {
     }
     return assets;
 }
+/**
+ * Populates the R2 incremental cache by starting a worker with an R2 binding.
+ *
+ * Flow:
+ * 1. Reads the R2 binding configuration from the wrangler config.
+ * 2. Collects cache assets from the build output.
+ * 3. Starts a worker (via `unstable_startWorker`) with the R2 binding, set to run remotely or locally depending upon the cache target.
+ * 4. Sends individual POST requests to the worker.
+ *
+ * Using a binding bypasses the Cloudflare REST API rate limit that affects `wrangler r2 bulk put`.
+ */
 async function populateR2IncrementalCache(buildOpts, config, populateCacheOptions, envVars) {
-    logger.info("\nPopulating R2 incremental cache...");
+    logger.info(`\nPopulating ${populateCacheOptions.target} R2 incremental cache...`);
     const binding = config.r2_buckets.find(({ binding }) => binding === R2_CACHE_BINDING_NAME);
     if (!binding) {
-        throw new Error(`No R2 binding ${JSON.stringify(R2_CACHE_BINDING_NAME)} found!`);
+        throw new Error(`No R2 binding "${R2_CACHE_BINDING_NAME}" found!`);
     }
-    const bucket = binding.bucket_name;
-    if (!bucket) {
-        throw new Error(`R2 binding ${JSON.stringify(R2_CACHE_BINDING_NAME)} should have a 'bucket_name'`);
+    if (typeof binding.bucket_name !== "string") {
+        throw new Error(`R2 binding "${R2_CACHE_BINDING_NAME}" is missing a bucket_name.`);
     }
+    const bucketName = populateCacheOptions.shouldUsePreviewId && typeof binding.preview_bucket_name === "string"
+        ? binding.preview_bucket_name
+        : binding.bucket_name;
     const prefix = envVars[R2_CACHE_PREFIX_ENV_NAME];
     const assets = getCacheAssets(buildOpts);
-    const objectList = assets.map(({ fullPath, key, buildId, isFetch }) => ({
+    if (assets.length === 0) {
+        logger.info("No cache assets to populate");
+        return;
+    }
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const handlerPath = path.join(currentDir, "../workers/r2-cache.js");
+    const isRemote = populateCacheOptions.target === "remote";
+    if (isRemote) {
+        const result = await ensureR2Bucket(buildOpts.appPath, bucketName, binding.jurisdiction);
+        if (!result.success) {
+            throw new Error(`Failed to provision remote R2 bucket "${bucketName}" for binding "${R2_CACHE_BINDING_NAME}": ${result.error}`);
+        }
+    }
+    // Start a local worker and proxy it to the Cloudflare network when remote mode is enabled.
+    const worker = await unstable_startWorker({
+        name: "open-next-cache-populate",
+        // Prevent it from discovering the project's wrangler config and leaking unrelated bindings.
+        config: "",
+        entrypoint: handlerPath,
+        compatibilityDate: "2026-01-01",
+        bindings: {
+            R2: {
+                type: "r2_bucket",
+                bucket_name: bucketName,
+                jurisdiction: binding.jurisdiction,
+            },
+        },
+        dev: {
+            remote: isRemote,
+            server: { port: 0 },
+            inspector: false,
+            watch: false,
+            liveReload: false,
+            logLevel: "none",
+        },
+    });
+    try {
+        const baseUrl = await worker.url;
+        await sendEntriesToR2Worker({
+            workerUrl: new URL("/populate", baseUrl).href,
+            assets,
+            prefix,
+            maxConcurrency: Math.max(1, populateCacheOptions.cacheChunkSize ?? 25),
+        });
+    }
+    catch (e) {
+        if (isRemote) {
+            throw new Error(`Failed to populate remote R2 bucket "${bucketName}" for binding "${R2_CACHE_BINDING_NAME}": ${e instanceof Error ? e.message : String(e)}`);
+        }
+        else {
+            throw new Error(`Failed to populate the local R2 cache: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    finally {
+        await worker.dispose();
+    }
+    logger.info(`Successfully populated cache with ${assets.length} entries`);
+}
+/**
+ * Sends cache entries to the R2 worker, one entry per request.
+ *
+ * Up to `concurrency` requests are in-flight at any given time.
+ * Retry logic for transient R2 write failures is handled by the worker.
+ *
+ * @param options
+ * @param options.workerUrl - The URL of the local R2 worker's `/populate` endpoint.
+ * @param options.assets - The cache assets to write, as collected by {@link getCacheAssets}.
+ * @param options.prefix - Optional prefix prepended to each R2 key.
+ * @param options.concurrency - Maximum number of concurrent in-flight requests.
+ * @returns Resolves when all entries have been written successfully.
+ * @throws {Error} If any entry fails after all retries or encounters a non-retryable error.
+ */
+async function sendEntriesToR2Worker(options) {
+    const { workerUrl, assets, prefix, maxConcurrency } = options;
+    // Build the list of entries to send (key + filename).
+    // File contents are read lazily in sendEntryToR2Worker to avoid
+    // loading all cache values into memory at once.
+    const entries = assets.map(({ fullPath, key, buildId, isFetch }) => ({
         key: computeCacheKey(key, {
             prefix,
             buildId,
             cacheType: isFetch ? "fetch" : "cache",
         }),
-        file: fullPath,
+        filename: fullPath,
     }));
-    const tempDir = await fsp.mkdtemp(path.join(os.tmpdir(), "open-next-"));
-    const listFile = path.join(tempDir, `r2-bulk-list.json`);
-    fs.writeFileSync(listFile, JSON.stringify(objectList));
-    const concurrency = Math.max(1, populateCacheOptions.cacheChunkSize ?? 50);
-    const jurisdiction = binding.jurisdiction ? `--jurisdiction ${binding.jurisdiction}` : "";
-    const result = runWrangler(buildOpts, [
-        "r2 bulk put",
-        bucket,
-        `--filename ${quoteShellMeta(listFile)}`,
-        `--concurrency ${concurrency}`,
-        jurisdiction,
-    ], {
-        target: populateCacheOptions.target,
-        configPath: populateCacheOptions.wranglerConfigPath,
-        // R2 does not support the environment flag and results in the following error:
-        // Incorrect type for the 'cacheExpiry' field on 'HttpMetadata': the provided value is not of type 'date'.
-        environment: undefined,
-        logging: "error",
-    });
-    fs.rmSync(listFile, { force: true });
-    if (!result.success) {
-        logger.error(`Wrangler r2 bulk put command failed${result.stderr ? `:\n${result.stderr}` : ""}`);
-        process.exit(1);
+    // Use a concurrency-limited loop with a progress bar.
+    // `pending` tracks in-flight promises so we can cap concurrency.
+    const pending = new Set();
+    let concurrency = 1;
+    for (const entry of tqdm(entries)) {
+        const task = sendEntryToR2Worker({
+            workerUrl,
+            key: entry.key,
+            filename: entry.filename,
+        }).finally(() => pending.delete(task));
+        pending.add(task);
+        // If we've reached the concurrency limit, wait for one to finish.
+        if (pending.size >= concurrency) {
+            await Promise.race(pending);
+            // Increase concurrency gradually to avoid overwhelming the worker
+            // with too many requests at once.
+            if (concurrency < maxConcurrency) {
+                concurrency++;
+            }
+        }
+    }
+    await Promise.all(pending);
+}
+class RetryableWorkerError extends Error {
+}
+/**
+ * Sends a single cache entry to the R2 worker.
+ *
+ * The file is streamed from disk and sent as the raw request body.
+ *
+ * @param options
+ * @param options.workerUrl - The URL of the local R2 worker's `/populate` endpoint.
+ * @param options.key - The R2 object key.
+ * @param options.filename - Path to the cache file on disk. Read at send time to avoid holding all values in memory.
+ * @throws {Error} If the worker reports a failure.
+ */
+async function sendEntryToR2Worker(options) {
+    const { workerUrl, key, filename } = options;
+    const CLIENT_RETRY_ATTEMPTS = 5;
+    const CLIENT_RETRY_BASE_DELAY_MS = 250;
+    for (let attempt = 0; attempt < CLIENT_RETRY_ATTEMPTS; attempt++) {
+        try {
+            let response;
+            try {
+                response = await fetch(workerUrl, {
+                    method: "POST",
+                    headers: {
+                        "x-opennext-cache-key": key,
+                        "content-length": fs.statSync(filename).size.toString(),
+                    },
+                    body: Readable.toWeb(fs.createReadStream(filename)),
+                    signal: AbortSignal.timeout(60_000),
+                    // @ts-expect-error - `duplex` is required for streaming request bodies in Node.js
+                    duplex: "half",
+                });
+            }
+            catch (e) {
+                throw new RetryableWorkerError(`Failed to send request to R2 worker: ${e instanceof Error ? e.message : String(e)}`, {
+                    cause: e,
+                });
+            }
+            const body = await response.text();
+            let result;
+            try {
+                result = JSON.parse(body);
+            }
+            catch (e) {
+                if (body.includes("Worker exceeded resource limits")) {
+                    throw new RetryableWorkerError("Worker exceeded resource limits", { cause: e });
+                }
+                if (response.status >= 500) {
+                    throw new RetryableWorkerError(`Worker returned a ${response.status} ${response.statusText} response`, { cause: e });
+                }
+                throw new Error(`Unexpected ${response.status} response from R2 worker: ${body}`, {
+                    cause: e,
+                });
+            }
+            if (!result.success && response.status >= 500) {
+                throw new RetryableWorkerError(result.error);
+            }
+            if (!result.success) {
+                throw new Error(`Failed to write "${key}" to R2: ${result.error}`);
+            }
+            return;
+        }
+        catch (e) {
+            if (e instanceof RetryableWorkerError && attempt < CLIENT_RETRY_ATTEMPTS - 1) {
+                logger.error(`Attempt ${attempt + 1} to write "${key}" failed with a retryable error: ${e.message}. Retrying...`);
+                await setTimeout(CLIENT_RETRY_BASE_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+            throw new Error(`Failed to write "${key}" to R2 after ${CLIENT_RETRY_ATTEMPTS} attempts`, {
+                cause: e,
+            });
+        }
     }
-    logger.info(`Successfully populated cache with ${assets.length} assets`);
 }
 async function populateKVIncrementalCache(buildOpts, config, populateCacheOptions, envVars) {
-    logger.info("\nPopulating KV incremental cache...");
+    logger.info(`\nPopulating ${populateCacheOptions.target} KV incremental cache...`);
     const binding = config.kv_namespaces.find(({ binding }) => binding === KV_CACHE_BINDING_NAME);
     if (!binding) {
-        throw new Error(`No KV binding ${JSON.stringify(KV_CACHE_BINDING_NAME)} found!`);
+        throw new Error(`No KV binding "${KV_CACHE_BINDING_NAME}" found!`);
     }
     const prefix = envVars[KV_CACHE_PREFIX_ENV_NAME];
     const assets = getCacheAssets(buildOpts);
+    if (assets.length === 0) {
+        logger.info("No cache assets to populate");
+        return;
+    }
     const chunkSize = Math.max(1, populateCacheOptions.cacheChunkSize ?? 25);
     const totalChunks = Math.ceil(assets.length / chunkSize);
-    logger.info(`Inserting ${assets.length} assets to KV in chunks of ${chunkSize}`);
+    logger.info(`Inserting ${assets.length} assets to ${populateCacheOptions.target} KV in chunks of ${chunkSize}`);
     const tempDir = await fsp.mkdtemp(path.join(os.tmpdir(), "open-next-"));
     for (const i of tqdm(Array.from({ length: totalChunks }, (_, i) => i))) {
         const chunkPath = path.join(tempDir, `cache-chunk-${i}.json`);
@@ -190,17 +359,16 @@ async function populateKVIncrementalCache(buildOpts, config, populateCacheOption
         });
         fs.rmSync(chunkPath, { force: true });
         if (!result.success) {
-            logger.error(`Wrangler kv bulk put command failed${result.stderr ? `:\n${result.stderr}` : ""}`);
-            process.exit(1);
+            throw new Error(`Wrangler kv bulk put command failed${result.stderr ? `:\n${result.stderr}` : ""}`);
         }
     }
-    logger.info(`Successfully populated cache with ${assets.length} assets`);
+    logger.info(`Successfully populated cache with ${assets.length} entries`);
 }
 function populateD1TagCache(buildOpts, config, populateCacheOptions) {
     logger.info("\nCreating D1 table if necessary...");
     const binding = config.d1_databases.find(({ binding }) => binding === D1_TAG_BINDING_NAME);
     if (!binding) {
-        throw new Error(`No D1 binding ${JSON.stringify(D1_TAG_BINDING_NAME)} found!`);
+        throw new Error(`No D1 binding "${D1_TAG_BINDING_NAME}" found!`);
     }
     const result = runWrangler(buildOpts, [
         "d1 execute",
@@ -214,8 +382,7 @@ function populateD1TagCache(buildOpts, config, populateCacheOptions) {
         logging: "error",
     });
     if (!result.success) {
-        logger.error(`Wrangler d1 execute command failed${result.stderr ? `:\n${result.stderr}` : ""}`);
-        process.exit(1);
+        throw new Error(`Wrangler d1 execute command failed${result.stderr ? `:\n${result.stderr}` : ""}`);
     }
     logger.info("\nSuccessfully created D1 table");
 }

package/dist/cli/utils/create-wrangler-config.js

@@ -1,12 +1,9 @@
 import assert from "node:assert";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { findPackagerAndRoot } from "@opennextjs/aws/build/helper.js";
-import Cloudflare from "cloudflare";
 import { parse, stringify } from "comment-json";
 import { getPackageTemplatesDirPath } from "../../utils/get-package-templates-dir-path.js";
-import { runWrangler } from "../commands/utils/run-wrangler.js";
-import { askAccountSelection } from "./ask-account-selection.js";
+import { ensureR2Bucket } from "./ensure-r2-bucket.js";
 /**
  * Gets the path to the Wrangler configuration file if it exists.
  *
@@ -49,7 +46,7 @@ export async function createWranglerConfigFile(projectDir, defaultCompatDate = "
     assert("bucket_name" in wranglerConfig.r2_buckets[0] &&
         typeof wranglerConfig.r2_buckets[0].bucket_name === "string");
     const bucketName = wranglerConfig.r2_buckets[0].bucket_name;
-    const { success: cachingEnabled } = await maybeCreateR2Bucket(projectDir, bucketName);
+    const { success: cachingEnabled } = await ensureR2Bucket(projectDir, bucketName);
     if (!cachingEnabled) {
         delete wranglerConfig.r2_buckets;
     }
@@ -114,131 +111,3 @@ async function getLatestCompatDate() {
         /* empty */
     }
 }
-/**
- * Gets the authentication credentials for Cloudflare API calls.
- *
- * Uses `wrangler auth token --json` which checks the following sources in order:
- * 1. CLOUDFLARE_API_TOKEN environment variable
- * 2. CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL environment variables
- * 3. OAuth token from `wrangler login`
- *
- * @param options The build options containing packager and monorepo root
- * @returns The auth credentials if available, undefined otherwise
- */
-function getAuthCredentials(options) {
-    const result = runWrangler(options, ["auth", "token", "--json"], { logging: "none" });
-    if (!result.success) {
-        return undefined;
-    }
-    try {
-        const json = JSON.parse(result.stdout);
-        if (json.type === "api_key") {
-            return { type: "api_key", apiKey: json.key, apiEmail: json.email };
-        }
-        // Both "oauth" and "api_token" types have a token field
-        if (json.token) {
-            return { type: "token", token: json.token };
-        }
-    }
-    catch {
-        /* empty */
-    }
-    return undefined;
-}
-/**
- * Gets the account ID for Cloudflare API calls.
- *
- * Tries the following sources in order:
- * 1. CLOUDFLARE_ACCOUNT_ID or CF_ACCOUNT_ID environment variable
- * 2. List accounts using the SDK and return the first one
- *
- * @param client The Cloudflare SDK client
- * @returns The account ID if available, undefined otherwise
- */
-async function getAccountId(client) {
-    if (process.env.CLOUDFLARE_ACCOUNT_ID || process.env.CF_ACCOUNT_ID) {
-        return process.env.CLOUDFLARE_ACCOUNT_ID || process.env.CF_ACCOUNT_ID;
-    }
-    try {
-        const accountsList = await client.accounts.list();
-        const accounts = [];
-        for await (const account of accountsList) {
-            accounts.push({ id: account.id, name: account.name });
-        }
-        if (accounts.length === 0) {
-            return undefined;
-        }
-        if (accounts.length === 1 && accounts[0]) {
-            return accounts[0].id;
-        }
-        return await askAccountSelection(accounts);
-    }
-    catch {
-        /* empty */
-    }
-    return undefined;
-}
-/**
- * Attempts to log in to Cloudflare via wrangler.
- *
- * @param options The build options containing packager and monorepo root
- * @returns true if login was successful, false otherwise
- */
-function wranglerLogin(options) {
-    const result = runWrangler(options, ["login"], { logging: "all" });
-    return result.success;
-}
-/**
- * Creates an R2 bucket.
- *
- * If no auth credentials are available, falls back to wrangler login for OAuth authentication.
- *
- * @param projectDir The project directory to detect the package manager
- * @param bucketName The name of the R2 bucket to create
- * @returns An object indicating success with the bucket name, or failure
- */
-async function maybeCreateR2Bucket(projectDir, bucketName) {
-    try {
-        const { packager, root: monorepoRoot } = findPackagerAndRoot(projectDir);
-        const options = { packager, monorepoRoot };
-        let authCredentials = getAuthCredentials(options);
-        // If no credentials available, fall back to wrangler login
-        if (!authCredentials) {
-            const loginSuccess = wranglerLogin(options);
-            if (!loginSuccess) {
-                return { success: false };
-            }
-            // Get credentials after login
-            authCredentials = getAuthCredentials(options);
-            if (!authCredentials) {
-                return { success: false };
-            }
-        }
-        const client = authCredentials.type === "api_key"
-            ? new Cloudflare({ apiKey: authCredentials.apiKey, apiEmail: authCredentials.apiEmail })
-            : new Cloudflare({ apiToken: authCredentials.token });
-        const accountId = await getAccountId(client);
-        if (!accountId) {
-            return { success: false };
-        }
-        // Check if bucket already exists
-        try {
-            await client.r2.buckets.get(bucketName, { account_id: accountId });
-            // Bucket exists
-            return { success: true, bucketName };
-        }
-        catch (error) {
-            if (!(error instanceof Cloudflare.NotFoundError)) {
-                return { success: false };
-            }
-        }
-        await client.r2.buckets.create({
-            account_id: accountId,
-            name: bucketName,
-        });
-        return { success: true, bucketName };
-    }
-    catch {
-        return { success: false };
-    }
-}

package/dist/cli/utils/ensure-r2-bucket.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Creates an R2 bucket if it doesn't already exist
+ *
+ * If no auth credentials are available, falls back to wrangler login for OAuth authentication.
+ *
+ * @param projectDir The project directory to detect the package manager
+ * @param bucketName The name of the R2 bucket to create
+ * @returns An object indicating success with the bucket name, or failure
+ */
+export declare function ensureR2Bucket(projectDir: string, bucketName: string, jurisdiction?: string): Promise<{
+    success: true;
+    bucketName: string;
+} | {
+    success: false;
+    error: string;
+}>;

package/dist/cli/utils/ensure-r2-bucket.js

@@ -0,0 +1,144 @@
+import { findPackagerAndRoot } from "@opennextjs/aws/build/helper.js";
+import Cloudflare from "cloudflare";
+import { runWrangler } from "../commands/utils/run-wrangler.js";
+import { askAccountSelection } from "./ask-account-selection.js";
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Gets the authentication credentials for Cloudflare API calls.
+ *
+ * Uses `wrangler auth token --json` which checks the following sources in order:
+ * 1. CLOUDFLARE_API_TOKEN environment variable
+ * 2. CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL environment variables
+ * 3. OAuth token from `wrangler login`
+ *
+ * @param options The build options containing packager and monorepo root
+ * @returns The auth credentials if available, undefined otherwise
+ */
+function getAuthCredentials(options) {
+    const result = runWrangler(options, ["auth", "token", "--json"], { logging: "none" });
+    if (!result.success) {
+        return undefined;
+    }
+    try {
+        const json = JSON.parse(result.stdout);
+        if (json.type === "api_key") {
+            return { type: "api_key", apiKey: json.key, apiEmail: json.email };
+        }
+        // Both "oauth" and "api_token" types have a token field
+        if (json.token) {
+            return { type: "token", token: json.token };
+        }
+    }
+    catch {
+        /* empty */
+    }
+    return undefined;
+}
+/**
+ * Gets the account ID for Cloudflare API calls.
+ *
+ * Tries the following sources in order:
+ * 1. CLOUDFLARE_ACCOUNT_ID or CF_ACCOUNT_ID environment variable
+ * 2. List accounts using the SDK and return the first one
+ *
+ * @param client The Cloudflare SDK client
+ * @returns The account ID if available, undefined otherwise
+ */
+async function getAccountId(client) {
+    if (process.env.CLOUDFLARE_ACCOUNT_ID || process.env.CF_ACCOUNT_ID) {
+        return process.env.CLOUDFLARE_ACCOUNT_ID || process.env.CF_ACCOUNT_ID;
+    }
+    try {
+        const accountsList = await client.accounts.list();
+        const accounts = [];
+        for await (const account of accountsList) {
+            accounts.push({ id: account.id, name: account.name });
+        }
+        if (accounts.length === 0) {
+            return undefined;
+        }
+        if (accounts.length === 1 && accounts[0]) {
+            return accounts[0].id;
+        }
+        return await askAccountSelection(accounts);
+    }
+    catch {
+        /* empty */
+    }
+    return undefined;
+}
+/**
+ * Attempts to log in to Cloudflare via wrangler.
+ *
+ * @param options The build options containing packager and monorepo root
+ * @returns true if login was successful, false otherwise
+ */
+function wranglerLogin(options) {
+    const result = runWrangler(options, ["login"], { logging: "all" });
+    return result.success;
+}
+/**
+ * Creates an R2 bucket if it doesn't already exist
+ *
+ * If no auth credentials are available, falls back to wrangler login for OAuth authentication.
+ *
+ * @param projectDir The project directory to detect the package manager
+ * @param bucketName The name of the R2 bucket to create
+ * @returns An object indicating success with the bucket name, or failure
+ */
+export async function ensureR2Bucket(projectDir, bucketName, jurisdiction) {
+    try {
+        const { packager, root: monorepoRoot } = findPackagerAndRoot(projectDir);
+        const options = { packager, monorepoRoot };
+        let authCredentials = getAuthCredentials(options);
+        // If no credentials available, fall back to wrangler login
+        if (!authCredentials) {
+            const loginSuccess = wranglerLogin(options);
+            if (!loginSuccess) {
+                return { success: false, error: "wrangler login failed" };
+            }
+            // Get credentials after login
+            authCredentials = getAuthCredentials(options);
+            if (!authCredentials) {
+                return { success: false, error: "Could not determine Cloudflare auth credentials after login" };
+            }
+        }
+        const client = authCredentials.type === "api_key"
+            ? new Cloudflare({ apiKey: authCredentials.apiKey, apiEmail: authCredentials.apiEmail })
+            : new Cloudflare({ apiToken: authCredentials.token });
+        const accountId = await getAccountId(client);
+        if (!accountId) {
+            return { success: false, error: "Could not determine Cloudflare account ID" };
+        }
+        // Check if bucket already exists
+        try {
+            await client.r2.buckets.get(bucketName, {
+                account_id: accountId,
+                // @ts-expect-error Let the API handle validation and potential errors for unsupported jurisdictions
+                jurisdiction,
+            });
+            // Bucket exists
+            return { success: true, bucketName };
+        }
+        catch (error) {
+            if (!(error instanceof Cloudflare.NotFoundError)) {
+                return {
+                    success: false,
+                    error: `Failed to check whether bucket exists: ${getErrorMessage(error)}`,
+                };
+            }
+        }
+        await client.r2.buckets.create({
+            account_id: accountId,
+            name: bucketName,
+            // @ts-expect-error Let the API handle validation and potential errors for unsupported jurisdictions
+            jurisdiction,
+        });
+        return { success: true, bucketName };
+    }
+    catch (error) {
+        return { success: false, error: getErrorMessage(error) };
+    }
+}

package/dist/cli/workers/r2-cache-types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared types and error codes for the R2 cache worker and its caller.
+ */
+/** The R2 bucket binding is not configured in the worker environment. */
+export declare const ERR_BINDING_NOT_FOUND = "ERR_BINDING_NOT_FOUND";
+/** The request is missing required cache metadata or body. */
+export declare const ERR_INVALID_REQUEST = "ERR_INVALID_REQUEST";
+/** The R2 put operation failed. */
+export declare const ERR_WRITE_FAILED = "ERR_WRITE_FAILED";
+export type ErrorCode = typeof ERR_BINDING_NOT_FOUND | typeof ERR_INVALID_REQUEST | typeof ERR_WRITE_FAILED;
+/** Successful response from the worker. */
+export interface R2SuccessResponse {
+    success: true;
+}
+/** Error response from the worker, includes an error message and a typed code. */
+export interface R2ErrorResponse {
+    success: false;
+    error: string;
+    code: ErrorCode;
+}
+/** Union of all possible responses from the worker. */
+export type R2Response = R2SuccessResponse | R2ErrorResponse;
+export interface CachePopulateEnv {
+    R2?: R2Bucket;
+}

package/dist/cli/workers/r2-cache-types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types and error codes for the R2 cache worker and its caller.
+ */
+/** The R2 bucket binding is not configured in the worker environment. */
+export const ERR_BINDING_NOT_FOUND = "ERR_BINDING_NOT_FOUND";
+/** The request is missing required cache metadata or body. */
+export const ERR_INVALID_REQUEST = "ERR_INVALID_REQUEST";
+/** The R2 put operation failed. */
+export const ERR_WRITE_FAILED = "ERR_WRITE_FAILED";

package/dist/cli/workers/r2-cache.d.ts

@@ -0,0 +1,28 @@
+/**
+ * This worker writes a cache entry to R2.
+ *
+ * It handles POST requests to /populate with:
+ * - `x-opennext-cache-key`: the R2 object key (header, required).
+ * - request body: the cache value to store (required).
+ *
+ * The worker validates the R2 binding and request body, then writes the entry
+ * to R2.
+ *
+ * This is used by the `populate-cache` command to bypass REST API rate limits when populating large caches.
+ */
+import { type CachePopulateEnv } from "./r2-cache-types.js";
+/**
+ * Worker fetch handler.
+ *
+ * Routes `POST /populate` to the cache population logic.
+ * Validates the R2 binding, request metadata, and request body, then writes the entry to R2.
+ *
+ * Response format:
+ * - 200 with `{ success: true }` on success.
+ * - 4xx/5xx with `{ success: false, error, code }` on failure.
+ * - 404 for unmatched routes.
+ */
+declare const _default: {
+    fetch(request: Request, env: CachePopulateEnv): Promise<Response>;
+};
+export default _default;

package/dist/cli/workers/r2-cache.js

@@ -0,0 +1,61 @@
+/**
+ * This worker writes a cache entry to R2.
+ *
+ * It handles POST requests to /populate with:
+ * - `x-opennext-cache-key`: the R2 object key (header, required).
+ * - request body: the cache value to store (required).
+ *
+ * The worker validates the R2 binding and request body, then writes the entry
+ * to R2.
+ *
+ * This is used by the `populate-cache` command to bypass REST API rate limits when populating large caches.
+ */
+import { ERR_BINDING_NOT_FOUND, ERR_INVALID_REQUEST, ERR_WRITE_FAILED, } from "./r2-cache-types.js";
+/**
+ * Worker fetch handler.
+ *
+ * Routes `POST /populate` to the cache population logic.
+ * Validates the R2 binding, request metadata, and request body, then writes the entry to R2.
+ *
+ * Response format:
+ * - 200 with `{ success: true }` on success.
+ * - 4xx/5xx with `{ success: false, error, code }` on failure.
+ * - 404 for unmatched routes.
+ */
+export default {
+    async fetch(request, env) {
+        const url = new URL(request.url);
+        if (request.method !== "POST" || url.pathname !== "/populate") {
+            return new Response("Not found", { status: 404 });
+        }
+        // Verify the R2 binding exists before processing the request.
+        const r2 = env.R2;
+        if (!r2) {
+            return Response.json({
+                success: false,
+                error: 'R2 binding "R2" is not configured',
+                code: ERR_BINDING_NOT_FOUND,
+            }, { status: 500 });
+        }
+        const key = request.headers.get("x-opennext-cache-key");
+        if (!key || request.body === null) {
+            return Response.json({
+                success: false,
+                error: "Request must include x-opennext-cache-key header and a body",
+                code: ERR_INVALID_REQUEST,
+            }, { status: 400 });
+        }
+        try {
+            await r2.put(key, request.body);
+            return Response.json({ success: true }, { status: 200 });
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            return Response.json({
+                success: false,
+                error: `Failed to write key "${key}": ${detail}`,
+                code: ERR_WRITE_FAILED,
+            }, { status: 500 });
+        }
+    },
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opennextjs/cloudflare",
   "description": "Cloudflare builder for next apps",
-  "version": "1.17.3",
+  "version": "1.18.0",
   "type": "module",
   "bin": {
     "opennextjs-cloudflare": "dist/cli/index.js"