From c68c757a2eeefa3e0afaadbe99dae994b02c9e49 Mon Sep 17 00:00:00 2001 From: dinasaur_404 Date: Wed, 29 Jan 2025 12:13:39 -0500 Subject: [PATCH 1/8] docs: add static assets documentation for Workers for Platforms --- .../configuration/static-assets.mdx | 246 +++++++++++++++++- 1 file changed, 244 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index 360660fabd61837..bbb327d78438e5f 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -1,5 +1,247 @@ --- -pcx_content_type: navigation +pcx_content_type: concept title: Static Assets -external_link: /workers/static-assets/direct-upload/ --- +Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare’s global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers. +## What you can build + +#### Static sites +Host and serve HTML, CSS, JavaScript, and media files drectly from Cloudflare’s network, ensuring fast loading times worldwide. This is ideal for blogs, landing pages, and documentation sites. + +#### Full-stack applications +Combine asset hosting with Cloudflare Workers to power dynamic, interactive applications. Store and retrieve data using Cloudflare KV, D1, and R2 Storage, allowing you to serve both front-end assets and backend logic from a single Worker. + +## Benefits +#### Global caching for faster performance +Cloudflare automatically caches static assets at data centers worldwide, reducing latency and improving load times by up to 2x for users everywhere. + +#### Scalability without infrastructure management +Your applications scale automatically to handle high traffic without requiring you to provision or manage infrastructure. Cloudflare dynamically adjusts to demand in real time. + +#### Unified deployment for static and dynamic content +Deploy front-end assets alongside server-side logic, all within Cloudflare Workers. This eliminates the need for a separate hosting provider and ensures a streamlined deployment process. + +## Deploying static assets to User Workers + +It's common that as the Platform, you will be responsible for uploading static assets on behalf of your end users. This often looks like this: + +1. User uploads files (HTML, CSS, images) through your interface. +2. Your platform interacts with the Workers for Platforms APIs to attach the static assets to the User Worker script. + +Once you receive the static files from your users (for a new or updated site), complete the following steps to attach the files to the corresponding User Worker: + +1. Create an Upload Session +2. Upload file contents +3. Deploy/Update the Worker + +After these steps are completed, the User Worker's static assets will be live on Cloudflare's edge. + +### 1. Create an Upload Session + +Before sending any file data, you need to tell Cloudflare which files you intend to upload. That list of files is called a manifest. Each item in the manifest includes: + +* A file path (for example, `"/index.html"` or `"/assets/logo.png"`) +* A hash (32-hex characters) representing the file contents +* The file size in bytes + +**Example manifest (JSON):** + +```json +{ + "/index.html": { + "hash": "08f1dfda4574284ab3c21666d1ee8c7d4", + "size": 1234 + }, + "/styles.css": { + "hash": "36b8be012ee77df5f269b11b975611d3", + "size": 5678 + } +} +``` + +To start the upload process, send a POST request to the Create Assets Upload Session [API endpoint](https://developers.cloudflare.com/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/asset_upload/methods/create/) + +```bash +POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session +``` + +Path Parameters: +* `namespace`: Name of the Workers for Platforms dispatch namespace +* `script_name`: Name of the User Worker + +In the request body, include a JSON object listing each file path along with its hash and size. This helps Cloudflare identify which files you intend to upload and allows Cloudflare to check if any of them are already stored. + +**Sample request:** + +```bash +curl -X POST \ + "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME/assets-upload-session" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" \ + --data '{ + "manifest": { + "/index.html": { + "hash": "08f1dfda4574284ab3c21666d1ee8c7d4", + "size": 1234 + }, + "/styles.css": { + "hash": "36b8be012ee77df5f269b11b975611d3", + "size": 5678 + } + } + }' +``` + +**Generating the hash** + +You can compute a SHA-256 digest of the file contents, then truncate or otherwise represent it consistently as a 32-hex-character string. Make sure to do it the same way each time so Cloudflare can reliably match files across uploads. + +**API Response** + +If all the files are already stored on Cloudflare, the response will only return the JWT token. If new or updated files are needed, the response will return: +* `jwt`: An upload token (valid for 1 hour) which will be used in the API request to upload the file contents (Step 2) +* `buckets`: An array of file-hash groups indicating which files to upload together. Files that have been recently uploaded won’t appear in buckets, since Cloudflare already has them. + +**Note**: This step alone does not store files on Cloudflare. You must upload the actual file data in the next step. + +### 2. Upload File Contents + +If the response to the Upload Session API returns `buckets`, that means you have new or changed files that need to be uploaded to Cloudflare. + +Use the [Workers Assets Upload API](https://developers.cloudflare.com/api/resources/workers/subresources/assets/subresources/upload/) to transmit the raw file bytes in base64-encoded format for any missing or changed files. Once uploaded, Cloudflare will store these files so they can then be attached to a User Worker. + +**API Request Authentication** + +Unlike most Cloudflare API calls that use an account-wide API token in the Authorization header, uploading file contents requires using the short-lived JWT token returned in the `jwt` field of the `assets-upload-session` response. + +Include it as a Bearer token in the header: + +```bash +Authorization: Bearer +``` + +This token is valid for one hour and must be supplied for each upload request to the Workers Assets Upload API. + +**File fields (multipart/form-data)** +You must send the files as multipart/form-data with base64-encoded content: + +* Field name: The file hash (for example, "36b8be012ee77df5f269b11b975611d3") +* Field value: A Base64-encoded string of the file's raw bytes + +**Example: Uploading multiple files within a single bucket** + +If your Upload Session response listed a single "bucket" containing two file hashes: + +```json +"buckets": [ + [ + "08f1dfda4574284ab3c21666d1ee8c7d4", + "36b8be012ee77df5f269b11b975611d3" + ] +] +``` + +You can upload both files in one request, each as a form-data field: + +```bash +curl -X POST \ + "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/assets/upload?base64=true" \ + -H "Authorization: Bearer " \ + -F "08f1dfda4574284ab3c21666d1ee8c7d4=" \ + -F "36b8be012ee77df5f269b11b975611d3=" +``` + +* `` is the token from step 1's assets-upload-session response +* `` is the Base64-encoded content of index.html +* `` is the Base64-encoded content of styles.css + +If you have multiple buckets (for example, `[["hashA"], ["hashB"], ["hashC"]]`), you might need to repeat this process for each bucket, making one request per bucket group. + +Once every file in the manifest has been uploaded, a status code of 201 will be returned, with the `jwt` field present. This JWT is a final "completion" token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour. + +```json +{ + "success": true, + "errors": [], + "messages": [], + "result": { + "jwt": "" + } +} +``` + +`` indicates that Cloudflare has successfully received and stored the file contents specified by your manifest. You will use this `` in Step 3 to finalize the attachment of these files to the Worker. + +### 3. Deploy the User Worker with Static Assets + +Now that Cloudflare has all the files it needs (from the previous upload steps), you must attach them to the User Worker by making a PUT request to the [Upload User Worker API](https://developers.cloudflare.com/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/). This final step links the static assets to the User Worker using the completion token you received after uploading file contents. + +You can also specify any optional settings under the assets.config field to customize how your files are served (for example, to handle trailing slashes in HTML paths). + +**API request example:** + +```bash +curl -X PUT \ + "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME" \ + -H "Content-Type: multipart/form-data" \ + -H "Authorization: Bearer $API_TOKEN" \ + -F 'metadata={ + "main_module": "index.js", + "assets": { + "jwt": "", + "config": { + "html_handling": "auto-trailing-slash" + } + }, + "compatibility_date": "2025-01-24" + };type=application/json' \ + -F 'index.js=@/path/to/index.js;type=application/javascript' +``` + +* The `"jwt": ""` links the newly uploaded files to the Worker +* Including "html_handling" (or other fields under "config") is optional and can customize how static files are served +* If the user's Worker code hasn't changed, you can omit the code file or re-upload the same index.js + +Once this PUT request succeeds, the files are served on the User Worker. Requests routed to that Worker will serve the new or updated static assets. + +# Deploying static assets with Wrangler + +If you prefer a CLI-based approach and your platform setup allows direct publishing, you can use Wrangler to deploy both your Worker code and static assets. Wrangler bundles and uploads static assets (from a specified directory) along with your Worker script, so you can manage everything in one place. + +Create or update your `wrangler.toml` to specify where Wrangler should look for static files: + +```toml +name = "my-static-site" +main = "./src/index.js" +compatibility_date = "2025-01-29" + +[assets] +directory = "./public" +binding = "ASSETS" +``` + +* `directory`: The local folder containing your static files (for example, `./public`). +* `binding`: The binding name used to reference these assets within your Worker code. + +**Organizing your files** + +Place your static files (HTML, CSS, images, etc.) in the specified directory (in this example, `./public`). Wrangler will detect and bundle these files when you publish your Worker. + +If you need to reference these files in your Worker script to serve them dynamically, you can use the `ASSETS` binding like this: + +```js +export default { + async fetch(request, env, ctx) { + return env.ASSETS.fetch(request); + }, +}; +``` +**Deploying the User Worker with the Static Assets** + +Run Wrangler to publish both your Worker code and the static assets: + +```bash +npx wrangler deploy --name --dispatch-namespace +``` + +Wrangler will automatically detect your static files, bundle them, and upload them to Cloudflare along with your Worker code. \ No newline at end of file From b71ac9e94a6f0ba796ca153a69478c3d99dcc642 Mon Sep 17 00:00:00 2001 From: dinasaur404 <49571477+dinasaur404@users.noreply.github.com> Date: Wed, 29 Jan 2025 12:14:08 -0500 Subject: [PATCH 2/8] Update src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- .../workers-for-platforms/configuration/static-assets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index bbb327d78438e5f..e483ad79613b01f 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -2,7 +2,7 @@ pcx_content_type: concept title: Static Assets --- -Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare’s global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers. +Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare's global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers. ## What you can build #### Static sites From 70433a0cca605510422f7ea3bc343d0617720c80 Mon Sep 17 00:00:00 2001 From: dinasaur404 <49571477+dinasaur404@users.noreply.github.com> Date: Wed, 29 Jan 2025 12:14:17 -0500 Subject: [PATCH 3/8] Update src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- .../workers-for-platforms/configuration/static-assets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index e483ad79613b01f..d7d54b721c2608a 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -59,7 +59,7 @@ Before sending any file data, you need to tell Cloudflare which files you intend } ``` -To start the upload process, send a POST request to the Create Assets Upload Session [API endpoint](https://developers.cloudflare.com/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/asset_upload/methods/create/) +To start the upload process, send a POST request to the Create Assets Upload Session [API endpoint](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/asset_upload/methods/create/) ```bash POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session From e1d138172613651526ee627f080be495a38a3ed1 Mon Sep 17 00:00:00 2001 From: dinasaur404 <49571477+dinasaur404@users.noreply.github.com> Date: Wed, 29 Jan 2025 12:14:32 -0500 Subject: [PATCH 4/8] Update src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- .../workers-for-platforms/configuration/static-assets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index d7d54b721c2608a..6f7ec1431df1258 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -100,7 +100,7 @@ You can compute a SHA-256 digest of the file contents, then truncate or otherwis If all the files are already stored on Cloudflare, the response will only return the JWT token. If new or updated files are needed, the response will return: * `jwt`: An upload token (valid for 1 hour) which will be used in the API request to upload the file contents (Step 2) -* `buckets`: An array of file-hash groups indicating which files to upload together. Files that have been recently uploaded won’t appear in buckets, since Cloudflare already has them. +* `buckets`: An array of file-hash groups indicating which files to upload together. Files that have been recently uploaded won't appear in buckets, since Cloudflare already has them. **Note**: This step alone does not store files on Cloudflare. You must upload the actual file data in the next step. From ca49da3f8db0747e22b00a833aa5f4a02919be2f Mon Sep 17 00:00:00 2001 From: dinasaur404 <49571477+dinasaur404@users.noreply.github.com> Date: Wed, 29 Jan 2025 12:14:41 -0500 Subject: [PATCH 5/8] Update src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- .../workers-for-platforms/configuration/static-assets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index 6f7ec1431df1258..0f9e9ecc5853b4e 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -6,7 +6,7 @@ Workers for Platforms lets you deploy front-end applications at scale. By hostin ## What you can build #### Static sites -Host and serve HTML, CSS, JavaScript, and media files drectly from Cloudflare’s network, ensuring fast loading times worldwide. This is ideal for blogs, landing pages, and documentation sites. +Host and serve HTML, CSS, JavaScript, and media files directly from Cloudflare's network, ensuring fast loading times worldwide. This is ideal for blogs, landing pages, and documentation sites. #### Full-stack applications Combine asset hosting with Cloudflare Workers to power dynamic, interactive applications. Store and retrieve data using Cloudflare KV, D1, and R2 Storage, allowing you to serve both front-end assets and backend logic from a single Worker. From 5de5d0525935300557e66c3bbff6ce42a76c3bdb Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 30 Jan 2025 18:31:52 +0000 Subject: [PATCH 6/8] Fix heading levels and other formatting --- .../configuration/static-assets.mdx | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index 0f9e9ecc5853b4e..9f665a64affd2f1 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -3,24 +3,28 @@ pcx_content_type: concept title: Static Assets --- Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare's global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers. -## What you can build -#### Static sites +### What you can build + +#### Static sites Host and serve HTML, CSS, JavaScript, and media files directly from Cloudflare's network, ensuring fast loading times worldwide. This is ideal for blogs, landing pages, and documentation sites. -#### Full-stack applications +#### Full-stack applications Combine asset hosting with Cloudflare Workers to power dynamic, interactive applications. Store and retrieve data using Cloudflare KV, D1, and R2 Storage, allowing you to serve both front-end assets and backend logic from a single Worker. - -## Benefits -#### Global caching for faster performance + +### Benefits + +#### Global caching for faster performance Cloudflare automatically caches static assets at data centers worldwide, reducing latency and improving load times by up to 2x for users everywhere. -#### Scalability without infrastructure management +#### Scalability without infrastructure management Your applications scale automatically to handle high traffic without requiring you to provision or manage infrastructure. Cloudflare dynamically adjusts to demand in real time. -#### Unified deployment for static and dynamic content +#### Unified deployment for static and dynamic content Deploy front-end assets alongside server-side logic, all within Cloudflare Workers. This eliminates the need for a separate hosting provider and ensures a streamlined deployment process. +--- + ## Deploying static assets to User Workers It's common that as the Platform, you will be responsible for uploading static assets on behalf of your end users. This often looks like this: @@ -31,7 +35,7 @@ It's common that as the Platform, you will be responsible for uploading static a Once you receive the static files from your users (for a new or updated site), complete the following steps to attach the files to the corresponding User Worker: 1. Create an Upload Session -2. Upload file contents +2. Upload file contents 3. Deploy/Update the Worker After these steps are completed, the User Worker's static assets will be live on Cloudflare's edge. @@ -69,7 +73,7 @@ Path Parameters: * `namespace`: Name of the Workers for Platforms dispatch namespace * `script_name`: Name of the User Worker -In the request body, include a JSON object listing each file path along with its hash and size. This helps Cloudflare identify which files you intend to upload and allows Cloudflare to check if any of them are already stored. +In the request body, include a JSON object listing each file path along with its hash and size. This helps Cloudflare identify which files you intend to upload and allows Cloudflare to check if any of them are already stored. **Sample request:** @@ -106,7 +110,7 @@ If all the files are already stored on Cloudflare, the response will only return ### 2. Upload File Contents -If the response to the Upload Session API returns `buckets`, that means you have new or changed files that need to be uploaded to Cloudflare. +If the response to the Upload Session API returns `buckets`, that means you have new or changed files that need to be uploaded to Cloudflare. Use the [Workers Assets Upload API](https://developers.cloudflare.com/api/resources/workers/subresources/assets/subresources/upload/) to transmit the raw file bytes in base64-encoded format for any missing or changed files. Once uploaded, Cloudflare will store these files so they can then be attached to a User Worker. @@ -155,7 +159,7 @@ curl -X POST \ * `` is the Base64-encoded content of index.html * `` is the Base64-encoded content of styles.css -If you have multiple buckets (for example, `[["hashA"], ["hashB"], ["hashC"]]`), you might need to repeat this process for each bucket, making one request per bucket group. +If you have multiple buckets (for example, `[["hashA"], ["hashB"], ["hashC"]]`), you might need to repeat this process for each bucket, making one request per bucket group. Once every file in the manifest has been uploaded, a status code of 201 will be returned, with the `jwt` field present. This JWT is a final "completion" token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour. @@ -174,7 +178,7 @@ Once every file in the manifest has been uploaded, a status code of 201 will be ### 3. Deploy the User Worker with Static Assets -Now that Cloudflare has all the files it needs (from the previous upload steps), you must attach them to the User Worker by making a PUT request to the [Upload User Worker API](https://developers.cloudflare.com/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/). This final step links the static assets to the User Worker using the completion token you received after uploading file contents. +Now that Cloudflare has all the files it needs (from the previous upload steps), you must attach them to the User Worker by making a PUT request to the [Upload User Worker API](https://developers.cloudflare.com/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/). This final step links the static assets to the User Worker using the completion token you received after uploading file contents. You can also specify any optional settings under the assets.config field to customize how your files are served (for example, to handle trailing slashes in HTML paths). @@ -204,7 +208,9 @@ curl -X PUT \ Once this PUT request succeeds, the files are served on the User Worker. Requests routed to that Worker will serve the new or updated static assets. -# Deploying static assets with Wrangler +--- + +## Deploying static assets with Wrangler If you prefer a CLI-based approach and your platform setup allows direct publishing, you can use Wrangler to deploy both your Worker code and static assets. Wrangler bundles and uploads static assets (from a specified directory) along with your Worker script, so you can manage everything in one place. @@ -223,11 +229,11 @@ binding = "ASSETS" * `directory`: The local folder containing your static files (for example, `./public`). * `binding`: The binding name used to reference these assets within your Worker code. -**Organizing your files** +### 1. Organize your files Place your static files (HTML, CSS, images, etc.) in the specified directory (in this example, `./public`). Wrangler will detect and bundle these files when you publish your Worker. -If you need to reference these files in your Worker script to serve them dynamically, you can use the `ASSETS` binding like this: +If you need to reference these files in your Worker script to serve them dynamically, you can use the `ASSETS` binding like this: ```js export default { @@ -236,7 +242,7 @@ export default { }, }; ``` -**Deploying the User Worker with the Static Assets** +### 2. Deploy the User Worker with the Static Assets Run Wrangler to publish both your Worker code and the static assets: From 3c548bfce36bff1aeeb26f7e08aa279ec3697ed4 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 30 Jan 2025 18:58:20 +0000 Subject: [PATCH 7/8] Style guide changes and replace CF's edge for global network --- .../configuration/static-assets.mdx | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index 9f665a64affd2f1..92a9d7789a6971e 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -title: Static Assets +title: Static assets --- Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare's global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers. @@ -25,11 +25,11 @@ Deploy front-end assets alongside server-side logic, all within Cloudflare Worke --- -## Deploying static assets to User Workers +## Deploy static assets to User Workers -It's common that as the Platform, you will be responsible for uploading static assets on behalf of your end users. This often looks like this: +It is common that, as the Platform, you will be responsible for uploading static assets on behalf of your end users. This often looks like this: -1. User uploads files (HTML, CSS, images) through your interface. +1. Your user uploads files (HTML, CSS, images) through your interface. 2. Your platform interacts with the Workers for Platforms APIs to attach the static assets to the User Worker script. Once you receive the static files from your users (for a new or updated site), complete the following steps to attach the files to the corresponding User Worker: @@ -38,7 +38,7 @@ Once you receive the static files from your users (for a new or updated site), c 2. Upload file contents 3. Deploy/Update the Worker -After these steps are completed, the User Worker's static assets will be live on Cloudflare's edge. +After these steps are completed, the User Worker's static assets will be live on the Cloudflare's global network. ### 1. Create an Upload Session @@ -63,7 +63,7 @@ Before sending any file data, you need to tell Cloudflare which files you intend } ``` -To start the upload process, send a POST request to the Create Assets Upload Session [API endpoint](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/asset_upload/methods/create/) +To start the upload process, send a POST request to the Create Assets Upload Session [API endpoint](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/asset_upload/methods/create/). ```bash POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session @@ -103,10 +103,13 @@ You can compute a SHA-256 digest of the file contents, then truncate or otherwis **API Response** If all the files are already stored on Cloudflare, the response will only return the JWT token. If new or updated files are needed, the response will return: -* `jwt`: An upload token (valid for 1 hour) which will be used in the API request to upload the file contents (Step 2) + +* `jwt`: An upload token (valid for 1 hour) which will be used in the API request to upload the file contents (Step 2). * `buckets`: An array of file-hash groups indicating which files to upload together. Files that have been recently uploaded won't appear in buckets, since Cloudflare already has them. -**Note**: This step alone does not store files on Cloudflare. You must upload the actual file data in the next step. +:::note +This step alone does not store files on Cloudflare. You must upload the actual file data in the next step. +::: ### 2. Upload File Contents @@ -129,7 +132,7 @@ This token is valid for one hour and must be supplied for each upload request to **File fields (multipart/form-data)** You must send the files as multipart/form-data with base64-encoded content: -* Field name: The file hash (for example, "36b8be012ee77df5f269b11b975611d3") +* Field name: The file hash (for example, `36b8be012ee77df5f269b11b975611d3`) * Field value: A Base64-encoded string of the file's raw bytes **Example: Uploading multiple files within a single bucket** @@ -161,7 +164,7 @@ curl -X POST \ If you have multiple buckets (for example, `[["hashA"], ["hashB"], ["hashC"]]`), you might need to repeat this process for each bucket, making one request per bucket group. -Once every file in the manifest has been uploaded, a status code of 201 will be returned, with the `jwt` field present. This JWT is a final "completion" token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour. +Once every file in the manifest has been uploaded, a status code of `201` will be returned, with the `jwt` field present. This JWT is a final "completion" token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour. ```json { @@ -176,11 +179,11 @@ Once every file in the manifest has been uploaded, a status code of 201 will be `` indicates that Cloudflare has successfully received and stored the file contents specified by your manifest. You will use this `` in Step 3 to finalize the attachment of these files to the Worker. -### 3. Deploy the User Worker with Static Assets +### 3. Deploy the User Worker with static assets Now that Cloudflare has all the files it needs (from the previous upload steps), you must attach them to the User Worker by making a PUT request to the [Upload User Worker API](https://developers.cloudflare.com/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/). This final step links the static assets to the User Worker using the completion token you received after uploading file contents. -You can also specify any optional settings under the assets.config field to customize how your files are served (for example, to handle trailing slashes in HTML paths). +You can also specify any optional settings under the `assets.config` field to customize how your files are served (for example, to handle trailing slashes in HTML paths). **API request example:** @@ -204,7 +207,7 @@ curl -X PUT \ * The `"jwt": ""` links the newly uploaded files to the Worker * Including "html_handling" (or other fields under "config") is optional and can customize how static files are served -* If the user's Worker code hasn't changed, you can omit the code file or re-upload the same index.js +* If the user's Worker code has not changed, you can omit the code file or re-upload the same index.js Once this PUT request succeeds, the files are served on the User Worker. Requests routed to that Worker will serve the new or updated static assets. @@ -242,7 +245,7 @@ export default { }, }; ``` -### 2. Deploy the User Worker with the Static Assets +### 2. Deploy the User Worker with the static assets Run Wrangler to publish both your Worker code and the static assets: From cea2ddfbb498cd400b639f71444fc84bcdf0f790 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 30 Jan 2025 19:06:48 +0000 Subject: [PATCH 8/8] Add meta description and replace bold by h4 --- .../configuration/static-assets.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx index 92a9d7789a6971e..624df2b42564770 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets.mdx @@ -1,6 +1,7 @@ --- pcx_content_type: concept title: Static assets +description: Host static assets on Cloudflare's global network and deliver faster load times worldwide with Workers for Platforms. --- Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare's global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers. @@ -48,7 +49,7 @@ Before sending any file data, you need to tell Cloudflare which files you intend * A hash (32-hex characters) representing the file contents * The file size in bytes -**Example manifest (JSON):** +#### Example manifest (JSON) ```json { @@ -75,7 +76,7 @@ Path Parameters: In the request body, include a JSON object listing each file path along with its hash and size. This helps Cloudflare identify which files you intend to upload and allows Cloudflare to check if any of them are already stored. -**Sample request:** +#### Sample request ```bash curl -X POST \ @@ -96,11 +97,11 @@ curl -X POST \ }' ``` -**Generating the hash** +#### Generating the hash You can compute a SHA-256 digest of the file contents, then truncate or otherwise represent it consistently as a 32-hex-character string. Make sure to do it the same way each time so Cloudflare can reliably match files across uploads. -**API Response** +#### API Response If all the files are already stored on Cloudflare, the response will only return the JWT token. If new or updated files are needed, the response will return: @@ -117,7 +118,7 @@ If the response to the Upload Session API returns `buckets`, that means you have Use the [Workers Assets Upload API](https://developers.cloudflare.com/api/resources/workers/subresources/assets/subresources/upload/) to transmit the raw file bytes in base64-encoded format for any missing or changed files. Once uploaded, Cloudflare will store these files so they can then be attached to a User Worker. -**API Request Authentication** +#### API Request Authentication Unlike most Cloudflare API calls that use an account-wide API token in the Authorization header, uploading file contents requires using the short-lived JWT token returned in the `jwt` field of the `assets-upload-session` response. @@ -129,13 +130,13 @@ Authorization: Bearer This token is valid for one hour and must be supplied for each upload request to the Workers Assets Upload API. -**File fields (multipart/form-data)** +#### File fields (multipart/form-data) You must send the files as multipart/form-data with base64-encoded content: * Field name: The file hash (for example, `36b8be012ee77df5f269b11b975611d3`) * Field value: A Base64-encoded string of the file's raw bytes -**Example: Uploading multiple files within a single bucket** +#### Example: Uploading multiple files within a single bucket If your Upload Session response listed a single "bucket" containing two file hashes: @@ -185,7 +186,7 @@ Now that Cloudflare has all the files it needs (from the previous upload steps), You can also specify any optional settings under the `assets.config` field to customize how your files are served (for example, to handle trailing slashes in HTML paths). -**API request example:** +#### API request example ```bash curl -X PUT \