-
Notifications
You must be signed in to change notification settings - Fork 5.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Tanushree Sharma
committed
Sep 20, 2024
1 parent
e7ffa53
commit d11b947
Showing
5 changed files
with
285 additions
and
228 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.