Skip to content

add more detail around how to use bindings in React-Router Workers projects #22850

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 3 commits into from
Jun 4, 2025
Merged

add more detail around how to use bindings in React-Router Workers projects #22850

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
24455b6
add more detail around how to use bindings in React-Router Workers pr…
petebacondarwin Jun 3, 2025
edee994
Update src/content/docs/workers/frameworks/framework-guides/react-rou…
petebacondarwin Jun 3, 2025
b5c0667
fix up missing import and formatting
petebacondarwin Jun 3, 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
166 changes: 117 additions & 49 deletions src/content/docs/workers/frameworks/framework-guides/react-router.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,74 +33,142 @@ It combines with the [Cloudflare Vite plugin](/workers/vite-plugin/) to provide
## Creating a full-stack React Router app

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

<PackageManagers
1. **Create a new project with the create-cloudflare CLI (C3)**

<PackageManagers
type="create"
pkg="cloudflare@latest"
args="my-react-router-app --framework=react-router"
/>
<Details header="How is this project set up?">
Below is a simplified file tree of the project.
<FileTree>
- my-react-router-app
- app
- routes
- ...
- entry.server.ts
- root.tsx
- routes.ts
- workers
- app.ts
- react-router.config.ts
- vite.config.ts
- wrangler.jsonc
</FileTree>

`react-router.config.ts` is your [React Router config file](https://reactrouter.com/explanation/special-files#react-routerconfigts).
In this file:
- `ssr` is set to `true`, meaning that your application will use server-side rendering.
- `future.unstable_viteEnvironmentApi` is set to `true` to enable compatibility with the [Cloudflare Vite plugin](/workers/vite-plugin/).

:::note
SPA mode and prerendering are not currently supported when using the [Cloudflare Vite plugin](/workers/vite-plugin/).
If you wish to use React Router in an SPA then we recommend starting with the [React template](/workers/frameworks/framework-guides/react/) and using React Router [as a library](https://reactrouter.com/start/data/installation).
:::

`vite.config.ts` is your [Vite config file](https://vite.dev/config/).
The React Router and Cloudflare plugins are included in the `plugins` array.
The [Cloudflare Vite plugin](/workers/vite-plugin/) runs your server code in the Workers runtime, ensuring your local development environment is as close to production as possible.

`wrangler.jsonc` is your [Worker config file](/workers/wrangler/configuration/).
In this file:
- `main` points to `./workers/app.ts`.
This is the entry file for your Worker.
The default export includes a [`fetch` handler](/workers/runtime-apis/fetch/), which delegates the request to React Router.
- If you want to add [bindings](/workers/runtime-apis/bindings/) to resources on Cloudflare's developer platform, you configure them here.
</Details>
/>

<Details header="How is this project set up?">

Below is a simplified file tree of the project.

<FileTree>
- my-react-router-app
- app
- routes
- ...
- entry.server.ts
- root.tsx
- routes.ts
- workers
- app.ts
- react-router.config.ts
- vite.config.ts
- wrangler.jsonc
</FileTree>

`react-router.config.ts` is your [React Router config file](https://reactrouter.com/explanation/special-files#react-routerconfigts).
In this file:
- `ssr` is set to `true`, meaning that your application will use server-side rendering.
- `future.unstable_viteEnvironmentApi` is set to `true` to enable compatibility with the [Cloudflare Vite plugin](/workers/vite-plugin/).

:::note
SPA mode and prerendering are not currently supported when using the [Cloudflare Vite plugin](/workers/vite-plugin/).
If you wish to use React Router in an SPA then we recommend starting with the [React template](/workers/frameworks/framework-guides/react/) and using React Router [as a library](https://reactrouter.com/start/data/installation).
:::

`vite.config.ts` is your [Vite config file](https://vite.dev/config/).
The React Router and Cloudflare plugins are included in the `plugins` array.
The [Cloudflare Vite plugin](/workers/vite-plugin/) runs your server code in the Workers runtime, ensuring your local development environment is as close to production as possible.

`wrangler.jsonc` is your [Worker config file](/workers/wrangler/configuration/).
In this file:
- `main` points to `./workers/app.ts`.
This is the entry file for your Worker.
The default export includes a [`fetch` handler](/workers/runtime-apis/fetch/), which delegates the request to React Router.
- If you want to add [bindings](/workers/runtime-apis/bindings/) to resources on Cloudflare's developer platform, you configure them here.

</Details>

2. **Develop locally**

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 React Router in combination with the [Cloudflare Vite plugin](/workers/vite-plugin/).
This means that your application runs in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings.
</Details>

<Details header="What's happening in local development?">
This project uses React Router in combination with the [Cloudflare Vite plugin](/workers/vite-plugin/).
This means that your application runs 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/).
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.
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"} />
<PackageManagers type="run" args={"deploy"} />

</Steps>

## Use bindings with React Router

With bindings, your application can be fully integrated with the Cloudflare Developer Platform, giving you access to compute, storage, AI and more.
As you have direct access to your Worker entry file (`workers/app.ts`), you can also add additional exports such as [Durable Objects](/durable-objects/) and [Workflows](/workflows/).

Once you have configured the bindings in the Wrangler configuration file, they are then available within `context.cloudflare` in your loader or action functions:

```ts title="app/routes/home.tsx"
export function loader({ context }: Route.LoaderArgs) {
return { message: context.cloudflare.env.VALUE_FROM_CLOUDFLARE };
}

export default function Home({ loaderData }: Route.ComponentProps) {
return <Welcome message={loaderData.message} />;
}
```

As you have direct access to your Worker entry file (`workers/app.ts`), you can also add additional exports such as [Durable Objects](/durable-objects/) and [Workflows](/workflows/)

<Details header="Example: Using Workflows">

Here is an example of how to set up a simple Workflow in your Worker entry file.

```ts title="workers/app.ts"
import { createRequestHandler } from "react-router";
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

declare global {
interface CloudflareEnvironment extends Env {}
}

type Env = {
MY_WORKFLOW: Workflow;
};

export class MyWorkflow extends WorkflowEntrypoint<Env> {
override async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
await step.do("first step", async () => {
return { output: "First step result" };
});

await step.sleep("sleep", "1 second");

await step.do("second step", async () => {
return { output: "Second step result" };
});

return "Workflow output";
}
}

const requestHandler = createRequestHandler(
() => import("virtual:react-router/server-build"),
import.meta.env.MODE
);

export default {
async fetch(request, env, ctx) {
return requestHandler(request, {
cloudflare: { env, ctx },
});
},
} satisfies ExportedHandler<CloudflareEnvironment>;
```

</Details>

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