---
title: 'Deploy React Router on AWS'
description: 'Deploy React Router applications on AWS using CSR/static pre-rendering with S3 and CloudFront, or full-stack SSR with ECS Fargate and Application Load Balancer.'
---

import { Tabs, TabItem, LinkButton, Aside } from '@astrojs/starlight/components';

Deploy your [React Router](https://reactrouter.com/) applications to AWS using Thunder patterns. This guide covers client-side rendering (CSR), static pre-rendering, and full-stack server-side rendering options.

There are two deployment patterns available for React Router on AWS:

1. **Single Page Application (SPA)** — Deploy client-side or static pre-rendered React Router sites using S3 and CloudFront with the [Single Page Application](/docs/patterns/s3-cloudfront) pattern
2. **Full Stack** — Deploy SSR React Router applications using ECS Fargate with the [Web Service](/docs/patterns/fargate-alb) pattern

<Aside type="note" title="Requirements">
- [AWS CDK](https://aws.amazon.com/cdk/) installed globally: `npm install -g aws-cdk`
- Node.js version 20 or higher
- [AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) configured
- AWS environment bootstrapped: `cdk bootstrap aws://your-account-id/us-east-1`
</Aside>

## Single Page Application (SPA) Deployment
---

Deploy React Router applications to S3 and CloudFront using the [CDK-SPA](https://github.com/thunder-so/cdk-spa) library. This pattern supports both client-side rendering (CSR) and static pre-rendering, offering flexibility for different use cases.

### Create Project

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
```sh
npm create vite@latest my-react-router-app -- --template react-ts
cd my-react-router-app
npm install react-router-dom@7
```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
```sh
pnpm create vite my-react-router-app --template react-ts
cd my-react-router-app
pnpm add react-router-dom@7
```
  </TabItem>
  <TabItem label="bun" icon="bun">
```sh
bun create vite my-react-router-app --template react-ts
cd my-react-router-app
bun add react-router-dom@7
```
  </TabItem>
</Tabs>

### Configure React Router

Choose one of the following configurations based on your needs:

**Client-Side Rendering (CSR)** — Routes are always client-side rendered as users navigate:

```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";

export default {
  ssr: false,
} satisfies Config;
```

**Static Pre-rendering** — Generate static HTML at build time for specific routes:

```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";

export default {
  // Return a list of URLs to prerender at build time
  async prerender() {
    return ["/", "/about", "/contact"];
  },
} satisfies Config;
```

Pre-rendering generates static HTML and client navigation data payloads for a list of URLs, offering better performance and SEO without requiring a server. Route module loaders are used to fetch data at build time. Individual routes can also use client data loading with `clientLoader` to supplement pre-rendered data.

### Install Dependencies and Setup Stack

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
```sh
npm i tsx @thunderso/cdk-spa --save-dev
```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
```sh
pnpm add -D tsx @thunderso/cdk-spa
```
  </TabItem>
  <TabItem label="bun" icon="bun">
```sh
bun add -d tsx @thunderso/cdk-spa
```
  </TabItem>
</Tabs>

```ts title="stack/index.ts"
import { Cdk, SPAStack, type SPAProps } from "@thunderso/cdk-spa";

const myApp: SPAProps = {
  env: {
    account: 'your-account-id',
    region: 'us-east-1'
  },
  application: 'your-application-id',
  service: 'your-service-id',
  environment: 'production',

  rootDir: '', // e.g. 'frontend/' for monorepos
  outputDir: 'dist/',
};

new SPAStack(
  new Cdk.App(), 
  `${myApp.application}-${myApp.service}-${myApp.environment}-stack`, 
  myApp
);
```

### Environment Variables and Secrets for Build

Configure build-time environment variables using the `buildProps` configuration:

```ts title="stack/index.ts"
const myApp: SPAProps = {
  // ... other props
  
  buildProps: {
    environment: [
      { VITE_API_URL: 'https://api.example.com' },
      { VITE_ANALYTICS_ID: 'UA-XXXXXX' }
    ],
    secrets: [
      { key: 'API_KEY', resource: '/my-app/API_KEY' },
    ],
  },
};
```

### Deploy

Build and deploy your React Router SPA:

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
```sh
npm run build
npx cdk deploy --all --app="npx tsx stack/index.ts"
```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
```sh
pnpm run build
pnpm exec cdk deploy --all --app="pnpm exec tsx stack/index.ts"
```
  </TabItem>
  <TabItem label="bun" icon="bun">
```sh
bun run build
npx cdk deploy --all --app="bunx tsx stack/index.ts"
```
  </TabItem>
</Tabs>

After deployment, you'll receive a **CloudFront URL** to access your application.

For complete documentation, see the [CDK-SPA README](https://github.com/thunder-so/cdk-spa).

## Full Stack Deployment (SSR)
---

Deploy server-side rendered React Router applications using ECS Fargate and Application Load Balancer with the [CDK-WebService](https://github.com/thunder-so/cdk-webservice) library.

### Create Project

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
```sh
npm create vite@latest my-react-router-app -- --template react-ts
cd my-react-router-app
npm install react-router-dom@7
```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
```sh
pnpm create vite my-react-router-app --template react-ts
cd my-react-router-app
pnpm add react-router-dom@7
```
  </TabItem>
  <TabItem label="bun" icon="bun">
```sh
bun create vite my-react-router-app --template react-ts
cd my-react-router-app
bun add react-router-dom@7
```
  </TabItem>
</Tabs>

### Configure React Router for SSR

```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";

export default {
  ssr: true,
} satisfies Config;
```

Server-side rendering requires a deployment that supports it. Individual routes can still be statically pre-rendered, and routes can also use client data loading with `clientLoader` to avoid server rendering/fetching for their portion of the UI.

### Install Dependencies and Setup Stack

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
```sh
npm i tsx @thunderso/cdk-webservice --save-dev
```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
```sh
pnpm add -D tsx @thunderso/cdk-webservice
```
  </TabItem>
  <TabItem label="bun" icon="bun">
```sh
bun add -d tsx @thunderso/cdk-webservice
```
  </TabItem>
</Tabs>

```ts title="stack/index.ts"
import { Cdk, WebServiceStack, type WebServiceProps } from "@thunderso/cdk-webservice";

const svcProps: WebServiceProps = {
  env: {
    account: 'your-account-id',
    region: 'us-west-2'
  },
  application: 'your-application-id',
  service: 'your-service-id',
  environment: 'production',

  rootDir: '', // e.g. 'app/' for monorepos
};

new WebServiceStack(
  new Cdk.App(), 
  `${svcProps.application}-${svcProps.service}-${svcProps.environment}-stack`, 
  svcProps
);
```

### Build Settings Using Nixpacks

Configure automatic containerization with Nixpacks:

```ts title="stack/index.ts"
const svcProps: WebServiceProps = {
  // ... other props
  
  buildProps: {
    buildSystem: 'Nixpacks',
    installcmd: 'bun install',
    buildcmd: 'bun run build',
    startcmd: 'bun start',
  },
};
```

### Build Settings Using Docker Container

Alternatively, use a custom Dockerfile:

```dockerfile title="Dockerfile"
FROM public.ecr.aws/docker/library/alpine

# Install Bun
RUN curl -fsSL https://bun.sh/install | bash

# Update PATH for bun
ENV PATH="/root/.bun/bin:$PATH"

# Copy code, install and build
WORKDIR /app
COPY . .
RUN bun install
RUN bun run build

EXPOSE 3000
CMD ["bun", "start"]
```

```ts title="stack/index.ts"
const svcProps: WebServiceProps = {
  // ... other props
  
  serviceProps: {
    dockerFile: 'Dockerfile',
    port: 3000,
  },
};
```

### Environment Variables and Secrets for SSR

Configure runtime environment variables and secrets:

```ts title="stack/index.ts"
const svcProps: WebServiceProps = {
  // ... other props
  
  serviceProps: {
    variables: [
      { NODE_ENV: 'production' },
      { VITE_API_URL: 'https://api.example.com' }
    ],
    secrets: [
      { 
        key: 'DATABASE_URL', 
        resource: 'arn:aws:secretsmanager:us-west-2:123456789012:secret:/my-app/DATABASE_URL-abc123' 
      },
    ],
  },
};
```

### Deploy

Build and deploy your containerized application:

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
```sh
npm run build
npx cdk deploy --all --app="npx tsx stack/index.ts"
```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
```sh
pnpm run build
pnpm exec cdk deploy --all --app="pnpm exec tsx stack/index.ts"
```
  </TabItem>
  <TabItem label="bun" icon="bun">
```sh
bun run build
npx cdk deploy --all --app="bunx tsx stack/index.ts"
```
  </TabItem>
</Tabs>

After deployment, you'll receive an **Application Load Balancer URL** to access your SSR application.

For complete documentation, see the [CDK-WebService README](https://github.com/thunder-so/cdk-webservice).