Skip to content

Commit

Permalink
routing/config
Browse files Browse the repository at this point in the history
  • Loading branch information
Tanushree Sharma committed Sep 20, 2024
1 parent e7ffa53 commit d11b947
Show file tree
Hide file tree
Showing 5 changed files with 285 additions and 228 deletions.
260 changes: 260 additions & 0 deletions src/content/docs/workers/configuration/assets.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
---
pcx_content_type: concept
title: Assets
sidebar:
order: 7
badge: Beta
head: []
description: Create a Worker with assets throught the wrangler CLI or through a Git integration.
---

import {
Badge,
Description,
FileTree,
InlineBadge,
Render,
TabItem,
Tabs,
} from "~/components";

Asset hosting on Cloudflare Workers allows developers to run frontend websites — static or dynamic — directly on our Cloudflare's global network.

## Configuration

Configuring a project with assets requires specifying a [directory](/workers/configuration/assets/#directory) and an optional [assets binding](/workers/configuration/assets/#binding) in the `wrangler.toml file`. Each Worker is limited to only one set of assets.

### Directory

Root folder of static assets to be served. For many frameworks, this is the `./public` or `./dist` folder.

```sh title="wrangler.toml"
name = "my-worker"
directory = "./public"
compatibility_date = "2024-09-19"
```

### Binding

The assets binding is used in full-stack applications. The [binding](/workers/runtime-apis/bindings) gives you access to the directory of assets from within a Worker.

```sh title="wrangler.toml"
name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-09-19"

assets = { directory = "./public", binding = "ASSETS" }
```
With this binding you can call `env.ASSETS.fetch()` to return assets on a given request.
**Example**
Your dynamic code can make or forward requests to your project’s static assets using the assets binding.
Take the following example that configures a Worker to return a response under all requests headed for `/api/`. Otherwise, the Worker will fallback to returning static assets.
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
// TODO: Add your custom /api/* logic here.
return new Response("Ok");
}
// Otherwise, serve the static assets.
// Without this, the Worker will error and no assets will be served.
return env.ASSETS.fetch(request);
},
};
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
interface Env {
ASSETS: Fetcher;
}

export default {
async fetch(request, env): Promise<Response> {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
// TODO: Add your custom /api/* logic here.
return new Response("Ok");
}
// Otherwise, serve the static assets.
// Without this, the Worker will error and no assets will be served.
return env.ASSETS.fetch(request);
},
} satisfies ExportedHandler<Env>;
```
</TabItem> </Tabs>
## Routing
### How it works
Assets are served based on file-based routing. The structure and organization of files in your project's directory determine the routing paths for your application. If a request is found with a matching path to the current route requested then that asset will always be served.
If a request does not match an asset based on file-based routing, files are served based on the configuration options defined. There are two areas of asset handling that can be configured:
1. **`html_handling`**: Trailing slashes on websites (e.g. example.com/page/ vs. example.com/page) can impact SEO because search engines treat URLs with and without trailing slashes as different, separate pages. This distinction can lead to duplicate content issues, indexing problems, and overall confusion about the correct canonical version of a page.
`html_handling` configuration determines redirects/rewrites of requests for HTML content. It is used to specify handling that redirects non-canonical URLs to canonical ones, and writes the asset path to serve the expected content at those canonical URLs.
2. **`not_found_handling`**: Handling of requests that do not map to an asset.
### Default configuration
#### 1. `html_handling`
`auto-trailing-slash` is the default mode if `html_handling` is not explicitly specified.
Take the following directory structure:
```
|---- file.html
|---- folder
|___ index.html
```
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | --------------- | ------------------ |
| /file | 200 | /file.html served |
| /file.html | 307 to /file | - |
| /file/ | 307 to /file | - |
| /file/index | 307 to /file | - |
| /file/index.html | 307 to /file | - |
| /folder | 307 to /folder/ | - |
| /folder.html | 307 to /folder/ | - |
| /folder/ | 200 | /folder/index.html |
| /folder/index | 307 /folder/ | - |
| /folder/index.html | 307 /folder/ | - |
#### 2. `not_found_handling`
**Static Site**
```
/not-found -> 404
/foo/bar/bang -> 404
/foo/bar/cat/dog -> 404
```
**Full-stack Application**
```
/not-found -> Worker
/foo/bar/bang -> Worker
/foo/bar/cat/dog -> Worker
```
Alternate configuration options are outlined on this page and can be specified in your project's wrangler.toml file. If you're deploying using a Framework[link], these options will be defined by the Framework provider.
### html_handling
Take the following directory structure:
```
|---- file.html
|---- folder
|___ index.html
```
#### `html_handling: "force-trailing-slash"`
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | --------------- | ------------------ |
| /file | 307 to /file/ | /file.html |
| /file.html | 307 to /file/ | - |
| /file/ | 200 | /file.html |
| /file/index | 307 to /file/ | - |
| /file/index.html | 307 to /file/ | - |
| /folder | 307 to /folder/ | - |
| /folder.html | 307 to /folder/ | - |
| /folder/ | 200 | /folder/index.html |
| /folder/index | 307 /folder/ | - |
| /folder/index.html | 307 /folder/ | - |
#### `html_handling: "auto-trailing-slash"`
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | -------------- | ------------------ |
| /file | 200 | /file.html |
| /file.html | 307 to /file | - |
| /file/ | 307 to /file | - |
| /file/index | 307 to /file | - |
| /file/index.html | 307 to /file | - |
| /folder | 307 to /folder | - |
| /folder.html | 307 to /folder | - |
| /folder/ | 200 | /folder/index.html |
| /folder/index | 307 /folder | - |
| /folder/index.html | 307 /folder | - |
#### `html_handling: "none"`
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | ------------------------------- | ------------------------------- |
| /file | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /file.html | 200 | /file.html |
| /file/ | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /file/index | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /file/index.html | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder.html | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder/ | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder/index | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder/index.html | 200 | /folder/index.html |
### not_found_handling
#### `not_found_handling: "single-page-application"`
**Static Site**
```
/not-found -> 200 /index.html
/foo/bar/cat/dog -> 200 /index.html
```
**Full-stack Application**
```
/not-found -> Worker
/foo/bar/cat/dog -> Worker
```
#### `not_found_handling: "404-page"`
**Static Site**
```
/not-found -> 404 /404.html
/foo/bar/cat/dog -> 404 /404.html
```
Define a custom page to be displayed when there is no match for the requested file by creating a 404.html file. If one is not found in the same directory as the route you are currently requesting, it will continue to look up the directory tree for a matching 404.html file. This means that you can define custom 404 paths for situations like /blog/404.html and /404.html, and Workers will automatically render the correct one depending on the situation.
**Full-stack Application**
```
/not-found -> Worker
/foo/bar/cat/dog -> Worker
```
## Encoding
// TO-DO
127 changes: 0 additions & 127 deletions src/content/docs/workers/frameworks/configuration.mdx

This file was deleted.

Loading

0 comments on commit d11b947

Please sign in to comment.