Skip to content

Commit 756b8b0

Browse files
GregBrimbleGregBrimble
authored
Workers with static assets metafiles support (#21442)
* Workers static assets metafiles support * Add Type/MetaInfo components to redirects docs * Migration guide (#21489) * Workers static assets metafiles support * Migration guide for Pages -> Workers * Fix links * Fix build command * Fix link
1 parent 9d05db2 commit 756b8b0

26 files changed

+911
-478
lines changed

‎public/__redirects‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1527,6 +1527,7 @@
15271527
/workers/tutorials/create-sitemap-from-sanity-cms/ /developer-spotlight/tutorials/create-sitemap-from-sanity-cms/ 301
15281528
/workers/tutorials/custom-access-control-for-files-in-r2-using-d1-and-workers/ /developer-spotlight/tutorials/custom-access-control-for-files/ 301
15291529
/workers/tutorials/generate-dynamic-og-images-using-workers/ /workers/tutorials/ 302
1530+
/workers/static-assets/compatibility-matrix/ /workers/static-assets/migrate-from-pages/ 301
15301531
/workers/frameworks/framework-guides/remix/ /workers/frameworks/framework-guides/react-router/ 301
15311532

15321533
# workers ai

‎src/content/docs/pages/configuration/headers.mdx‎

Lines changed: 2 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,8 @@
11
---
22
pcx_content_type: concept
33
title: Headers
4-
54
---
65

7-
import { Render } from "~/components"
8-
9-
## Attach a header
10-
11-
To attach headers to Cloudflare Pages responses, create a `_headers` plain text file in the output folder of your project. It is usually the folder that contains the deploy-ready HTML files and assets generated by the build, such as favicons. Changes to headers will be updated to your website at build time. Make sure you commit and push the file to trigger a new build each time you update headers.
12-
13-
:::caution
14-
15-
16-
Custom headers defined in the `_headers` file are not applied to responses from [Functions](/pages/functions/), even if the Function route matches the URL pattern. If your Pages application uses Functions, you must migrate any behaviors from the `_headers` file to the `Response` object in the appropriate `/functions` route. When altering headers for multiple routes, you may be interested in [adding middleware](/pages/functions/middleware/) for shared behavior.
17-
18-
19-
:::
20-
21-
Header rules are defined in multi-line blocks. The first line of a block is the URL or URL pattern where the rule's headers should be applied. On the next line, an indented list of header names and header values must be written:
22-
23-
```txt
24-
[url]
25-
[name]: [value]
26-
```
27-
28-
Using absolute URLs is supported, though be aware that absolute URLs must begin with `https` and specifying a port is not supported. Cloudflare Pages ignores the incoming request's port and protocol when matching against an incoming request. For example, a rule like `https://example.com/path` would match against requests to `other://example.com:1234/path`.
29-
30-
You can define as many `[name]: [value]` pairs as you require on subsequent lines. For example:
31-
32-
```txt
33-
# This is a comment
34-
/secure/page
35-
X-Frame-Options: DENY
36-
X-Content-Type-Options: nosniff
37-
Referrer-Policy: no-referrer
38-
39-
/static/*
40-
Access-Control-Allow-Origin: *
41-
X-Robots-Tag: nosnippet
42-
43-
https://myproject.pages.dev/*
44-
X-Robots-Tag: noindex
45-
```
46-
47-
An incoming request which matches multiple rules' URL patterns will inherit all rules' headers. Using the previous `_headers` file, the following requests will have the following headers applied:
48-
49-
| Request URL | Headers |
50-
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
51-
| `https://custom.domain/secure/page` | `X-Frame-Options: DENY` <br /> `X-Content-Type-Options: nosniff ` <br /> `Referrer-Policy: no-referrer` |
52-
| `https://custom.domain/static/image.jpg` | `Access-Control-Allow-Origin: *` <br /> `X-Robots-Tag: nosnippet` |
53-
| `https://myproject.pages.dev/home` | `X-Robots-Tag: noindex` |
54-
| `https://myproject.pages.dev/secure/page` | `X-Frame-Options: DENY` <br /> `X-Content-Type-Options: nosniff` <br /> `Referrer-Policy: no-referrer` <br /> `X-Robots-Tag: noindex` |
55-
| `https://myproject.pages.dev/static/styles.css` | `Access-Control-Allow-Origin: *` <br /> `X-Robots-Tag: nosnippet, noindex` |
56-
57-
A project is limited to 100 header rules. Each line in the `_headers` file has a 2,000 character limit. The entire line, including spacing, header name, and value, counts towards this limit.
58-
59-
If a header is applied twice in the `_headers` file, the values are joined with a comma separator. Headers defined in the `_headers` file override what Cloudflare Pages ordinarily sends, so be aware when setting security headers. Cloudflare reserves the right to attach new headers to Pages projects at any time in order to improve performance or harden the security of your deployments.
60-
61-
### Detach a header
62-
63-
You may wish to remove a header which has been added by a more pervasive rule. This can be done by prepending an exclamation mark `!`.
64-
65-
```txt
66-
/*
67-
Content-Security-Policy: default-src 'self';
68-
69-
/*.jpg
70-
! Content-Security-Policy
71-
```
72-
73-
### Match a path
74-
75-
The same URL matching features that [`_redirects`](/pages/configuration/redirects/) offers is also available to the `_headers` file. Note, however, that redirects are applied before headers, when a request matches both a redirect and a header, the redirect takes priority.
76-
77-
#### Splats
78-
79-
When matching, a splat pattern — signified by an asterisk (`*`) — will greedily match all characters. You may only include a single splat in the URL.
80-
81-
The matched value can be referenced within the header value as the `:splat` placeholder.
82-
83-
#### Placeholders
84-
85-
<Render file="headers_redirects_placeholders" params={{ one: "header" }} />
86-
87-
```txt
88-
/movies/:title
89-
x-movie-name: You are watching ":title"
90-
```
91-
92-
## Examples
93-
94-
### Cross-Origin Resource Sharing (CORS)
95-
96-
To enable other domains to fetch every asset from your Pages project, the following can be added to the `_headers` file:
97-
98-
```txt
99-
/*
100-
Access-Control-Allow-Origin: *
101-
```
102-
103-
This applies the `Access-Control-Allow-Origin` header to any incoming URL. To be more restrictive, you can define a URL pattern that applies to a `*.pages.dev` subdomain, which then only allows access from its `staging` branch's subdomain:
104-
105-
```txt
106-
https://:project.pages.dev/*
107-
Access-Control-Allow-Origin: https://staging.:project.pages.dev/
108-
```
109-
110-
### Prevent your pages.dev deployments showing in search results
111-
112-
[Google](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) and other search engines often support the `X-Robots-Tag` header to instruct its crawlers how your website should be indexed.
113-
114-
For example, to prevent your `*.pages.dev` deployment from being indexed, add the following to your `_headers` file:
115-
116-
```txt
117-
https://:project.pages.dev/*
118-
X-Robots-Tag: noindex
119-
```
120-
121-
### Harden security for an application
122-
123-
:::note
124-
125-
126-
If you are using Pages Functions and wish to attach security headers in order to control access to or browser behavior of server-side logic, the headers should be sent from in Pages Functions' `Response` instead of the `_headers` file. For example, if you have an API endpoint and want to allow cross-origin requests, you should ensure that your Pages Functions attaches CORS headers to its responses, including to `OPTIONS` requests. This is to ensure that, in the unlikely event of an incident involving serving static assets, your API security headers will continue to be configured.
127-
128-
129-
:::
130-
131-
You can prevent click-jacking by informing browsers not to embed your application inside another (for example, with an `<iframe>`) with a [`X-Frame-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) header.
132-
133-
[`X-Content-Type-Options: nosniff`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) prevents browsers from interpreting a response as any other content-type than what is defined with the `Content-Type` header.
134-
135-
[`Referrer-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) allows you to customize how much information visitors give about where they are coming from when they navigate away from your page.
136-
137-
Browser features can be disabled to varying degrees with the [`Permissions-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy) header (recently renamed from `Feature-Policy`).
138-
139-
If you need fine-grained control over your application's content, the [`Content-Security-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) header allows you to configure a number of security settings, including similar controls to the `X-Frame-Options` header.
6+
import { Render } from "~/components";
1407

141-
```txt
142-
/app/*
143-
X-Frame-Options: DENY
144-
X-Content-Type-Options: nosniff
145-
Referrer-Policy: no-referrer
146-
Permissions-Policy: document-domain=()
147-
Content-Security-Policy: script-src 'self'; frame-ancestors 'none';
148-
```
8+
<Render product="workers" file="custom_headers" params={{ product: "pages" }} />

‎src/content/docs/pages/configuration/redirects.mdx‎

Lines changed: 2 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -1,165 +1,8 @@
11
---
22
pcx_content_type: concept
33
title: Redirects
4-
54
---
65

7-
import { Render } from "~/components"
8-
9-
To use redirects on Cloudflare Pages, declare your redirects in a plain text file called `_redirects` without a file extension, in the output folder of your project. The [build output folder](/pages/configuration/build-configuration/) is project-specific, so the `_redirects` file should not always be in the root directory of the repository. Changes to redirects will be updated to your website at build time so make sure you commit and push the file to trigger a new build each time you update redirects.
10-
11-
:::caution
12-
13-
14-
Redirects defined in the `_redirects` file are not applied to requests served by [Functions](/pages/functions/), even if the Function route matches the URL pattern. If your Pages application uses Functions, you must migrate any behaviors from the `_redirects` file to the code in the appropriate `/functions` route, or [exclude the route from Functions](/pages/functions/routing/#create-a-_routesjson-file).
15-
16-
17-
:::
18-
19-
## Structure
20-
21-
### Per line
22-
23-
Only one redirect can be defined per line and must follow this format, otherwise it will be ignored.
24-
25-
```txt
26-
[source] [destination] [code?]
27-
```
28-
29-
30-
31-
* `source` required
32-
33-
* A file path.
34-
* Can include [wildcards (`*`)](#splats) and [placeholders](#placeholders).
35-
* Because fragments are evaluated by your browser and not Cloudflare's network, any fragments in the source are not evaluated.
36-
* `destination` required
37-
38-
* A file path or external link.
39-
* Can include fragments, query strings, [splats](#splats), and [placeholders](#placeholders).
40-
* `code` default: `302`
41-
42-
* Optional parameter
43-
44-
45-
46-
Lines starting with a `#` will be treated as comments.
47-
48-
### Per file
49-
50-
A project is limited to 2,000 static redirects and 100 dynamic redirects, for a combined total of 2,100 redirects. Each redirect declaration has a 1,000-character limit.
51-
52-
In your `_redirects` file:
53-
54-
* The order of your redirects matter. If there are multiple redirects for the same `source` path, the topmost redirect is applied.
55-
* Static redirects should appear before dynamic redirects.
56-
* Redirects are always followed, regardless of whether or not an asset matches the incoming request.
57-
58-
A complete example with multiple redirects may look like the following:
59-
60-
```txt
61-
/home301 / 301
62-
/home302 / 302
63-
/querystrings /?query=string 301
64-
/twitch https://twitch.tv
65-
/trailing /trailing/ 301
66-
/notrailing/ /nottrailing 301
67-
/page/ /page2/#fragment 301
68-
/blog/* https://blog.my.domain/:splat
69-
/products/:code/:name /products?code=:code&name=:name
70-
```
71-
72-
:::note
73-
74-
75-
In the case of some frameworks, such as Jekyll, you may need to manually copy and paste your `_redirects` file to the build output directory. To do this:
76-
77-
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
78-
2. Go to **Workers & Pages** > your Pages project > **Settings** > **Builds & deployments**.
79-
3. Go to **Build configurations** > **Edit configurations** > change the build command to `jekyll build && cp _redirects _site/_redirects` and select **Save**.
80-
81-
82-
:::
83-
84-
## Advanced redirects
85-
86-
Cloudflare currently offers limited support for advanced redirects. More support will be added in the future.
87-
88-
89-
90-
| Feature | Support | Example | Notes |
91-
| ----------------------------------- | ------- | --------------------------------------------------------------- | --------------------------------------- |
92-
| Redirects (301, 302, 303, 307, 308) | Yes | `/home / 301` | 302 is used as the default status code. |
93-
| Rewrites (other status codes) | No | `/blog/* /blog/404.html 404` | |
94-
| Splats | Yes | `/blog/* /posts/:splat` | Refer to [Splats](#splats). |
95-
| Placeholders | Yes | `/blog/:year/:month/:date/:slug /news/:year/:month/:date/:slug` | Refer to [Placeholders](#placeholders). |
96-
| Query Parameters | No | `/shop id=:id /blog/:id 301` | |
97-
| Proxying | Yes | `/blog/* /news/:splat 200` | Refer to [Proxying](#proxying). |
98-
| Domain-level redirects | No | `workers.example.com/* workers.example.com/blog/:splat 301` | |
99-
| Redirect by country or language | No | `/ /us 302 Country=us` | |
100-
| Redirect by cookie | No | `/\* /preview/:splat 302 Cookie=preview` | |
101-
102-
103-
104-
## Redirects and header matching
105-
106-
Redirects execute before headers, so in the case of a request matching rules in both files, the redirect will win out.
107-
108-
### Splats
109-
110-
On matching, a splat (asterisk, `*`) will greedily match all characters. You may only include a single splat in the URL.
111-
112-
The matched value can be used in the redirect location with `:splat`.
113-
114-
### Placeholders
115-
116-
<Render file="headers_redirects_placeholders" params={{ one: "redirect" }} />
117-
118-
```txt
119-
/movies/:title /media/:title
120-
```
121-
122-
### Proxying
123-
124-
Proxying will only support relative URLs on your site. You cannot proxy external domains.
125-
126-
Only the first redirect in your will apply. For example, in the following example, a request to `/a` will render `/b`, and a request to `/b` will render `/c`, but `/a` will not render `/c`.
127-
128-
```
129-
/a /b 200
130-
/b /c 200
131-
```
132-
133-
:::note
134-
135-
Be aware that proxying pages can have an adverse effect on search engine optimization (SEO). Search engines often penalize websites that serve duplicate content. Consider adding a `Link` HTTP header which informs search engines of the canonical source of content.
136-
137-
For example, if you have added `/about/faq/* /about/faqs 200` to your `_redirects` file, you may want to add the following to your `_headers` file:
138-
139-
```txt
140-
/about/faq/*
141-
Link: </about/faqs>; rel="canonical"
142-
```
143-
144-
145-
:::
146-
147-
## Surpass `_redirects` limits
148-
149-
A [`_redirects`](/pages/platform/limits/#redirects) file has a maximum of 2,000 static redirects and 100 dynamic redirects, for a combined total of 2,100 redirects. Use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/) to handle redirects that surpasses the 2,100 redirect rules limit set by Pages.
150-
151-
:::note
152-
153-
154-
The redirects defined in the `_redirects` file of your build folder can work together with your Bulk Redirects. In case of duplicates, Bulk Redirects will run in front of your Pages project, where your other redirects live.
155-
156-
For example, if you have Bulk Redirects set up to direct `abc.com` to `xyz.com` but also have `_redirects` set up to direct `xyz.com` to `foo.com`, a request for `abc.com` will eventually redirect to `foo.com`.
157-
158-
159-
:::
160-
161-
To use Bulk Redirects, refer to the [Bulk Redirects dashboard documentation](/rules/url-forwarding/bulk-redirects/create-dashboard/) or the [Bulk Redirects API documentation](/rules/url-forwarding/bulk-redirects/create-api/).
162-
163-
## Related resources
6+
import { Render } from "~/components";
1647

165-
* [Transform Rules](/rules/transform/)
8+
<Render product="workers" file="redirects" params={{ product: "pages" }} />

0 commit comments

Comments
 (0)