From 054e1420154c4f5fa2ddfcf9be277ee8ea8adfeb Mon Sep 17 00:00:00 2001 From: korinne Date: Mon, 3 Feb 2025 12:34:29 -0800 Subject: [PATCH 1/5] Removes Workers Sites docs, adds FAQ for Workers Static assets --- .../configuration/sites/configuration.mdx | 129 ---------------- .../workers/configuration/sites/index.mdx | 47 ------ .../sites/start-from-existing.mdx | 144 ------------------ .../sites/start-from-scratch.mdx | 90 ----------- .../configuration/sites/start-from-worker.mdx | 103 ------------- .../docs/workers/static-assets/faqs.mdx | 34 +++++ .../partials/workers/workers_sites.mdx | 3 +- src/env.d.ts | 1 + 8 files changed, 36 insertions(+), 515 deletions(-) delete mode 100644 src/content/docs/workers/configuration/sites/configuration.mdx delete mode 100644 src/content/docs/workers/configuration/sites/index.mdx delete mode 100644 src/content/docs/workers/configuration/sites/start-from-existing.mdx delete mode 100644 src/content/docs/workers/configuration/sites/start-from-scratch.mdx delete mode 100644 src/content/docs/workers/configuration/sites/start-from-worker.mdx create mode 100644 src/content/docs/workers/static-assets/faqs.mdx create mode 100644 src/env.d.ts diff --git a/src/content/docs/workers/configuration/sites/configuration.mdx b/src/content/docs/workers/configuration/sites/configuration.mdx deleted file mode 100644 index 26203d3d2b6f3d4..000000000000000 --- a/src/content/docs/workers/configuration/sites/configuration.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -pcx_content_type: configuration -title: Workers Sites configuration -sidebar: - order: 4 - ---- - -import { Render, WranglerConfig } from "~/components" - - - -Workers Sites require the latest version of [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler). - -## Wrangler configuration file - -There are a few specific configuration settings for Workers Sites in your Wrangler file: - - - -* `bucket` required - - * The directory containing your static assets, path relative to your `wrangler.toml / wrangler.json` file. Example: `bucket = "./public"`. - -* `include` optional - - * A list of gitignore-style patterns for files or directories in `bucket` you exclusively want to upload. Example: `include = ["upload_dir"]`. - -* `exclude` optional - * A list of gitignore-style patterns for files or directories in `bucket` you want to exclude from uploads. Example: `exclude = ["ignore_dir"]`. - - - -To learn more about the optional `include` and `exclude` fields, refer to [Ignoring subsets of static assets](#ignoring-subsets-of-static-assets). - -:::note - - -If your project uses [environments](/workers/wrangler/environments/), make sure to place `site` above any environment-specific configuration blocks. - - -::: - -Example of a `wrangler.toml / wrangler.json` file: - - - -```toml -name = "docs-site-blah" - -[site] -bucket = "./public" - -[env.production] -name = "docs-site" -route = "https://example.com/docs*" - -[env.staging] -name = "docs-site-staging" -route = "https://staging.example.com/docs*" -``` - - - -## Storage limits - -For very exceptionally large pages, Workers Sites might not work for you. There is a 25 MiB limit per page or file. - -## Ignoring subsets of static assets - -Workers Sites require [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) - make sure to use the [latest version](/workers/wrangler/install-and-update/#update-wrangler). - -There are cases where users may not want to upload certain static assets to their Workers Sites. -In this case, Workers Sites can also be configured to ignore certain files or directories using logic -similar to [Cargo's optional include and exclude fields](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields-optional). - -This means that you should use gitignore semantics when declaring which directory entries to include or ignore in uploads. - -### Exclusively including files/directories - -If you want to include only a certain set of files or directories in your `bucket`, you can add an `include` field to your `[site]` section of your Wrangler file: - - - - - -```toml -[site] -bucket = "./public" -include = ["included_dir"] # must be an array. -``` - - - -Wrangler will only upload files or directories matching the patterns in the `include` array. - -### Excluding files/directories - -If you want to exclude files or directories in your `bucket`, you can add an `exclude` field to your `[site]` section of your Wrangler file: - - - - - -```toml -[site] -bucket = "./public" -exclude = ["excluded_dir"] # must be an array. -``` - - - -Wrangler will ignore files or directories matching the patterns in the `exclude` array when uploading assets to Workers KV. - -### Include > exclude - -If you provide both `include` and `exclude` fields, the `include` field will be used and the `exclude` field will be ignored. - -### Default ignored entries - -Wrangler will always ignore: - -* `node_modules` -* Hidden files and directories -* Symlinks - -#### More about include/exclude patterns - -Learn more about the standard patterns used for include and exclude in the [gitignore documentation](https://git-scm.com/docs/gitignore). diff --git a/src/content/docs/workers/configuration/sites/index.mdx b/src/content/docs/workers/configuration/sites/index.mdx deleted file mode 100644 index 7420de45c11f978..000000000000000 --- a/src/content/docs/workers/configuration/sites/index.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -pcx_content_type: navigation -title: Workers Sites -head: [] -description: Use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. Do not use Workers Sites for new projects. ---- - -import { Render } from "~/components" -import { LinkButton } from "~/components" - - - -Workers Sites enables developers to deploy static applications directly to Workers. It can be used for deploying applications built with static site generators like [Hugo](https://gohugo.io) and [Gatsby](https://www.gatsbyjs.org), or front-end frameworks like [Vue](https://vuejs.org) and [React](https://reactjs.org). - -To deploy with Workers Sites, select from one of these three approaches depending on the state of your target project: - -*** - -## 1. Start from scratch - -If you are ready to start a brand new project, this quick start guide will help you set up the infrastructure to deploy a HTML website to Workers. - -Start from scratch - -*** - -## 2. Deploy an existing static site - -If you have an existing project or static assets that you want to deploy with Workers, this quick start guide will help you install Wrangler and configure Workers Sites for your project. - -Start from an existing static site - -*** - -## 3. Add static assets to an existing Workers project - -If you already have a Worker deployed to Cloudflare, this quick start guide will show you how to configure the existing codebase to use Workers Sites. - -Start from an existing Worker - -:::note - - -Workers Sites is built on Workers KV, and usage rates may apply. Refer to [Pricing](/workers/platform/pricing/) to learn more. - - -::: diff --git a/src/content/docs/workers/configuration/sites/start-from-existing.mdx b/src/content/docs/workers/configuration/sites/start-from-existing.mdx deleted file mode 100644 index efcbaacb27c500b..000000000000000 --- a/src/content/docs/workers/configuration/sites/start-from-existing.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -pcx_content_type: how-to -title: Start from existing -sidebar: - order: 1 ---- - -import { Render, TabItem, Tabs, WranglerConfig } from "~/components"; - - - -Workers Sites require [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) — make sure to use the [latest version](/workers/wrangler/install-and-update/#update-wrangler). - -To deploy a pre-existing static site project, start with a pre-generated site. Workers Sites works with all static site generators, for example: - -- [Hugo](https://gohugo.io/getting-started/quick-start/) -- [Gatsby](https://www.gatsbyjs.org/docs/quick-start/), requires Node -- [Jekyll](https://jekyllrb.com/docs/), requires Ruby -- [Eleventy](https://www.11ty.io/#quick-start), requires Node -- [WordPress](https://wordpress.org) (refer to the tutorial on [deploying static WordPress sites with Pages](/pages/how-to/deploy-a-wordpress-site/)) - -## Getting started - -1. Run the `wrangler init` command in the root of your project's directory to generate a basic Worker: - - ```sh - wrangler init -y - ``` - - This command adds/update the following files: - - - `wrangler.json`: The file containing project configuration. - - `package.json`: Wrangler `devDependencies` are added. - - `tsconfig.json`: Added if not already there to support writing the Worker in TypeScript. - - `src/index.ts`: A basic Cloudflare Worker, written in TypeScript. - -2. Add your site's build/output directory to the Wrangler file: - - - - ```toml - [site] - bucket = "./public" # <-- Add your build directory name here. - ``` - - - - The default directories for the most popular static site generators are listed below: - - - Hugo: `public` - - Gatsby: `public` - - Jekyll: `_site` - - Eleventy: `_site` - -3. Install the `@cloudflare/kv-asset-handler` package in your project: - - ```sh - npm i -D @cloudflare/kv-asset-handler - ``` - -4. Replace the contents of `src/index.ts` with the following code snippet: - - - -```js -import { getAssetFromKV } from "@cloudflare/kv-asset-handler"; -import manifestJSON from "__STATIC_CONTENT_MANIFEST"; -const assetManifest = JSON.parse(manifestJSON); - -export default { - async fetch(request, env, ctx) { - try { - // Add logic to decide whether to serve an asset or run your original Worker code - return await getAssetFromKV( - { - request, - waitUntil: ctx.waitUntil.bind(ctx), - }, - { - ASSET_NAMESPACE: env.__STATIC_CONTENT, - ASSET_MANIFEST: assetManifest, - }, - ); - } catch (e) { - let pathname = new URL(request.url).pathname; - return new Response(`"${pathname}" not found`, { - status: 404, - statusText: "not found", - }); - } - }, -}; -``` - - - -```js -import { getAssetFromKV } from "@cloudflare/kv-asset-handler"; - -addEventListener("fetch", (event) => { - event.respondWith(handleEvent(event)); -}); - -async function handleEvent(event) { - try { - // Add logic to decide whether to serve an asset or run your original Worker code - return await getAssetFromKV(event); - } catch (e) { - let pathname = new URL(event.request.url).pathname; - return new Response(`"${pathname}" not found`, { - status: 404, - statusText: "not found", - }); - } -} -``` - - - -5. Run `wrangler dev` or `npx wrangler deploy` to preview or deploy your site on Cloudflare. - Wrangler will automatically upload the assets found in the configured directory. - - ```sh - npx wrangler deploy - ``` - -6. Deploy your site to a [custom domain](/workers/configuration/routing/custom-domains/) that you own and have already attached as a Cloudflare zone. Add a `route` property to the Wrangler file. - - - - - - ```toml - route = "https://example.com/*" - ``` - - - - :::note - - Refer to the documentation on [Routes](/workers/configuration/routing/routes/) to configure a `route` properly. - ::: - -Learn more about [configuring your project](/workers/wrangler/configuration/). diff --git a/src/content/docs/workers/configuration/sites/start-from-scratch.mdx b/src/content/docs/workers/configuration/sites/start-from-scratch.mdx deleted file mode 100644 index c5198648b52b172..000000000000000 --- a/src/content/docs/workers/configuration/sites/start-from-scratch.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -pcx_content_type: how-to -title: Start from scratch -sidebar: - order: 2 ---- - -import { Render, WranglerConfig } from "~/components"; - - - -This guide shows how to quickly start a new Workers Sites project from scratch. - -## Getting started - -1. Ensure you have the latest version of [git](https://git-scm.com/downloads) and [Node.js](https://nodejs.org/en/download/) installed. - -2. In your terminal, clone the `worker-sites-template` starter repository. - The following example creates a project called `my-site`: - - ```sh - git clone --depth=1 --branch=wrangler2 https://github.com/cloudflare/worker-sites-template my-site - ``` - -3. Run `npm install` to install all dependencies. - -4. You can preview your site by running the [`wrangler dev`](/workers/wrangler/commands/#dev) command: - - ```sh - wrangler dev - ``` - -5. Deploy your site to Cloudflare: - - ```sh - npx wrangler deploy - ``` - -## Project layout - -The template project contains the following files and directories: - -- `public`: The static assets for your project. By default it contains an `index.html` and a `favicon.ico`. -- `src`: The Worker configured for serving your assets. You do not need to edit this but if you want to see how it works or add more functionality to your Worker, you can edit `src/index.ts`. -- `wrangler.json`: The file containing project configuration. - The `bucket` property tells Wrangler where to find the static assets (e.g. `site = { bucket = "./public" }`). -- `package.json`/`package-lock.json`: define the required Node.js dependencies. - -## Customize the `wrangler.toml / wrangler.json` file: - -- Change the `name` property to the name of your project: - - - - ```toml - name = "my-site" - ``` - - - -- Consider updating`compatibility_date` to today's date to get access to the most recent Workers features: - - - - - - ```toml - compatibility_date = "yyyy-mm-dd" - ``` - - - -- Deploy your site to a [custom domain](/workers/configuration/routing/custom-domains/) that you own and have already attached as a Cloudflare zone: - - - - - - ```toml - route = "https://example.com/*" - ``` - - - - :::note - - Refer to the documentation on [Routes](/workers/configuration/routing/routes/) to configure a `route` properly. - ::: - -Learn more about [configuring your project](/workers/wrangler/configuration/). diff --git a/src/content/docs/workers/configuration/sites/start-from-worker.mdx b/src/content/docs/workers/configuration/sites/start-from-worker.mdx deleted file mode 100644 index 46d789a4db225de..000000000000000 --- a/src/content/docs/workers/configuration/sites/start-from-worker.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -pcx_content_type: how-to -title: Start from Worker -sidebar: - order: 3 ---- - -import { Render, TabItem, Tabs, WranglerConfig } from "~/components"; - - - -Workers Sites require [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) — make sure to use the [latest version](/workers/wrangler/install-and-update/#update-wrangler). - -If you have a pre-existing Worker project, you can use Workers Sites to serve static assets to the Worker. - -## Getting started - -1. Create a directory that will contain the assets in the root of your project (for example, `./public`) - -2. Add configuration to your Wrangler file to point to it. - - - - ```toml - [site] - bucket = "./public" # Add the directory with your static assets! - ``` - - - -3. Install the `@cloudflare/kv-asset-handler` package in your project: - - ```sh - npm i -D @cloudflare/kv-asset-handler - ``` - -4. Import the `getAssetFromKV()` function into your Worker entry point and use it to respond with static assets. - - - -```js -import { getAssetFromKV } from "@cloudflare/kv-asset-handler"; -import manifestJSON from "__STATIC_CONTENT_MANIFEST"; -const assetManifest = JSON.parse(manifestJSON); - -export default { - async fetch(request, env, ctx) { - try { - // Add logic to decide whether to serve an asset or run your original Worker code - return await getAssetFromKV( - { - request, - waitUntil: ctx.waitUntil.bind(ctx), - }, - { - ASSET_NAMESPACE: env.__STATIC_CONTENT, - ASSET_MANIFEST: assetManifest, - }, - ); - } catch (e) { - let pathname = new URL(request.url).pathname; - return new Response(`"${pathname}" not found`, { - status: 404, - statusText: "not found", - }); - } - }, -}; -``` - - - -```js -import { getAssetFromKV } from "@cloudflare/kv-asset-handler"; - -addEventListener("fetch", (event) => { - event.respondWith(handleEvent(event)); -}); - -async function handleEvent(event) { - try { - // Add logic to decide whether to serve an asset or run your original Worker code - return await getAssetFromKV(event); - } catch (e) { - let pathname = new URL(event.request.url).pathname; - return new Response(`"${pathname}" not found`, { - status: 404, - statusText: "not found", - }); - } -} -``` - - - -For more information on the configurable options of `getAssetFromKV()` refer to [kv-asset-handler docs](https://github.com/cloudflare/workers-sdk/tree/main/packages/kv-asset-handler). - -5. Run `wrangler deploy` or `npx wrangler deploy` as you would normally with your Worker project. - Wrangler will automatically upload the assets found in the configured directory. - - ```sh - npx wrangler deploy - ``` diff --git a/src/content/docs/workers/static-assets/faqs.mdx b/src/content/docs/workers/static-assets/faqs.mdx new file mode 100644 index 000000000000000..63eacd485b9bca2 --- /dev/null +++ b/src/content/docs/workers/static-assets/faqs.mdx @@ -0,0 +1,34 @@ +--- +pcx_content_type: concept +title: FAQs +sidebar: + order: 12 +head: [] +description: Frequently Asked Questions +--- + +import { + Badge, + Description, + FileTree, + InlineBadge, + Render, + TabItem, + Tabs, + WranglerConfig, +} from "~/components"; + +### What's happening to [Pages](/pages/)? + +Pages is fully supported, with no current plans to change its support status. That being said, new features will land in Workers without a guarantee they will be available in Pages. + +### What kinds of projects are Workers best for, and when should I use Pages? + +We currently recommend: + +- **Pages** for static sites or simple applications (such as personal blogs or websites). +- **Workers** for building both static sites _and_ full stack applications, since you can take advantage of the full developer platform (such as [Queues](/queues/get-started/), [Durable Objects](/durable-objects/), and more). See the [Workers vs Pages compatibility matrix](/workers/static-assets/compatibility-matrix/) for more information. + +### What about Workers Sites? + +We do not recommend using Workers Sites for projects. Please use Workers with static assets, or Pages. diff --git a/src/content/partials/workers/workers_sites.mdx b/src/content/partials/workers/workers_sites.mdx index b7f0bb880b0fcb2..47faa85780e8b68 100644 --- a/src/content/partials/workers/workers_sites.mdx +++ b/src/content/partials/workers/workers_sites.mdx @@ -1,9 +1,8 @@ --- {} - --- :::caution[Use Workers Static Assets Instead] -You should use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. Do not use Workers Sites for new projects. +You should use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. Do not use Workers Sites for new projects. ::: diff --git a/src/env.d.ts b/src/env.d.ts new file mode 100644 index 000000000000000..9bc5cb41c24efc4 --- /dev/null +++ b/src/env.d.ts @@ -0,0 +1 @@ +/// \ No newline at end of file From 793738e4189ab8195d0c6d96d0b084dfbfe0addf Mon Sep 17 00:00:00 2001 From: korinne Date: Mon, 3 Feb 2025 14:53:57 -0800 Subject: [PATCH 2/5] Moves recommendations to compatibility matrix page --- .../static-assets/compatibility-matrix.mdx | 131 +++++++++--------- .../docs/workers/static-assets/faqs.mdx | 7 - 2 files changed, 69 insertions(+), 69 deletions(-) diff --git a/src/content/docs/workers/static-assets/compatibility-matrix.mdx b/src/content/docs/workers/static-assets/compatibility-matrix.mdx index f2573c17762fa6a..406d45a21505c95 100644 --- a/src/content/docs/workers/static-assets/compatibility-matrix.mdx +++ b/src/content/docs/workers/static-assets/compatibility-matrix.mdx @@ -17,9 +17,14 @@ import { Tabs, } from "~/components"; -You can deploy full-stack applications, including front-end static assets and back-end APIs, as well as server-side rendered pages (SSR), to both Cloudflare [Workers](/workers/static-assets/) and [Pages](/pages/). The compatibility matrix below shows which features are available for each, to help you choose whether to build with Workers or Pages. Unless otherwise stated below, what works in Pages works in Workers, and what works in Workers works in Pages. Think something is missing from this list? [Open a pull request](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/workers/static-assets/compatibility-matrix.mdx) or [create a GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/new). +You can deploy full-stack applications, including front-end static assets and back-end APIs, as well as server-side rendered pages (SSR), to both Cloudflare [Workers](/workers/static-assets/) and [Pages](/pages/). The compatibility matrix below shows which features are available for each. -We plan to bridge the gaps between Workers and Pages and provide ways to migrate your Pages projects to Workers. +If you're still unsure what use-cases are best for Pages and when you should use Workers with assets, we broadly recommend: + +- **Pages** for static sites or simple applications (such as personal blogs or websites). +- **Workers** for building both static sites _and_ full stack applications, since you can take advantage of the full developer platform (such as [Queues](/queues/get-started/), [Durable Objects](/durable-objects/), and more). + +We will continue to work to close the gaps between Workers and Pages, as well as provide a migration path. **Legend**
✅: Supported
@@ -27,66 +32,66 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate 🟡: Unsupported, workaround available
❌: Unsupported -| | Workers | Pages | -| ----------------------------------------------------------------------------------- | ------- | ------- | -| **Writing, Testing, and Deploying Code** | | | -| [Rollbacks](/workers/configuration/versions-and-deployments/rollbacks/) | ✅ | ✅ | -| [Gradual Deployments](/workers/configuration/versions-and-deployments/) | ✅ | ❌ | -| [Preview URLs](/workers/configuration/previews) | ✅ | ✅ | -| [Testing tools](/workers/testing) | ✅ | ✅ | -| [Local Development](/workers/testing/local-development/) | ✅ | ✅ | -| [Remote Development (`--remote`)](/workers/wrangler/commands/) | ✅ | ❌ | -| [Quick Editor in Dashboard](https://blog.cloudflare.com/improved-quick-edit) | ✅ | ❌ | -| **Static Assets** | | | -| [Early Hints](/pages/configuration/early-hints/) | ❌ | ✅ | -| [Custom HTTP headers for static assets](/pages/configuration/headers/) | 🟡 [^1] | ✅ | -| [Middleware](/workers/static-assets/binding/#run_worker_first) | ✅ [^2] | ✅ | -| [Redirects](/pages/configuration/redirects/) | 🟡 [^3] | ✅ | -| [Smart Placement](/workers/configuration/smart-placement/) | ✅ | ✅ | -| [Serve assets on a path](/workers/static-assets/routing/) | ✅ | ❌ | -| **Observability** | | | -| [Workers Logs](/workers/observability/) | ✅ | ❌ | -| [Logpush](/workers/observability/logs/logpush/) | ✅ | ❌ | -| [Tail Workers](/workers/observability/logs/tail-workers/) | ✅ | ❌ | -| [Real-time logs](/workers/observability/logs/real-time-logs/) | ✅ | ✅ | -| [Source Maps](/workers/observability/source-maps/) | ✅ | ❌ | -| **Runtime APIs & Compute Models** | | | -| [Node.js Compatibility Mode](/workers/runtime-apis/nodejs/) | ✅ | ✅ | -| [Durable Objects](/durable-objects/api/) | ✅ | 🟡 [^4] | -| [Cron Triggers](/workers/configuration/cron-triggers/) | ✅ | ❌ | -| **Bindings** | | | -| [AI](/workers-ai/get-started/workers-wrangler/#2-connect-your-worker-to-workers-ai) | ✅ | ✅ | -| [Analytics Engine](/analytics/analytics-engine) | ✅ | ✅ | -| [Assets](/workers/static-assets/binding/) | ✅ | ✅ | -| [Browser Rendering](/browser-rendering) | ✅ | ✅ | -| [D1](/d1/worker-api/) | ✅ | ✅ | -| [Email Workers](/email-routing/email-workers/send-email-workers/) | ✅ | ❌ | -| [Environment Variables](/workers/configuration/environment-variables/) | ✅ | ✅ | -| [Hyperdrive](/hyperdrive/) | ✅ | ✅ | -| [KV](/kv/) | ✅ | ✅ | -| [mTLS](/workers/runtime-apis/bindings/mtls/) | ✅ | ✅ | -| [Queue Producers](/queues/configuration/configure-queues/#producer) | ✅ | ✅ | -| [Queue Consumers](/queues/configuration/configure-queues/#consumer) | ✅ | ❌ | -| [R2](/r2/) | ✅ | ✅ | -| [Rate Limiting](/workers/runtime-apis/bindings/rate-limit/) | ✅ | ❌ | -| [Secrets](/workers/configuration/secrets/) | ✅ | ✅ | -| [Service bindings](/workers/runtime-apis/bindings/service-bindings/) | ✅ | ✅ | -| [Vectorize](/vectorize/get-started/intro/#3-bind-your-worker-to-your-index) | ✅ | ✅ | -| **Builds (CI/CD)** | | | -| [Monorepos](/workers/ci-cd/builds/advanced-setups/) | ✅ | ✅ | -| [Build Watch Paths](/workers/ci-cd/builds/build-watch-paths/) | ✅ | ✅ | -| [Build Caching](/workers/ci-cd/builds/build-caching/) | ✅ | ✅ | -| [Deploy Hooks](/pages/configuration/deploy-hooks/) | ❌ | ✅ | -| [Branch Deploy Controls](/pages/configuration/branch-build-controls/) | ❌ | ✅ | -| [Custom Branch Aliases](/pages/how-to/custom-branch-aliases/) | ❌ | ✅ | -| **Pages Functions** | | | -| [File-based Routing](/pages/functions/routing/) | ❌ [^5] | ✅ | -| [Pages Plugins](/pages/functions/plugins/) | ❌ [^6] | ✅ | -| **Domain Configuration** | | | -| [Custom domains](/workers/configuration/routing/custom-domains/#add-a-custom-domain)| ✅ | ✅ | -| [Custom subdomains](/workers/configuration/routing/custom-domains/#set-up-a-custom-domain-in-the-dashboard)|✅|✅| -| [Custom domains outside Cloudflare zones](/pages/configuration/custom-domains/#add-a-custom-cname-record)|❌|✅| -| [Non-root routes](/workers/configuration/routing/routes/) | ✅ | ❌ | +| | Workers | Pages | +| ----------------------------------------------------------------------------------------------------------- | ------- | ------- | +| **Writing, Testing, and Deploying Code** | | | +| [Rollbacks](/workers/configuration/versions-and-deployments/rollbacks/) | ✅ | ✅ | +| [Gradual Deployments](/workers/configuration/versions-and-deployments/) | ✅ | ❌ | +| [Preview URLs](/workers/configuration/previews) | ✅ | ✅ | +| [Testing tools](/workers/testing) | ✅ | ✅ | +| [Local Development](/workers/testing/local-development/) | ✅ | ✅ | +| [Remote Development (`--remote`)](/workers/wrangler/commands/) | ✅ | ❌ | +| [Quick Editor in Dashboard](https://blog.cloudflare.com/improved-quick-edit) | ✅ | ❌ | +| **Static Assets** | | | +| [Early Hints](/pages/configuration/early-hints/) | ❌ | ✅ | +| [Custom HTTP headers for static assets](/pages/configuration/headers/) | 🟡 [^1] | ✅ | +| [Middleware](/workers/static-assets/binding/#run_worker_first) | ✅ [^2] | ✅ | +| [Redirects](/pages/configuration/redirects/) | 🟡 [^3] | ✅ | +| [Smart Placement](/workers/configuration/smart-placement/) | ✅ | ✅ | +| [Serve assets on a path](/workers/static-assets/routing/) | ✅ | ❌ | +| **Observability** | | | +| [Workers Logs](/workers/observability/) | ✅ | ❌ | +| [Logpush](/workers/observability/logs/logpush/) | ✅ | ❌ | +| [Tail Workers](/workers/observability/logs/tail-workers/) | ✅ | ❌ | +| [Real-time logs](/workers/observability/logs/real-time-logs/) | ✅ | ✅ | +| [Source Maps](/workers/observability/source-maps/) | ✅ | ❌ | +| **Runtime APIs & Compute Models** | | | +| [Node.js Compatibility Mode](/workers/runtime-apis/nodejs/) | ✅ | ✅ | +| [Durable Objects](/durable-objects/api/) | ✅ | 🟡 [^4] | +| [Cron Triggers](/workers/configuration/cron-triggers/) | ✅ | ❌ | +| **Bindings** | | | +| [AI](/workers-ai/get-started/workers-wrangler/#2-connect-your-worker-to-workers-ai) | ✅ | ✅ | +| [Analytics Engine](/analytics/analytics-engine) | ✅ | ✅ | +| [Assets](/workers/static-assets/binding/) | ✅ | ✅ | +| [Browser Rendering](/browser-rendering) | ✅ | ✅ | +| [D1](/d1/worker-api/) | ✅ | ✅ | +| [Email Workers](/email-routing/email-workers/send-email-workers/) | ✅ | ❌ | +| [Environment Variables](/workers/configuration/environment-variables/) | ✅ | ✅ | +| [Hyperdrive](/hyperdrive/) | ✅ | ✅ | +| [KV](/kv/) | ✅ | ✅ | +| [mTLS](/workers/runtime-apis/bindings/mtls/) | ✅ | ✅ | +| [Queue Producers](/queues/configuration/configure-queues/#producer) | ✅ | ✅ | +| [Queue Consumers](/queues/configuration/configure-queues/#consumer) | ✅ | ❌ | +| [R2](/r2/) | ✅ | ✅ | +| [Rate Limiting](/workers/runtime-apis/bindings/rate-limit/) | ✅ | ❌ | +| [Secrets](/workers/configuration/secrets/) | ✅ | ✅ | +| [Service bindings](/workers/runtime-apis/bindings/service-bindings/) | ✅ | ✅ | +| [Vectorize](/vectorize/get-started/intro/#3-bind-your-worker-to-your-index) | ✅ | ✅ | +| **Builds (CI/CD)** | | | +| [Monorepos](/workers/ci-cd/builds/advanced-setups/) | ✅ | ✅ | +| [Build Watch Paths](/workers/ci-cd/builds/build-watch-paths/) | ✅ | ✅ | +| [Build Caching](/workers/ci-cd/builds/build-caching/) | ✅ | ✅ | +| [Deploy Hooks](/pages/configuration/deploy-hooks/) | ❌ | ✅ | +| [Branch Deploy Controls](/pages/configuration/branch-build-controls/) | ❌ | ✅ | +| [Custom Branch Aliases](/pages/how-to/custom-branch-aliases/) | ❌ | ✅ | +| **Pages Functions** | | | +| [File-based Routing](/pages/functions/routing/) | ❌ [^5] | ✅ | +| [Pages Plugins](/pages/functions/plugins/) | ❌ [^6] | ✅ | +| **Domain Configuration** | | | +| [Custom domains](/workers/configuration/routing/custom-domains/#add-a-custom-domain) | ✅ | ✅ | +| [Custom subdomains](/workers/configuration/routing/custom-domains/#set-up-a-custom-domain-in-the-dashboard) | ✅ | ✅ | +| [Custom domains outside Cloudflare zones](/pages/configuration/custom-domains/#add-a-custom-cname-record) | ❌ | ✅ | +| [Non-root routes](/workers/configuration/routing/routes/) | ✅ | ❌ | [^1]: Similar to 3, to customize the HTTP headers that are returned by static assets, you can use [Service bindings](/workers/runtime-apis/bindings/service-bindings/) to connect a Worker in front of the Worker with assets. @@ -99,3 +104,5 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate [^5]: Workers [supports popular frameworks](/workers/frameworks/), many of which implement file-based routing. [^6]: Everything that is possible with Pages Functions can also be achieved by adding code to your Worker or by using framework-specific plugins for relevant third party tools. + +Think something is missing from this list? [Open a pull request](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/workers/static-assets/compatibility-matrix.mdx) or [create a GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/new). diff --git a/src/content/docs/workers/static-assets/faqs.mdx b/src/content/docs/workers/static-assets/faqs.mdx index 63eacd485b9bca2..ab675405ba24452 100644 --- a/src/content/docs/workers/static-assets/faqs.mdx +++ b/src/content/docs/workers/static-assets/faqs.mdx @@ -22,13 +22,6 @@ import { Pages is fully supported, with no current plans to change its support status. That being said, new features will land in Workers without a guarantee they will be available in Pages. -### What kinds of projects are Workers best for, and when should I use Pages? - -We currently recommend: - -- **Pages** for static sites or simple applications (such as personal blogs or websites). -- **Workers** for building both static sites _and_ full stack applications, since you can take advantage of the full developer platform (such as [Queues](/queues/get-started/), [Durable Objects](/durable-objects/), and more). See the [Workers vs Pages compatibility matrix](/workers/static-assets/compatibility-matrix/) for more information. - ### What about Workers Sites? We do not recommend using Workers Sites for projects. Please use Workers with static assets, or Pages. From f48aeda34fb0f36682b468458dda74b76928c15c Mon Sep 17 00:00:00 2001 From: korinne <40270578+korinne@users.noreply.github.com> Date: Mon, 3 Feb 2025 15:58:35 -0800 Subject: [PATCH 3/5] Update src/content/docs/workers/static-assets/faqs.mdx Co-authored-by: Greg Brimble --- src/content/docs/workers/static-assets/faqs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/static-assets/faqs.mdx b/src/content/docs/workers/static-assets/faqs.mdx index ab675405ba24452..870095ad46ebbbd 100644 --- a/src/content/docs/workers/static-assets/faqs.mdx +++ b/src/content/docs/workers/static-assets/faqs.mdx @@ -24,4 +24,4 @@ Pages is fully supported, with no current plans to change its support status. Th ### What about Workers Sites? -We do not recommend using Workers Sites for projects. Please use Workers with static assets, or Pages. +We do not recommend using Workers Sites for projects. Please use [Workers with static assets](/workers/static-assets/), or [Pages](/pages/). From a0e739d69f43a789eb1c57d213495f94440259ae Mon Sep 17 00:00:00 2001 From: korinne Date: Mon, 3 Feb 2025 16:05:24 -0800 Subject: [PATCH 4/5] Adds redirects --- public/_redirects | 5 +++++ src/env.d.ts | 1 - 2 files changed, 5 insertions(+), 1 deletion(-) delete mode 100644 src/env.d.ts diff --git a/public/_redirects b/public/_redirects index 6a998490ad72bab..73a984e25a1ba2a 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1530,6 +1530,11 @@ /workers/runtime-apis/fetch-event/ /workers/runtime-apis/handlers/fetch/ 301 /workers/runtime-apis/add-event-listener/ /workers/reference/migrate-to-module-workers/ 301 /workers/runtime-apis/tail-event/ /workers/runtime-apis/handlers/tail/ 301 +/workers/configuration/sites/configuration/ /workers/static-assets/binding/ 301 +/workers/configuration/sites/ /workers/static-assets/ 301 +/workers/configuration/sites/start-from-existing/ /workers/static-assets/get-started/ 301 +/workers/configuration/sites/start-from-scratch/ /workers/static-assets/get-started/ 301 +/workers/configuration/sites/start-from-worker/ /workers/static-assets/get-started/ 301 /workers/wrangler/workers-kv/ /kv/ 301 /workers/databases/native-integrations/momento/ /workers/configuration/integrations/momento/ 301 /workers/databases/connect-to-postgres/ /hyperdrive/learning/connect-to-postgres/ 301 diff --git a/src/env.d.ts b/src/env.d.ts deleted file mode 100644 index 9bc5cb41c24efc4..000000000000000 --- a/src/env.d.ts +++ /dev/null @@ -1 +0,0 @@ -/// \ No newline at end of file From 299f303cc5963503afefe0c20f8eb7c147af1fa6 Mon Sep 17 00:00:00 2001 From: korinne Date: Mon, 3 Feb 2025 16:10:23 -0800 Subject: [PATCH 5/5] Adds links in FAQs --- src/content/docs/workers/static-assets/faqs.mdx | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/src/content/docs/workers/static-assets/faqs.mdx b/src/content/docs/workers/static-assets/faqs.mdx index ab675405ba24452..886bd588af71df1 100644 --- a/src/content/docs/workers/static-assets/faqs.mdx +++ b/src/content/docs/workers/static-assets/faqs.mdx @@ -7,21 +7,10 @@ head: [] description: Frequently Asked Questions --- -import { - Badge, - Description, - FileTree, - InlineBadge, - Render, - TabItem, - Tabs, - WranglerConfig, -} from "~/components"; - ### What's happening to [Pages](/pages/)? Pages is fully supported, with no current plans to change its support status. That being said, new features will land in Workers without a guarantee they will be available in Pages. ### What about Workers Sites? -We do not recommend using Workers Sites for projects. Please use Workers with static assets, or Pages. +We do not recommend using Workers Sites for projects. Please use [Workers with static assets](/workers/static-assets/), or [Pages](/pages/).