Skip to content

Commit f789349

Browse files
committed
docs: improve docs around cache control order and redirects
1 parent f4f3290 commit f789349

File tree

3 files changed

+35
-4
lines changed

3 files changed

+35
-4
lines changed

packages/docs/src/routes/docs/(qwikcity)/caching/index.mdx

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,6 @@ export default component$(() => {
4747

4848
With the above setup, you will not only have better performance (pages are always served instantly from cache), but you can also have significantly decreased hosting costs, as our server or edge functions only need to run at most once every 5 seconds per page.
4949

50-
## `cacheControl`
51-
52-
Any method that takes a [request event](https://qwik.dev/docs/advanced/request-handling/#request-event) can call `request.cacheControl` to set the cache control headers for the response:
53-
5450
```tsx title="src/routes/layout.tsx"
5551
import type { RequestHandler } from "@builder.io/qwik-city";
5652

@@ -83,6 +79,22 @@ export const onGet: RequestHandler = async ({ cacheControl }) => {
8379

8480
You can see the full [API reference](https://qwik.dev/api/qwik-city-middleware-request-handler/) of options you can pass to `request.cacheControl`.
8581

82+
## `cacheControl` Order
83+
84+
Any method that takes a [request event](https://qwik.dev/docs/advanced/request-handling/#request-event) can call `request.cacheControl` to set the cache control headers for the response.
85+
86+
Qwik City executes request handlers in a specific order. This is important because if multiple handlers set the cache control policy, **the last one to execute wins**.
87+
88+
The execution order is as follows:
89+
90+
1. **Middleware (`src/middleware/index.ts`)**
91+
2. **Layouts (from the root layout downwards)**
92+
3. **Page endpoints (`src/routes/..../index.tsx`)**
93+
94+
This means that the cache control set in a page's `onGet` handler will override any cache control set in a layout or middleware. For example, you can set a default cache policy in a root layout, and then override it in a specific page.
95+
96+
When using `redirect()`, there is a special case for caching. See [redirects and caching](/docs/(qwikcity)/guides/redirects/#caching) for more information.
97+
8698
## When not to cache
8799

88100
Caching is generally beneficial, but not right for every page all the time. If your site has URLs that will show different content to different people — for example, pages exclusive to logged-in users or pages that show content based on a user's location — you should avoid using cache-control headers to cache these pages. Instead, render the content of these pages on the server side on a per-visitor basis.

packages/docs/src/routes/docs/(qwikcity)/guides/redirects/index.mdx

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,23 @@ If you do not provide a status code, Qwik City will default to a `302` Found sta
5353

5454
Read more about redirect status codes [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages).
5555

56+
## Caching
57+
58+
When you issue a redirect using the `redirect()` method from the `RequestEvent`, Qwik City applies a default cache control policy if one hasn't been explicitly set. This includes `Cache-Control` headers set in a higher-level layout or middleware. For more details on the order of execution, see the [caching documentation](/docs/caching/).
59+
60+
If the redirect's status code is greater than `301` (e.g., `302`, `307`), and you haven't called `cacheControl()` for that request, the `Cache-Control` header will automatically be set to `'no-store'`. This prevents the redirect from being cached by the browser or intermediate caches.
61+
62+
```typescript
63+
export const onGet: RequestHandler = ({ redirect, cacheControl }) => {
64+
// This will result in a `Cache-Control: no-store` header except if cacheControl was called in a middleware or layout above.
65+
throw redirect(302, '/new-location');
66+
67+
// To override the default, set it explicitly
68+
cacheControl('day');
69+
throw redirect(302, '/new-location');
70+
};
71+
```
72+
5673
## Managing multiple redirects
5774

5875
In some cases, you may need to manage multiple redirects based on different conditions. For example, you might want to redirect users from old URLs to new URLs after a site restructure. Additionally, you may want editors in a CMS to manage these redirects as well. Here's one of the ways you can handle multiple redirects in Qwik:

packages/docs/src/routes/docs/(qwikcity)/middleware/index.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -460,6 +460,8 @@ export const onGet: RequestHandler = async ({ status, getWritableStream }) => {
460460

461461
Redirect to a new URL. Notice the importance of throwing to prevent other middleware functions from running. The `redirect()` method will automatically set the `Location` header to the redirect URL.
462462

463+
> **Note**: When using `redirect()`, Qwik City applies a default `Cache-Control` header of `no-store` for redirects with a status code greater than 301. You can learn more about this behavior in the [redirects guide](/docs/guides/redirects/#caching).
464+
463465
<CodeSandbox src="/src/routes/demo/qwikcity/middleware/redirect/index.tsx">
464466
```tsx
465467
import { type RequestHandler } from '@builder.io/qwik-city';

0 commit comments

Comments
 (0)