From dc34a84856638504ffdac5ab9859814fc5a346ac Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Thu, 3 Oct 2024 16:05:47 +0200 Subject: [PATCH 1/4] Make Compat Matrix more comprehensive Attempts to cover all the differences between Workers and Pages --- .../static-assets/compatibility-matrix.mdx | 73 ++++++++++++++----- 1 file changed, 55 insertions(+), 18 deletions(-) diff --git a/src/content/docs/workers/static-assets/compatibility-matrix.mdx b/src/content/docs/workers/static-assets/compatibility-matrix.mdx index f494123cd8874f..b2edba35e10b22 100644 --- a/src/content/docs/workers/static-assets/compatibility-matrix.mdx +++ b/src/content/docs/workers/static-assets/compatibility-matrix.mdx @@ -17,29 +17,42 @@ import { Tabs, } from "~/components"; -Cloudflare [Workers with static assets](/workers/static-assets/) and [Pages](/pages/) both have the ability to host front-end and full-stack applications. The following compatibility matrix shows the features are available for each product to help you when choosing which product to start with. +You can deply full-stack applications, including front-end static assets and back-end APIs and 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). We plan to bridge the gaps between Workers and Pages and provide ways to migrate your Pages projects to Workers. -| | Asset hosting on Workers | Pages | + +| | Workers | Pages | | ----------------------------------------------------------------------------------- | ------------------------ | ----- | -| **Features** | | | -| Middleware | ❌ 1 | ✅ | -| [Redirects](/pages/configuration/redirects/) | ❌ 2 | ✅ | -| [Smart Placement](/workers/configuration/smart-placement/) | ⏳ 3 | ✅ | +| **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](/workers/testing) | ✅ | ✅ | +| [Local Development](/workers/testing/local-development/) | ✅ | ✅ | +| [Remote Development (`--remote`)](/workers/wrangler/commands/) | ✅ 1 | ❌ | +| [Quick Editor in Dashboard](https://blog.cloudflare.com/improved-quick-edit) | ✅ | ❌ | +| **Static Assets** | | | +| [Early Hints](/pages/configuration/early-hints/) | ❌ | ✅ | +| [Customize HTTP headers of static assets](/pages/configuration/headers/) | 🟡 2 | ✅ | +| [Middleware](/pages/functions/middleware/) | 🟡 3 | ✅ | +| [Redirects](/pages/configuration/redirects/) | 🟡 4 | ✅ | +| [Smart Placement](/workers/configuration/smart-placement/) | ⏳ 5 | ✅ | | **Observability** | | | | [Workers Logs](/workers/observability/) | ✅ | ❌ | -| [Logpush](/workers/observability/logs/logpush/) | ✅ | ❌ | -| [Tail Workers](/workers/observability/logs/tail-workers/) | ⏳ 4 | ❌ | -| [Real-time logs](/workers/observability/logs/real-time-logs/) | ✅ | ✅ | -| **Bindings** | | | +| [Logpush](/workers/observability/logs/logpush/) | ✅ | ❌ | +| [Tail Workers](/workers/observability/logs/tail-workers/) | ⏳ 6 | ❌ | +| [Real-time logs](/workers/observability/logs/real-time-logs/) | ✅ | ✅ | +| **Runtime APIs & Compute Models** | | | +| [Node.js Compatibility Mode](/workers/runtime-apis/nodejs/) | ✅ | ✅ | +| [Durable Objects](/durable-objects/api/) | ✅ | 🟡 7 | +| [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/build-with-d1/d1-client-api/) | ✅ | ✅ | -| [Durable Objects](/durable-objects/api/) | ✅ | ❌ | | [Environment Variables](/workers/configuration/environment-variables/) | ✅ | ✅ | | [Hyperdrive](/hyperdrive/) | ✅ | ❌ | | [KV](/kv/) | ✅ | ✅ | @@ -51,22 +64,46 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate | [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](/pages/configuration/build-watch-paths/) | ❌ | ✅ | +| [Deploy Hooks](/pages/configuration/deploy-hooks/) | ❌ | ✅ | +| [Build Caching](/pages/configuration/build-caching/) | ❌ | ✅ | +| [Custom Preview Branches](/pages/configuration/branch-build-controls/) | ❌ | ✅ | +| [Custom Branch Aliases](/pages/how-to/custom-branch-aliases/) | ❌ | ✅ | +| **Pages Functions** | | | +| [File-based Routing](/pages/functions/routing/) | ❌ 8 | ✅ | +| [Pages Plugins](/pages/functions/plugins/) | ❌ 9 | ✅ | + -1 If you need to run a Worker script ahead of serving static assets, -we currently recommend using [Service +1 For more details on which bindings are supported in remote development, [refer to the docs]((/workers/testing/local-development/#supported-resource-bindings-in-different-environments) + +2 Similar to 1, 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. We plan to explore additional configuration +in front of the Worker with assets. + +3 If you need to run a Worker before serving static assets, +you can create a separate Worker that acts as middleware, and then use [Service +bindings](/workers/runtime-apis/bindings/service-bindings/) to forward the request +to the Worker with assets. We plan to explore additional configuration to support more complex routing in the future. -2 You can handle redirects by adding code to your Worker (a +4 You can handle redirects by adding code to your Worker (a [community package](https://npmjs.com/package/redirects-in-workers) is available for `_redirects` support), or you can use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/). -3 You cannot yet enable [Smart -Placement](/workers/configuration/smart-placement/) projects with static assets. +5 You cannot yet enable [Smart +Placement](/workers/configuration/smart-placement/) for Workers with static assets. This is a temporary limitation, we are working to remove it. -4 You cannot yet add a [Tail +6 You cannot yet add a [Tail Worker](/workers/observability/logs/tail-workers/) to a project with assets. This is a temporary limitation, we are working to remove it. + +7 To [use Durable Objects with your Cloudflare Pages project](/pages/functions/bindings/#durable-objects), you must create a separate Worker with a Durable Object, and then declare a binding to it in both your Production and Preview environments. Using Durable Objects with Workers is simpler, and recommended. + +8 Workers [supports popular frameworks](/workers/frameworks/), many of which implement file-based routing. + +9 Everything that is possible with Pages Functions, can also be achieved by adding code to your Worker, or using framework-specific plugins for relevant third party tools. From 7f4eacdf5324cc9f77df0942bd269558e2d89c67 Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Wed, 9 Oct 2024 09:16:45 -0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Tanushree <87711021+tanushree-sharma@users.noreply.github.com> --- .../docs/workers/static-assets/compatibility-matrix.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/workers/static-assets/compatibility-matrix.mdx b/src/content/docs/workers/static-assets/compatibility-matrix.mdx index b2edba35e10b22..7b4ce5f271f077 100644 --- a/src/content/docs/workers/static-assets/compatibility-matrix.mdx +++ b/src/content/docs/workers/static-assets/compatibility-matrix.mdx @@ -28,13 +28,13 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate | [Rollbacks](/workers/configuration/versions-and-deployments/rollbacks/) | ✅ | ✅ | | [Gradual Deployments](/workers/configuration/versions-and-deployments/) | ✅ | ❌ | | [Preview URLs](/workers/configuration/previews) | ✅ | ✅ | -| [Testing](/workers/testing) | ✅ | ✅ | +| [Testing tools](/workers/testing) | ✅ | ✅ | | [Local Development](/workers/testing/local-development/) | ✅ | ✅ | | [Remote Development (`--remote`)](/workers/wrangler/commands/) | ✅ 1 | ❌ | | [Quick Editor in Dashboard](https://blog.cloudflare.com/improved-quick-edit) | ✅ | ❌ | | **Static Assets** | | | | [Early Hints](/pages/configuration/early-hints/) | ❌ | ✅ | -| [Customize HTTP headers of static assets](/pages/configuration/headers/) | 🟡 2 | ✅ | +| [Custom HTTP headers for static assets](/pages/configuration/headers/) | 🟡 2 | ✅ | | [Middleware](/pages/functions/middleware/) | 🟡 3 | ✅ | | [Redirects](/pages/configuration/redirects/) | 🟡 4 | ✅ | | [Smart Placement](/workers/configuration/smart-placement/) | ⏳ 5 | ✅ | @@ -76,7 +76,7 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate | [Pages Plugins](/pages/functions/plugins/) | ❌ 9 | ✅ | -1 For more details on which bindings are supported in remote development, [refer to the docs]((/workers/testing/local-development/#supported-resource-bindings-in-different-environments) +1 For more details on which bindings are supported in remote development, [refer to the docs](/workers/testing/local-development/#supported-resource-bindings-in-different-environments) 2 Similar to 1, to customize the HTTP headers that are returned by static assets, you can use [Service From 52d25d01cd4532a86c5b6b44c9aa9613505dc2b8 Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Wed, 9 Oct 2024 12:10:39 -0700 Subject: [PATCH 3/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thomas Gauvin <35609369+thomasgauvin@users.noreply.github.com> Co-authored-by: Denise Peña <75506267+dcpena@users.noreply.github.com> --- .../workers/static-assets/compatibility-matrix.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/workers/static-assets/compatibility-matrix.mdx b/src/content/docs/workers/static-assets/compatibility-matrix.mdx index 7b4ce5f271f077..00d7e45220d8e2 100644 --- a/src/content/docs/workers/static-assets/compatibility-matrix.mdx +++ b/src/content/docs/workers/static-assets/compatibility-matrix.mdx @@ -17,7 +17,7 @@ import { Tabs, } from "~/components"; -You can deply full-stack applications, including front-end static assets and back-end APIs and 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 and 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). We plan to bridge the gaps between Workers and Pages and provide ways to migrate your Pages projects to Workers. @@ -76,7 +76,7 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate | [Pages Plugins](/pages/functions/plugins/) | ❌ 9 | ✅ | -1 For more details on which bindings are supported in remote development, [refer to the docs](/workers/testing/local-development/#supported-resource-bindings-in-different-environments) +1 For more details on which bindings are supported in remote development, [refer to the docs](/workers/testing/local-development/#supported-resource-bindings-in-different-environments). 2 Similar to 1, to customize the HTTP headers that are returned by static assets, you can use [Service @@ -96,14 +96,14 @@ Redirects](/rules/url-forwarding/bulk-redirects/). 5 You cannot yet enable [Smart Placement](/workers/configuration/smart-placement/) for Workers with static assets. -This is a temporary limitation, we are working to remove it. +This is a temporary limitation we are working to remove. 6 You cannot yet add a [Tail Worker](/workers/observability/logs/tail-workers/) to a project with assets. This is a temporary limitation, we are working to remove it. -7 To [use Durable Objects with your Cloudflare Pages project](/pages/functions/bindings/#durable-objects), you must create a separate Worker with a Durable Object, and then declare a binding to it in both your Production and Preview environments. Using Durable Objects with Workers is simpler, and recommended. +7 To [use Durable Objects with your Cloudflare Pages project](/pages/functions/bindings/#durable-objects), you must create a separate Worker with a Durable Object and then declare a binding to it in both your Production and Preview environments. Using Durable Objects with Workers is simpler and recommended. 8 Workers [supports popular frameworks](/workers/frameworks/), many of which implement file-based routing. -9 Everything that is possible with Pages Functions, can also be achieved by adding code to your Worker, or using framework-specific plugins for relevant third party tools. +9 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. From e6008014a46f5b6143d173545640bd2b9936121f Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Thu, 10 Oct 2024 10:59:15 -0700 Subject: [PATCH 4/4] Update src/content/docs/workers/static-assets/compatibility-matrix.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Denise Peña <75506267+dcpena@users.noreply.github.com> --- src/content/docs/workers/static-assets/compatibility-matrix.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/static-assets/compatibility-matrix.mdx b/src/content/docs/workers/static-assets/compatibility-matrix.mdx index 00d7e45220d8e2..8124ab9aa39203 100644 --- a/src/content/docs/workers/static-assets/compatibility-matrix.mdx +++ b/src/content/docs/workers/static-assets/compatibility-matrix.mdx @@ -100,7 +100,7 @@ This is a temporary limitation we are working to remove. 6 You cannot yet add a [Tail Worker](/workers/observability/logs/tail-workers/) to a project with assets. -This is a temporary limitation, we are working to remove it. +This is a temporary limitation we are working to remove. 7 To [use Durable Objects with your Cloudflare Pages project](/pages/functions/bindings/#durable-objects), you must create a separate Worker with a Durable Object and then declare a binding to it in both your Production and Preview environments. Using Durable Objects with Workers is simpler and recommended.