AWS SPA React Example

Copyright © 2026 Rusty Nations. Released under MIT License.

A demonstration Single Page Application for the AWS SPA Hosting Kit. This React + Vite + TypeScript SPA demonstrates the complete CI/CD workflow from GitHub to AWS.

Purpose

This example SPA serves as:

1. Reference Implementation: Shows how to structure a SPA for AWS hosting
2. Testing Tool: Validates that the hosting kit and CodePipeline work correctly
3. Starting Point: Can be forked and customized for your own projects
4. Documentation: Illustrates recommended directory structure and best practices

Technology Stack

• Framework: React 19
• Build Tool: Vite 7
• Language: TypeScript
• Package Manager: npm

Directory Structure

sample-spa/
├── src/                    # Source code
│   ├── App.tsx            # Main application component
│   ├── main.tsx           # Application entry point
│   ├── index.css          # Global styles
│   └── assets/            # Images, fonts, etc.
├── public/                # Static assets (copied as-is)
├── dist/                  # Build output (generated by 'npm run build')
├── buildspec.yml          # AWS CodeBuild build specification
├── package.json           # Dependencies and scripts
├── vite.config.ts         # Vite configuration
└── tsconfig.json          # TypeScript configuration

Recommended Directory Structure

This SPA follows a recommended structure for React applications:

your-spa/
├── src/                   # Application source code
│   ├── components/       # Reusable React components
│   ├── pages/            # Page components (for routing)
│   ├── hooks/            # Custom React hooks
│   ├── utils/            # Utility functions
│   ├── services/         # API service layer
│   ├── types/            # TypeScript type definitions
│   ├── assets/           # Images, fonts, icons
│   └── App.tsx           # Main application component
├── public/               # Static assets
├── tests/                # Test files
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   └── e2e/             # End-to-end tests
├── buildspec.yml         # AWS CodeBuild specification
├── package.json          # Dependencies and scripts
└── README.md             # Project documentation

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Open browser to http://localhost:5173

Building for Production

# Build the application
npm run build

# Output directory: dist/
# Files are optimized and minified for production

Deployment

This SPA is designed to be deployed via the AWS SPA Hosting Kit:

1. Configure the hosting kit: Point it to this repository in config.yml
2. Deploy infrastructure: Run npm run deploy in the hosting kit
3. Authorize connection: Complete GitHub OAuth in AWS Console
4. Trigger pipeline: Push code or manually trigger
5. CloudFront serves: SPA is accessible globally via CloudFront URL

Timeline: 5-10 minutes from commit to live

Placeholder Comments

This example SPA includes placeholder comments indicating where you would add:

API Integration

See src/App.tsx for examples of:

• Fetching data from REST APIs
• Integrating with API Gateway
• Handling API responses and errors

Authentication

See src/App.tsx for examples of:

• AWS Cognito integration with Amplify
• Sign-in/sign-out flows
• Protected routes

State Management

See src/App.tsx for examples of:

• Redux setup and usage
• Zustand setup and usage
• Context API patterns

Testing

# Run linter
npm run lint

# Build and preview
npm run build
npm run preview

Configuration

Build Output Directory

Vite outputs to dist/ by default. This matches the hosting kit default configuration.

Environment Variables

To add environment variables:

1. Development: Create .env.local file

   VITE_API_URL=https://dev-api.example.com
   

2. Production: Configure in hosting kit config.yml

   build:
     environmentVariables:
       VITE_API_URL: 'https://api.example.com'

3. Access in code:

   const apiUrl = import.meta.env.VITE_API_URL;

Customization

When adapting this for your own SPA:

1. Update dependencies: Add your required packages
2. Update build command: Modify if using different build script
3. Update output directory: Configure in hosting kit if different from dist/
4. Add environment variables: Configure in hosting kit config.yml
5. Add custom build steps: Update buildspec.yml if needed
6. Add tests: Include test execution in buildspec.yml

Questions

For questions about this example or the AWS SPA Hosting Kit, open an issue on GitHub:

• Example SPA: https://github.com/rusty428/aws-spa-react-example
• Hosting Kit: https://github.com/rusty428/aws-spa-hosting-kit