feat: add platformProxy option to configure getPlatformProxy (#12011)

* feat: allow passing config to getPlatformProxy via platformProxy option

* remove platformProxy default value

* Update packages/adapter-cloudflare-workers/index.js

* Update 60-adapter-cloudflare.md

* Update 60-adapter-cloudflare.md

* Update 70-adapter-cloudflare-workers.md

* Update index.d.ts

* Update packages/adapter-cloudflare-workers/index.d.ts

* Update packages/adapter-cloudflare-workers/index.js

* Update documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md

* Update documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md

* Update documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md

* Update documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md

* Update 60-adapter-cloudflare.md

* Update documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md

* Update documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md

---------

Co-authored-by: Tee Ming <[email protected]>

Author: vnphanquang

.changeset/tough-dolphins-kick.md

@@ -0,0 +1,6 @@
+---
+"@sveltejs/adapter-cloudflare-workers": minor
+"@sveltejs/adapter-cloudflare": minor
+---
+
+feat: support platform emulation configuration via the `platformProxy` adapter option

documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md

@@ -28,15 +28,20 @@ export default {
 			routes: {
 				include: ['/*'],
 				exclude: ['<all>']
-			}
+			},
+      platformProxy: {
+        persist: './your-custom-path'
+      }
 		})
 	}
 };
 ```
 
 ## Options
 
-The `routes` option allows you to customise the [`_routes.json`](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file) file generated by `adapter-cloudflare`.
+### routes
+
+Allows you to customise the [`_routes.json`](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file) file generated by `adapter-cloudflare`.
 
 - `include` defines routes that will invoke a function, and defaults to `['/*']`
 - `exclude` defines routes that will _not_ invoke a function — this is a faster and cheaper way to serve your app's static assets. This array can include the following special values:
@@ -47,6 +52,10 @@ The `routes` option allows you to customise the [`_routes.json`](https://develop
 
 You can have up to 100 `include` and `exclude` rules combined. Generally you can omit the `routes` options, but if (for example) your `<prerendered>` paths exceed that limit, you may find it helpful to manually create an `exclude` list that includes `'/articles/*'` instead of the auto-generated `['/articles/foo', '/articles/bar', '/articles/baz', ...]`.
 
+### platformProxy
+
+Preferences for the emulated `platform.env` local bindings. See the [getPlatformProxy](https://developers.cloudflare.com/workers/wrangler/api/#syntax) Wrangler API documentation for a full list of options.
+
 ## Deployment
 
 Please follow the [Get Started Guide](https://developers.cloudflare.com/pages/get-started) for Cloudflare Pages to begin.
@@ -90,7 +99,7 @@ export {};
 
 ### Testing Locally
 
-Cloudflare Workers specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on the configuration in your `wrangler.toml` file and are used to populate `platform.env` during development.
+Cloudflare Workers specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on the configuration in your `wrangler.toml` file and are used to populate `platform.env` during development and preview. Use the adapter config [`platformProxy` option](#options-platformproxy) to change your preferences for the bindings.
 
 For testing the build, you should use [wrangler](https://developers.cloudflare.com/workers/cli-wrangler) **version 3**. Once you have built your site, run `wrangler pages dev .svelte-kit/cloudflare`.
 

documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md

@@ -17,11 +17,26 @@ import adapter from '@sveltejs/adapter-cloudflare-workers';
 
 export default {
 	kit: {
-		adapter: adapter()
+		adapter: adapter({
+      config: '<your-wrangler-name>.toml',
+      platformProxy: {
+        persist: './your-custom-path'
+      }
+    })
 	}
 };
 ```
 
+## Options
+
+### config
+
+Path to your custom `wrangler.toml` config file.
+
+### platformProxy
+
+Preferences for the emulated `platform.env` local bindings. See the [getPlatformProxy](https://developers.cloudflare.com/workers/wrangler/api/#syntax) Wrangler API documentation for a full list of options.
+
 ## Basic Configuration
 
 This adapter expects to find a [wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It should look something like this:
@@ -63,19 +78,7 @@ wrangler deploy
 
 ## Custom config
 
-If you would like to use a config file other than `wrangler.toml`, you can do like so:
-
-```js
-// @errors: 2307
-/// file: svelte.config.js
-import adapter from '@sveltejs/adapter-cloudflare-workers';
-
-export default {
-	kit: {
-		adapter: adapter({ config: '<your-wrangler-name>.toml' })
-	}
-};
-```
+If you would like to use a config file other than `wrangler.toml` you can specify so using the [`config` option](#options-config).
 
 If you would like to enable [Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs/#enable-nodejs-from-the-cloudflare-dashboard), you can add "nodejs_compat" flag to `wrangler.toml`:
 
@@ -117,7 +120,7 @@ export {};
 
 ### Testing Locally
 
-Cloudflare Workers specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on the configuration in your `wrangler.toml` file and are used to populate `platform.env` during development.
+Cloudflare Workers specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on the configuration in your `wrangler.toml` file and are used to populate `platform.env` during development and preview. Use the adapter config [`platformProxy` option](#options-platformproxy) to change your preferences for the bindings.
 
 For testing the build, you should use [wrangler](https://developers.cloudflare.com/workers/cli-wrangler) **version 3**. Once you have built your site, run `wrangler dev`.
 

packages/adapter-cloudflare-workers/index.d.ts

@@ -1,8 +1,14 @@
 import { Adapter } from '@sveltejs/kit';
 import './ambient.js';
+import { GetPlatformProxyOptions } from 'wrangler';
 
 export default function plugin(options?: AdapterOptions): Adapter;
 
 export interface AdapterOptions {
 	config?: string;
+	/**
+	 * Config object passed to {@link https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy | getPlatformProxy}
+	 * during development and preview.
+	 */
+	platformProxy?: GetPlatformProxyOptions;
 }

packages/adapter-cloudflare-workers/index.js

@@ -32,7 +32,7 @@ const compatible_node_modules = [
 ];
 
 /** @type {import('./index.js').default} */
-export default function ({ config = 'wrangler.toml' } = {}) {
+export default function ({ config = 'wrangler.toml', platformProxy = {} } = {}) {
 	return {
 		name: '@sveltejs/adapter-cloudflare-workers',
 
@@ -145,7 +145,7 @@ export default function ({ config = 'wrangler.toml' } = {}) {
 		},
 
 		async emulate() {
-			const proxy = await getPlatformProxy();
+			const proxy = await getPlatformProxy(platformProxy);
 			const platform = /** @type {App.Platform} */ ({
 				env: proxy.env,
 				context: proxy.ctx,

packages/adapter-cloudflare/index.d.ts

@@ -1,5 +1,6 @@
 import { Adapter } from '@sveltejs/kit';
 import './ambient.js';
+import { GetPlatformProxyOptions } from 'wrangler';
 
 export default function plugin(options?: AdapterOptions): Adapter;
 
@@ -17,7 +18,7 @@ export interface AdapterOptions {
 	fallback?: 'plaintext' | 'spa';
 
 	/**
-	 * Customize the automatically-generated `_routes.json` file
+	 * Customize the automatically-generated `_routes.json` file.
 	 * https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file
 	 */
 	routes?: {
@@ -42,6 +43,12 @@ export interface AdapterOptions {
 		 */
 		exclude?: string[];
 	};
+
+	/**
+	 * Config object passed to {@link https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy | getPlatformProxy}
+	 * during development and preview.
+	 */
+	platformProxy?: GetPlatformProxyOptions;
 }
 
 export interface RoutesJSONSpec {

packages/adapter-cloudflare/index.js

@@ -128,7 +128,7 @@ export default function (options = {}) {
 			}
 		},
 		async emulate() {
-			const proxy = await getPlatformProxy();
+			const proxy = await getPlatformProxy(options.platformProxy);
 			const platform = /** @type {App.Platform} */ ({
 				env: proxy.env,
 				context: proxy.ctx,