Deploying to a Static Host (Nginx, S3)
Relevant source files
The following files were used as context for generating this wiki page:Introduction
This project is a static Single Page Application (SPA) built with React and Vite. This architecture means the entire application is delivered as a set of static files (HTML, CSS, JavaScript) that run in the user's browser. This makes it exceptionally easy to deploy on any platform that supports static file hosting, such as traditional web servers like Nginx and Apache, or cloud storage services like AWS S3, Netlify, and Cloudflare Pages.
The key to deploying this SPA is a two-step process: first, building the production-ready static assets, and second, configuring the static host to serve these assets correctly. A crucial configuration for SPAs is handling client-side routing by redirecting all path requests to the main index.html file.
Sources: README.md:30-32, README.md:65-68, package.json
Build Process
The project uses Vite as its build tool to bundle the React/TypeScript source code into optimized static files for production.
Sources: package.json:17, vite.config.ts
Build Command
To generate the static assets, run the following command from the project's root directory:
npm run build
This command is defined in the scripts section of the package.json file and executes vite build.
Sources: package.json:7, README.md:61-64
Build Output
The build process generates a dist folder in the project root. This folder contains all the necessary files to run the application. The contents of this dist folder are what you will upload to your static hosting provider.
The diagram below illustrates the build process flow.
This diagram shows how the npm run build command initiates the Vite build process, resulting in the dist directory containing the static application files.
Sources: README.md:61-64, package.json:7
Deployment Artifacts
The dist directory contains the compiled and bundled application. The primary files are:
| File/Directory | Description | Source File |
|---|---|---|
index.html | The main entry point for the application. The web server should be configured to serve this file. | index.html |
assets/ | A directory containing the bundled and minified JavaScript, CSS, and other static assets like images. | vite.config.ts |
The application's entry point is index.html, which contains a <div id="root"></div>. The React application is mounted into this element by the bundled JavaScript.
Sources: README.md:65-66, index.html:81, index.tsx:4
Server Configuration for SPAs
A critical aspect of deploying an SPA is configuring the web server to handle client-side routing. Since the application handles its own routing in the browser, any request for a specific path (e.g., /some/path) that isn't a direct file request must be redirected to index.html. This allows the React application to load and then interpret the URL path.
If this is not configured, users who try to access a deep link directly will receive a 404 Not Found error from the server.
Sources: README.md:68-70
Request Handling Flow
The following diagram shows the correct request handling flow for an SPA on a static host.
This sequence diagram illustrates how a static server should handle both root requests and deep-link requests for a Single Page Application.
Sources: README.md:68-70
Deployment Steps Summary
The general steps to deploy to a static host like Nginx or an S3 bucket are as follows:
| Step | Action | Details |
|---|---|---|
| 1 | Build the Project | Run npm run build locally to create the dist directory. |
| 2 | Upload Artifacts | Upload the contents of the dist folder to your server's public root (e.g., /var/www/html for Nginx) or the root of an S3 bucket. |
| 3 | Configure Redirects | Set up a server-side rule to redirect all requests that would otherwise result in a 404 error to serve the index.html file instead. |
Sources: README.md:61-70
Conclusion
The project's architecture as a static Single Page Application built with Vite greatly simplifies the deployment process. By running a single build command, all necessary assets are generated in a self-contained dist directory. The only significant server-side consideration is implementing a rewrite/redirect rule to forward all non-file requests to index.html, ensuring that client-side routing functions correctly. This makes the application highly portable and compatible with a wide range of modern, low-cost static hosting solutions.
Sources: README.md:30-32, App.tsx