chore: address #2815 feedback

.changeset/fluffy-hotels-yell.md

@@ -0,0 +1,6 @@
+---
+"@sveltejs/adapter-cloudflare-workers": patch
+"@sveltejs/adapter-cloudflare": patch
+---
+
+Update READMEs with additional **Comparison** notes

README.md

@@ -1,10 +1,13 @@
 # READ THIS FIRST!
 
-SvelteKit is still in beta. Expect bugs! Read more [here](https://svelte.dev/blog/sveltekit-beta), and track progress towards 1.0 [here](https://github.com/sveltejs/kit/issues?q=is%3Aopen+is%3Aissue+milestone%3A1.0).
+SvelteKit is still in beta. Expect bugs! Read more
+[here](https://svelte.dev/blog/sveltekit-beta), and track progress towards 1.0
+[here](https://github.com/sveltejs/kit/issues?q=is%3Aopen+is%3Aissue+milestone%3A1.0).
 
 ## Documentation
 
-Please see [the documentation](https://kit.svelte.dev/docs) for information about getting started and developing with SvelteKit.
+Please see [the documentation](https://kit.svelte.dev/docs) for information
+about getting started and developing with SvelteKit.
 
 ## Packages
 
@@ -14,30 +17,41 @@ Please see [the documentation](https://kit.svelte.dev/docs) for information abou
 | [create-svelte](packages/create-svelte)                                     | [Changelog](packages/create-svelte/CHANGELOG.md)              |
 | [@sveltejs/adapter-node](packages/adapter-node)                             | [Changelog](packages/adapter-node/CHANGELOG.md)               |
 | [@sveltejs/adapter-static](packages/adapter-static)                         | [Changelog](packages/adapter-static/CHANGELOG.md)             |
+| [@sveltejs/adapter-cloudflare](packages/adapter-cloudflare)                 | [Changelog](packages/adapter-cloudflare/CHANGELOG.md)         |
 | [@sveltejs/adapter-cloudflare-workers](packages/adapter-cloudflare-workers) | [Changelog](packages/adapter-cloudflare-workers/CHANGELOG.md) |
 | [@sveltejs/adapter-netlify](packages/adapter-netlify)                       | [Changelog](packages/adapter-netlify/CHANGELOG.md)            |
 | [@sveltejs/adapter-vercel](packages/adapter-vercel)                         | [Changelog](packages/adapter-vercel/CHANGELOG.md)             |
 
-The SvelteKit community also makes additional [SvelteKit adapters available for use](https://sveltesociety.dev/components#adapters).
+The SvelteKit community also makes additional
+[SvelteKit adapters available for use](https://sveltesociety.dev/components#adapters).
 
 ## Bug reporting
 
-Please make sure the issue you're reporting involves SvelteKit. Many issues related to how a project builds originate from [Vite](https://vitejs.dev/), which SvelteKit uses to build a project. It's important to note that new Vite projects don't use SSR by default and so if you create a new Vite project from scratch many issues won't reproduce eventhough they're caused by Vite. You should thus start with a project that utilizes SSR such as:
+Please make sure the issue you're reporting involves SvelteKit. Many issues
+related to how a project builds originate from [Vite](https://vitejs.dev/),
+which SvelteKit uses to build a project. It's important to note that new Vite
+projects don't use SSR by default and so if you create a new Vite project from
+scratch many issues won't reproduce eventhough they're caused by Vite. You
+should thus start with a project that utilizes SSR such as:
 
 - https://github.com/GrygrFlzr/vite-ssr-d3
 - https://github.com/sveltejs/vite-plugin-svelte/tree/main/packages/e2e-tests/vite-ssr
 
-If an issue is caused by Vite, please report in the [Vite issue tracker](https://github.com/vitejs/vite/issues).
+If an issue is caused by Vite, please report in the
+[Vite issue tracker](https://github.com/vitejs/vite/issues).
 
 ## Developing
 
-This is a monorepo meaning the repo holds multiple packages. It requires the use of [pnpm](https://pnpm.js.org/en/). You can [install pnpm](https://pnpm.io/installation) with:
+This is a monorepo meaning the repo holds multiple packages. It requires the use
+of [pnpm](https://pnpm.js.org/en/). You can
+[install pnpm](https://pnpm.io/installation) with:
 
 ```bash
 npm i -g pnpm
 ```
 
-`pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and build all sub-projects with:
+`pnpm` commands run in the project's root directory will run on all
+sub-projects. You can checkout the code and build all sub-projects with:
 
 ```bash
 git clone git@github.com:sveltejs/kit.git
@@ -47,14 +61,18 @@ pnpm build
 ```
 
 You should now be able to run [the example](examples/hn.svelte.dev) with:
+
 ```bash
 cd examples/hn.svelte.dev
 pnpm dev
 ```
 
-Run `pnpm dev` inside the `packages/kit` directory to continually rebuild `@sveltejs/kit` as you make changes to SvelteKit. Restarting the example/test apps will cause the newly built version to be used.
+Run `pnpm dev` inside the `packages/kit` directory to continually rebuild
+`@sveltejs/kit` as you make changes to SvelteKit. Restarting the example/test
+apps will cause the newly built version to be used.
 
-To use the git hooks in the repo, which will save you waiting for CI to tell you that you forgot to lint, run this:
+To use the git hooks in the repo, which will save you waiting for CI to tell you
+that you forgot to lint, run this:
 
 ```bash
 git config core.hookspath .githooks
@@ -63,42 +81,66 @@ git config core.hookspath .githooks
 ### Coding style
 
 There are a few guidelines we follow:
-- Internal variables are written with `snake_case` while external APIs are written with `camelCase`
-- Provide a single object as the argument to public APIs. This object can have multiple properties
-- Avoid creating new test projects under `packages/kit/test/apps` but reuse an existing one when possible
-- Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format the code
+
+- Internal variables are written with `snake_case` while external APIs are
+  written with `camelCase`
+- Provide a single object as the argument to public APIs. This object can have
+  multiple properties
+- Avoid creating new test projects under `packages/kit/test/apps` but reuse an
+  existing one when possible
+- Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format
+  the code
 
 ### Generating changelogs
 
-For changes to be reflected in package changelogs, run `pnpx changeset` and follow the prompts. All changesets should be `patch` until SvelteKit 1.0
+For changes to be reflected in package changelogs, run `pnpx changeset` and
+follow the prompts. All changesets should be `patch` until SvelteKit 1.0
 
 ### Testing
 
-Run `pnpm test` to run the tests from all subpackages. Browser tests live in subdirectories of `packages/kit/test` such as `packages/kit/test/apps/basics`.
+Run `pnpm test` to run the tests from all subpackages. Browser tests live in
+subdirectories of `packages/kit/test` such as `packages/kit/test/apps/basics`.
 
-You can run the tests for only a single package by first moving to that directory. E.g. `cd packages/kit`.
+You can run the tests for only a single package by first moving to that
+directory. E.g. `cd packages/kit`.
 
 You must rebuild each time before running the tests if you've made code changes.
 
-To run a single integration test, provide the `FILTER` env var with the test name. E.g. `FILTER="includes paths" pnpm test:integration`. You can also open up the file and change `test` to `test.only`.
+To run a single integration test, provide the `FILTER` env var with the test
+name. E.g. `FILTER="includes paths" pnpm test:integration`. You can also open up
+the file and change `test` to `test.only`.
 
-You can run the test server with `cd packages/kit/test/apps/basics; pnpm run dev` to hit it with your browser.
+You can run the test server with
+`cd packages/kit/test/apps/basics; pnpm run dev` to hit it with your browser.
 
-You may need to install some dependencies first e.g. with `npx playwright install-deps` (which only works on Ubuntu).
+You may need to install some dependencies first e.g. with
+`npx playwright install-deps` (which only works on Ubuntu).
 
 ### Documentation
 
-All documentation for SvelteKit is in the `documentation` directory, any improvements should be made as a Pull Request to this repository. The documentation is served via and API, the site itself is located in the [`sites` repository](https://github.com/sveltejs/sites).
+All documentation for SvelteKit is in the `documentation` directory, any
+improvements should be made as a Pull Request to this repository. The
+documentation is served via and API, the site itself is located in the
+[`sites` repository](https://github.com/sveltejs/sites).
 
-If you wish to preview documentation changes locally, please follow the instructions here: [Previewing local docs changes](https://github.com/sveltejs/sites/blob/master/sites/kit.svelte.dev/README.md#previewing-local-docs-changes).
+If you wish to preview documentation changes locally, please follow the
+instructions here:
+[Previewing local docs changes](https://github.com/sveltejs/sites/blob/master/sites/kit.svelte.dev/README.md#previewing-local-docs-changes).
 
 ### Releases
 
-The [Changesets GitHub action](https://github.com/changesets/action#with-publishing) will create and update a PR that applies changesets and publishes new versions of changed packages to npm.
+The
+[Changesets GitHub action](https://github.com/changesets/action#with-publishing)
+will create and update a PR that applies changesets and publishes new versions
+of changed packages to npm.
 
-> It uses `pnpm publish` rather than `pnpx changeset publish` so that we can use the `--filter` and (while in beta) `--tag` flags — though perhaps they work with `pnpx changeset publish`?
+> It uses `pnpm publish` rather than `pnpx changeset publish` so that we can use
+> the `--filter` and (while in beta) `--tag` flags — though perhaps they work
+> with `pnpx changeset publish`?
 
-New packages will need to be published manually the first time if they are scoped to the `@sveltejs` organisation, by running this from the package directory:
+New packages will need to be published manually the first time if they are
+scoped to the `@sveltejs` organisation, by running this from the package
+directory:
 
 ```
 npm publish --access=public
@@ -107,10 +149,20 @@ npm publish --access=public
 ## Code structure
 
 Entry points to be aware of are:
-- [`packages/create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte) - code that's run when you create a new project with `npm init svelte@next`
-- [`packages/kit/src/packaging`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/packaging) - for the `svelte-kit package` command
-- [`packages/kit/src/core/dev/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/dev/index.js) - for the dev-mode server
-- [`packages/kit/src/core/build/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/build/index.js) - for the production server
-- [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/master/packages) - for the various SvelteKit-provided adapters
 
-Most code that's called at build-time or from the CLI entry point lives in [packages/kit/src/core](https://github.com/sveltejs/kit/tree/master/packages/kit/src/core). Code that runs for rendering and routing lives in [packages/kit/src/runtime](https://github.com/sveltejs/kit/tree/master/packages/kit/src/runtime). Most changes to SvelteKit itself would involve code in these two directories.
+- [`packages/create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte) -
+  code that's run when you create a new project with `npm init svelte@next`
+- [`packages/kit/src/packaging`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/packaging) -
+  for the `svelte-kit package` command
+- [`packages/kit/src/core/dev/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/dev/index.js) -
+  for the dev-mode server
+- [`packages/kit/src/core/build/index.js`](https://github.com/sveltejs/kit/blob/master/packages/kit/src/core/build/index.js) -
+  for the production server
+- [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/master/packages) -
+  for the various SvelteKit-provided adapters
+
+Most code that's called at build-time or from the CLI entry point lives in
+[packages/kit/src/core](https://github.com/sveltejs/kit/tree/master/packages/kit/src/core).
+Code that runs for rendering and routing lives in
+[packages/kit/src/runtime](https://github.com/sveltejs/kit/tree/master/packages/kit/src/runtime).
+Most changes to SvelteKit itself would involve code in these two directories.

packages/adapter-cloudflare-workers/README.md

@@ -1,12 +1,31 @@
 # adapter-cloudflare-workers
 
-SvelteKit adapter that creates a Cloudflare Workers site using a function for dynamic server rendering.
+SvelteKit adapter that creates a Cloudflare Workers site using a function for
+dynamic server rendering.
 
-This is very experimental; the adapter API isn't at all fleshed out, and things will definitely change.
+This is very experimental; the adapter API isn't at all fleshed out, and things
+will definitely change.
+
+_**Comparisons**_
+
+- `adapter-cloudflare` – supports all SvelteKit features; builds for
+  [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/)
+- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for
+  Cloudflare Workers
+- `adapter-static` – only produces client-side static assets; compatible with
+  Cloudflare Pages
+
+> **Note:**<br> Cloudflare Pages' new Workers integration is currently in
+> beta.<br> Compared to `adapter-cloudflare-workers`, this adapter will be the
+> preferred approach for most users since building on top of Pages unlocks
+> automatic builds and deploys, preview deployments, instant rollbacks, etc.<br>
+> From SvelteKit's perspective, there is no difference and no functionality loss
+> when migrating to/from the Workers and the Pages adapters.
 
 ## Usage
 
-Install with `npm i -D @sveltejs/adapter-cloudflare-workers@next`, then add the adapter to your `svelte.config.js`:
+Install with `npm i -D @sveltejs/adapter-cloudflare-workers@next`, then add the
+adapter to your `svelte.config.js`:
 
 ```js
 import adapter from '@sveltejs/adapter-cloudflare-workers';
@@ -21,9 +40,14 @@ export default {
 
 ## Basic Configuration
 
-**You will need [Wrangler](https://developers.cloudflare.com/workers/cli-wrangler/install-update) installed on your system**
+**You will need
+[Wrangler](https://developers.cloudflare.com/workers/cli-wrangler/install-update)
+installed on your system**
 
-This adapter expects to find a [wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It will determine where to write static assets and the worker based on the `site.bucket` and `site.entry-point` settings.
+This adapter expects to find a
+[wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration)
+file in the project root. It will determine where to write static assets and the
+worker based on the `site.bucket` and `site.entry-point` settings.
 
 Generate this file using `wrangler` from your project directory
 
@@ -36,9 +60,11 @@ Now you should get some details from Cloudflare. You should get your:
 1. Account ID
 2. And your Zone-ID (Optional)
 
-Get them by visiting your Cloudflare-Dashboard and click on any domain. There, you can scroll down and on the left, you can see your details under **API**.
+Get them by visiting your Cloudflare-Dashboard and click on any domain. There,
+you can scroll down and on the left, you can see your details under **API**.
 
-Then configure your sites build directory and your account-details in the config file:
+Then configure your sites build directory and your account-details in the config
+file:
 
 ```toml
 account_id = 'YOUR ACCOUNT_ID'
@@ -55,7 +81,8 @@ command = ""
 format = "service-worker"
 ```
 
-It's recommended that you add the `build` and `workers-site` folders (or whichever other folders you specify) to your `.gitignore`.
+It's recommended that you add the `build` and `workers-site` folders (or
+whichever other folders you specify) to your `.gitignore`.
 
 Now, log in with wrangler:
 
@@ -71,13 +98,17 @@ npm run build && wrangler publish
 
 **You are done!**
 
-More info on configuring a cloudflare worker site can be found [here](https://developers.cloudflare.com/workers/platform/sites/start-from-existing)
+More info on configuring a cloudflare worker site can be found
+[here](https://developers.cloudflare.com/workers/platform/sites/start-from-existing)
 
 ## Advanced Configuration
 
 ### esbuild
 
-As an escape hatch, you may optionally specify a function which will receive the final esbuild options generated by this adapter and returns a modified esbuild configuration. The result of this function will be passed as-is to esbuild. The function can be async.
+As an escape hatch, you may optionally specify a function which will receive the
+final esbuild options generated by this adapter and returns a modified esbuild
+configuration. The result of this function will be passed as-is to esbuild. The
+function can be async.
 
 For example, you may wish to add a plugin:
 
@@ -106,4 +137,5 @@ const options = {
 
 ## Changelog
 
-[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare-workers/CHANGELOG.md).
+[The Changelog for this package is available on
+GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare-workers/CHANGELOG.md).

packages/adapter-cloudflare/README.md

@@ -12,6 +12,13 @@ _**Comparisons**_
 - `adapter-static` – only produces client-side static assets; compatible with
   Cloudflare Pages
 
+> **Note:**<br> Cloudflare Pages' new Workers integration is currently in
+> beta.<br> Compared to `adapter-cloudflare-workers`, this adapter will be the
+> preferred approach for most users since building on top of Pages unlocks
+> automatic builds and deploys, preview deployments, instant rollbacks, etc.<br>
+> From SvelteKit's perspective, there is no difference and no functionality loss
+> when migrating to/from the Workers and the Pages adapters.
+
 ## Installation
 
 ```sh

packages/adapter-cloudflare/files/worker.js

@@ -28,7 +28,7 @@ export default {
 				});
 			}
 		} catch (e) {
-			return new Response('Error rendering route:' + (e.message || e.toString()), { status: 500 });
+			return new Response('Error rendering route: ' + (e.message || e.toString()), { status: 500 });
 		}
 
 		return new Response({