Skip to content

update various framework guides (hono, react etc.) #21367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Apr 7, 2025
Merged

update various framework guides (hono, react etc.) #21367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2425a9b
update hono docs
emily-shen Apr 3, 2025
393a2da
f
emily-shen Apr 3, 2025
1c0682e
add bindings partial
emily-shen Apr 3, 2025
d49e7ca
update vue a bit
emily-shen Apr 3, 2025
9801d18
add bindings partial to hono
emily-shen Apr 3, 2025
b6997e2
and the rest of them
emily-shen Apr 3, 2025
cce882a
Apply suggestions from code review
emily-shen Apr 7, 2025
9bdb327
add links to vite plugin
emily-shen Apr 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 0 additions & 11 deletions src/content/docs/workers/frameworks/framework-guides/angular.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,6 @@ To use `create-cloudflare` to create a new Angular project with <InlineBadge pre
args={"--framework=angular --platform=workers"}
/>

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Angular",
}}
/>

After setting up your project, change your directory by running the following command:

```sh
Expand All @@ -60,6 +51,4 @@ The following command will build and deploy your project. If you're using CI, en

## Static assets

You can serve static assets your Angular application by placing them in [the `./public/` directory](https://angular.dev/reference/configs/file-structure#workspace-configuration-files). This can be useful for resource files such as images, stylesheets, fonts, and manifests.

<Render file="workers-assets-routing-summary" />
15 changes: 0 additions & 15 deletions src/content/docs/workers/frameworks/framework-guides/docusaurus.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,6 @@ To use `create-cloudflare` to create a new Docusaurus project with <InlineBadge
args={"--framework=docusaurus --platform=workers"}
/>

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Docusaurus",
}}
/>

After setting up your project, change your directory by running the following command:

```sh
Expand All @@ -55,9 +46,3 @@ Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain]
The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Static assets

You can serve static assets your Docusaurus application by placing them in [the `./static/` directory](https://docusaurus.io/docs/static-assets). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
15 changes: 0 additions & 15 deletions src/content/docs/workers/frameworks/framework-guides/gatsby.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,6 @@ To use `create-cloudflare` to create a new Gatsby project with <InlineBadge pres
args={"--framework=gatsby --platform=workers"}
/>

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Gatsby",
}}
/>

After setting up your project, change your directory by running the following command:

```sh
Expand All @@ -55,9 +46,3 @@ Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain]
The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Static assets

You can serve static assets your Gatsby application by placing them in [the `./static/` directory](https://www.gatsbyjs.com/docs/how-to/images-and-media/static-folder/). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
95 changes: 62 additions & 33 deletions src/content/docs/workers/frameworks/framework-guides/hono.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,59 +11,88 @@ import {
InlineBadge,
Render,
PackageManagers,
Steps,
Details,
FileTree,
} from "~/components";

In this guide, you will create a new [Hono](https://hono.dev/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, use code from the official Hono template, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Hono project with <InlineBadge preset="beta" /> Workers Assets, run the following command:
**Start from CLI** - scaffold a full-stack app with a Hono API, React SPA and the [Cloudflare Vite plugin](/workers/vite-plugin/) for lightning-fast development.

<PackageManagers
type="create"
pkg="cloudflare@latest my-hono-app"
args={"--framework=hono --platform=workers"}
args="--template=cloudflare/templates/vite-react-template"
/>
---

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Hono",
}}
/>
**Or just deploy** - create a full-stack app using Hono, React and Vite, with CI/CD and previews all set up for you.

After setting up your project, change your directory by running the following command:
[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/staging/vite-react-template)

```sh
cd my-hono-app
```
## What is Hono?

## 2. Develop locally
[Hono](https://hono.dev/) is an ultra-fast, lightweight framework for building web applications, and works fantastically with Cloudflare Workers.
With Workers Assets, you can easily combine a Hono API running on Workers with a SPA to create a full-stack app.

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.
## Creating a full-stack Hono app with a React SPA

<PackageManagers type="run" args={"dev"} />
<Steps>
1. **Create a new project with the create-cloudflare CLI (C3)**

## 3. Deploy your project
<PackageManagers
type="create"
pkg="cloudflare@latest my-hono-app"
args="--template=cloudflare/templates/vite-react-template"
/>
<Details header="How is this project set up?">
Below is a simplified file tree of the project.
<FileTree>
- my-hono-app
- src
- worker/
- index.ts
- react-app/
- index.html
- vite.config.ts
- wrangler.jsonc
</FileTree>

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).
`wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/).
Copy link
Contributor

@jamesopstad jamesopstad Apr 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/).
`wrangler.jsonc` is your [Worker configuration file](/workers/wrangler/configuration/).

Copy link
Contributor Author

@emily-shen emily-shen Apr 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we use "wrangler configuration file" everywhere else across the docs, unless you feel strongly about it, i'd prefer to keep it consistent. Especially since that file configures more than just your worker (e.g. resources), for better or worse 🥲

Copy link
Contributor

@jamesopstad jamesopstad Apr 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough. I used 'Worker config file' in the Vite plugin docs but we can revisit this at a later date.

In this file:
- `main` points to `src/worker/index.ts`. This is your Hono app, which will run in a Worker.
- `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your SPA do not go to the Worker, and are thus free.
- If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/).

The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.
`vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible.

<PackageManagers type="run" args={"deploy"} />
`src/worker/index.ts` is your Hono app, which contains a single endpoint to begin with, `/api`.
At `src/react-app/src/App.tsx`, your React app calls this endpoint to get a message back and displays this in your SPA.
</Details>

---
2. **Develop locally with the [Cloudflare Vite plugin](/workers/vite-plugin/)**

## Bindings
After creating your project, run the following command in your project directory to start a local development server.
<PackageManagers type="run" args="dev" />
<Details header="What's happening in local development?">
This project uses Vite for local development and build, and thus comes with all of Vite's features, including hot module replacement (HMR).

In addition, `vite.config.ts` is set up to use the Cloudflare Vite plugin. This runs your application in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings.
</Details>

Your Hono application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Hono documentation](https://hono.dev/docs/getting-started/cloudflare-workers#bindings) provides information about configuring bindings and how you can access them.
3. **Deploy your project**

## Static assets
Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

</Steps>

---

## Bindings

You can serve static assets in your Hono application by [placing them in the `./public/` directory](https://hono.dev/docs/getting-started/cloudflare-workers#serve-static-files). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
The [Hono documentation](https://hono.dev/docs/getting-started/cloudflare-workers#bindings) provides information on how you can access bindings in your Hono app.

<Render file="workers-assets-routing-summary" />
<Render file="frameworks-bindings" />
15 changes: 1 addition & 14 deletions src/content/docs/workers/frameworks/framework-guides/nuxt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,6 @@ To use `create-cloudflare` to create a new Nuxt project with <InlineBadge preset
args={"--framework=nuxt --platform=workers"}
/>

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Nuxt",
}}
/>

After setting up your project, change your directory by running the following command:

```sh
Expand All @@ -62,8 +53,4 @@ The following command will build and deploy your project. If you're using CI, en

Your Nuxt application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Nuxt documentation](https://nitro.unjs.io/deploy/providers/cloudflare#direct-access-to-cloudflare-bindings) provides information about configuring bindings and how you can access them in your Nuxt event handlers.

## Static assets

You can serve static assets your Nuxt application by placing them in [the `./public/` directory](https://nuxt.com/docs/guide/directory-structure/public). This can be useful for resource files such as images, stylesheets, fonts, and manifests.

<Render file="workers-assets-routing-summary" />
<Render file="frameworks-bindings" />
15 changes: 1 addition & 14 deletions src/content/docs/workers/frameworks/framework-guides/qwik.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,6 @@ To use `create-cloudflare` to create a new Qwik project with <InlineBadge preset
args={"--framework=qwik --platform=workers"}
/>

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Qwik",
}}
/>

After setting up your project, change your directory by running the following command:

```sh
Expand All @@ -62,8 +53,4 @@ The following command will build and deploy your project. If you're using CI, en

Your Qwik application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Qwik documentation](https://qwik.dev/docs/deployments/cloudflare-pages/#context) provides information about configuring bindings and how you can access them in your Qwik endpoint methods.

## Static assets

You can serve static assets your Qwik application by placing them in [the `./public/` directory](https://qwik.dev/docs/advanced/static-assets/). This can be useful for resource files such as images, stylesheets, fonts, and manifests.

<Render file="workers-assets-routing-summary" />
<Render file="frameworks-bindings" />
94 changes: 64 additions & 30 deletions src/content/docs/workers/frameworks/framework-guides/react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,59 +11,93 @@ import {
InlineBadge,
Render,
PackageManagers,
Details,
FileTree,
Steps,
} from "~/components";

In this guide, you will create a new [React](https://react.dev/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, use code from the official React template, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new React project with <InlineBadge preset="beta" /> Workers Assets, run the following command:
**Start from CLI** - scaffold a full-stack app with a React SPA, Cloudflare Workers API, and the [Cloudflare Vite plugin](/workers/vite-plugin/) for lightning-fast development.

<PackageManagers
type="create"
pkg="cloudflare@latest my-react-app"
args={"--framework=react --platform=workers"}
args="--framework=react --platform=workers"
/>
---

<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "React",
}}
/>
**Or just deploy** - create a full-stack app using React, Hono API And Vite, with CI/CD and previews all set up for you.

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/staging/vite-react-template)

## What is React?

After setting up your project, change your directory by running the following command:
[React](https://react.dev/) is a framework for building user interfaces. It allows you to create reusable UI components and manage the state of your application efficiently. You can use React to build a single-page application (SPA), and combine it with a backend API running on Cloudflare Workers to create a full-stack application.

```sh
cd my-react-app
```
## Creating a full-stack app with React

## 2. Develop locally
<Steps>
1. **Create a new project with the create-cloudflare CLI (C3)**

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.
<PackageManagers
type="create"
pkg="cloudflare@latest my-react-app"
args="--framework=react --platform=workers"
/>
<Details header="How is this project set up?">
Below is a simplified file tree of the project.
<FileTree>
- my-react-app
- src/
- App.tsx
- worker/
- index.ts
- index.html
- vite.config.ts
- wrangler.jsonc
</FileTree>

<PackageManagers type="run" args={"dev"} />
`wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/).
In this file:
- `main` points to `worker/index.ts`. This is your Worker, which is going to act as your backend API.
- `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your React SPA do not go to the Worker, and are thus free.
- If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/).

## 3. Deploy your project
`vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible.

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).
`worker/index.ts` is your backend API, which contains a single endpoint, `/api/`, that returns a text response.
At `src/App.tsx`, your React app calls this endpoint to get a message back and displays this.
</Details>

The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.
2. **Develop locally with the [Cloudflare Vite plugin](/workers/vite-plugin/)**

<PackageManagers type="run" args={"deploy"} />
After creating your project, run the following command in your project directory to start a local development server.
<PackageManagers type="run" args="dev" />
<Details header="What's happening in local development?">
This project uses Vite for local development and build, and thus comes with all of Vite's features, including hot module replacement (HMR).

In addition, `vite.config.ts` is set up to use the Cloudflare Vite plugin. This runs your application in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings.
</Details>

3. **Deploy your project**

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

</Steps>

---

## Static assets
## Asset Routing

You can serve static assets in your React application by [placing them in the `./public/` directory](https://vite.dev/guide/assets#the-public-directory). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
If you're using React as a SPA, you will want to set `not_found_handling = "single_page_application"` in your Wrangler configuration file.

<Render file="workers-assets-routing-summary" />

## Use bindings with React

Your new project also contains a Worker at `./api/index.ts`, which you can use as a backend API for your React application. While your React application cannot directly access Workers bindings, it can interact with them through this Worker. You can make [`fetch()` requests](/workers/runtime-apis/fetch/) from your React application to the Worker, which can then handle the request and use bindings. Learn how to [configure Workers bindings](/workers/runtime-apis/bindings/).
Your new project also contains a Worker at `./worker/index.ts`, which you can use as a backend API for your React application. While your React application cannot directly access Workers bindings, it can interact with them through this Worker. You can make [`fetch()` requests](/workers/runtime-apis/fetch/) from your React application to the Worker, which can then handle the request and use bindings. Learn how to [configure Workers bindings](/workers/runtime-apis/bindings/).

<Render file="frameworks-bindings" />
Loading
Loading