From 8e4942bb7a9ce1bc9f1c5112d437139dc0e7b49b Mon Sep 17 00:00:00 2001 From: Luke Edwards Date: Wed, 17 Nov 2021 12:46:12 -0800 Subject: [PATCH 1/2] chore: address #2815 feedback --- README.md | 112 +++++++++++++----- packages/adapter-cloudflare-workers/README.md | 54 +++++++-- packages/adapter-cloudflare/README.md | 7 ++ packages/adapter-cloudflare/files/worker.js | 2 +- 4 files changed, 133 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index e30984f1ba82..fc25a6903b44 100644 --- a/README.md +++ b/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. diff --git a/packages/adapter-cloudflare-workers/README.md b/packages/adapter-cloudflare-workers/README.md index a62bfead4808..1a04ee8a6133 100644 --- a/packages/adapter-cloudflare-workers/README.md +++ b/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:**
Cloudflare Pages' new Workers integration is currently in +> beta.
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.
+> 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). diff --git a/packages/adapter-cloudflare/README.md b/packages/adapter-cloudflare/README.md index 4e8db306ab21..53dacfc97404 100644 --- a/packages/adapter-cloudflare/README.md +++ b/packages/adapter-cloudflare/README.md @@ -12,6 +12,13 @@ _**Comparisons**_ - `adapter-static` – only produces client-side static assets; compatible with Cloudflare Pages +> **Note:**
Cloudflare Pages' new Workers integration is currently in +> beta.
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.
+> From SvelteKit's perspective, there is no difference and no functionality loss +> when migrating to/from the Workers and the Pages adapters. + ## Installation ```sh diff --git a/packages/adapter-cloudflare/files/worker.js b/packages/adapter-cloudflare/files/worker.js index 7282d43e8649..8378d9f5add7 100644 --- a/packages/adapter-cloudflare/files/worker.js +++ b/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({ From 456a5225a0c494e772e0615d477ea92b593b3742 Mon Sep 17 00:00:00 2001 From: Luke Edwards Date: Wed, 17 Nov 2021 12:47:55 -0800 Subject: [PATCH 2/2] changeset --- .changeset/fluffy-hotels-yell.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/fluffy-hotels-yell.md diff --git a/.changeset/fluffy-hotels-yell.md b/.changeset/fluffy-hotels-yell.md new file mode 100644 index 000000000000..f7930c566749 --- /dev/null +++ b/.changeset/fluffy-hotels-yell.md @@ -0,0 +1,6 @@ +--- +"@sveltejs/adapter-cloudflare-workers": patch +"@sveltejs/adapter-cloudflare": patch +--- + +Update READMEs with additional **Comparison** notes