Deploying Your TanStack + Vite Website with a Custom Domain

A step-by-step guide to deploying a modern web application

modern computer workspace with code and server racks

Highlights

Robust Project Setup: Begin with a proper setup of Vite and TanStack Router to enable a smooth deployment process.
Deployment Options Galore: Choose from platforms like GitHub Pages, Netlify, Vercel, and more, all supporting custom domains.
Custom Domain Configuration: Ensure your DNS settings and hosting configurations are aligned for a reliable, branded online presence.

Introduction

Deploying a web application that harnesses TanStack Router with Vite and a custom domain involves several key components. The process includes setting up your development environment, configuring your application routing, building for production, and selecting a hosting platform that supports custom domain integration. In this comprehensive guide, you will learn the best practices and recommended steps necessary to deploy your application in a way that maintains both performance and ease of updates.

Project Setup and Configuration

1. Setting Up the Vite Environment

The foundation for deploying a TanStack Router application begins with setting up Vite. Vite is recognized for its speed and flexibility, particularly when it comes to modern web development. When initializing a Vite project, you typically create the project using one of Vite's templates, such as the React or TypeScript React template.

Initializing Your Project

To start, you can create your project by running a command in your terminal. This will scaffold out a project structure that includes essential folders and configuration files. After the project is created, install the necessary dependencies including TanStack Router:


# Create a new Vite project with React and TypeScript
npm create vite@latest my-app -- --template react-ts
cd my-app

# Install TanStack Router and its plugins
npm install @tanstack/router
npm install --save-dev @tanstack/router-plugin

Once installed, you will need to configure Vite to use the TanStack Router plugin. An example configuration in your vite.config.ts might look like:


import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { TanStackRouterVite } from '@tanstack/router-plugin/vite';

export default defineConfig({
  plugins: [
    react(),
    TanStackRouterVite({ autoCodeSplitting: true }),
  ],
  base: '/', // Adjust as necessary for your custom domain or subdirectory deployment
});

This configuration ensures that your application is set to automatically split code and optimally route pages using TanStack Router. Adjust the base parameter if you are deploying to a platform that might require a subdirectory (for example, GitHub Pages).

2. Configuring Your Routing

TanStack Router provides a flexible, type-safe way of handling routing in your web application. Organizing your routes in the src/routes directory not only improves structure but also leverages file-based routing advantages. Here is an example of how you might set up basic routes:

Creating Routes

Consider creating routes such as a root layout, a home page, and a profile page. These files would typically be structured as follows:


// src/routes/__root.tsx
import { Outlet, createRootRoute } from '@tanstack/react-router';

export const Route = createRootRoute({
  component: () => <Outlet />,
});


// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/')({
  component: () => <div>Welcome to Home!</div>,
});


// src/routes/profile.tsx
import { createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/profile')({
  component: () => <div>Welcome to your Profile!</div>,
});

With these routes configured, you then update your App.tsx file to initiate the router:


import './App.css';
import { RouterProvider, createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const router = createRouter({ routeTree });

function App() {
  return <RouterProvider router={router} />;
}

export default App;

The above setup ensures that your application is structured to handle multiple routes and components effectively.

Building and Deploying The Application

3. Building for Production

Before deployment, it is essential to build your project using Vite's optimized build process. Building your application generates a production-ready version of your website, typically placed in a dist folder. This static output is what gets deployed to your hosting platform.

Running the Build Process

Execute the following command in your terminal:


npm run build

Once the process completes, verify that the dist folder exists and contains all the compiled assets needed for production.

4. Choosing a Deployment Platform

Selecting the appropriate hosting platform is a critical decision. There are several major platforms that support modern web applications and custom domain integration. Below is a comparison table outlining some key differences:

Platform	Deployment Method	Custom Domain Support	Special Features
GitHub Pages	Using GitHub Actions or manual push	Yes; requires DNS configuration and CNAME file	Free hosting for static sites
Netlify	Automatic deployments from Git repository	Yes; straightforward custom domain settings	Serverless functions and edge features
Vercel	Git integrations for continuous deployment	Yes; easy domain management	Optimized for Next.js and modern frameworks
Railway	Quick deployment with templates	Yes; custom domain configuration available	Efficient use of resources

Platforms such as GitHub Pages are highly popular as they integrate seamlessly with Git-based workflows, making them perfect for static web applications built with Vite and TanStack Router. In addition, platforms like Netlify and Vercel offer extra functionalities such as serverless features that may benefit your application.

5. Deploying with GitHub Pages

Deploying to GitHub Pages is one of the most accessible routes, especially if you have an existing repository on GitHub. After building your application, follow these steps to ensure a smooth deployment:

Configuring a GitHub Actions Workflow

Automate your deployment with GitHub Actions by creating a workflow file in .github/workflows/deploy.yml. The workflow automates building your project and deploying the contents of the dist folder to GitHub Pages.


name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        
      - name: Install dependencies
        run: npm ci
        
      - name: Build
        run: npm run build
        
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          cname: yourcustomdomain.com  # Replace with your actual custom domain

This workflow ensures that every push to your main branch triggers an automated build and deployment cycle, making sure your website remains current without the need for manual intervention.

6. Deploying with Alternative Platforms

While GitHub Pages is a popular choice, there are several other robust options available:

Netlify

Netlify offers an extremely user-friendly approach. Simply pushing your code to a Git repository linked with Netlify triggers an automated deployment. After deployment, navigate to the domain management settings to add your custom domain. DNS configuration there is straightforward; just update your DNS records with your domain registrar by adding:

An A record pointing to Netlify’s IP addresses.
A CNAME record for your subdomain that points to your Netlify site.

Vercel

Vercel is another excellent option that focuses on performance. It integrates directly with Git repositories and automatically handles deployment as you push changes. Adding a custom domain in Vercel is made effortless through its dashboard where you can simply verify ownership and update DNS settings as guided.

Other Platforms (Railway, Firebase, Render, Azure)

Platforms like Railway offer one-click deployments along with efficient resource utilization. Firebase and Render deliver excellent static site hosting capabilities, while Microsoft Azure’s Static Web Apps service provides robust hosting options with scalability and seamless integration with other Azure services. Each platform has its own process for adding custom domains, typically involving:

Linking your domain via the project settings.
Configuring DNS records (A records, CNAME records, or even TXT records for verification).
Waiting for DNS propagation to ensure that your site is accessible from your custom domain.

Custom Domain Configuration

7. Domain Registration and DNS Setup

Registering your domain through a reputable domain registrar is the first step. Once registered, you have full control of your DNS settings. To point your domain to the hosting platform:

DNS Record Setup

Follow these guidelines based on your platform:

A Records: These are used to point your primary domain (example.com) to the hosting platform’s IP addresses.
CNAME Records: These point subdomains, such as www.example.com, to your site’s URL provided by the hosting service.
Propagation: Remember that DNS changes can take up to 48 hours to propagate, though they often complete much sooner.

For platforms like GitHub Pages, it is often necessary to include a CNAME file in your public directory that contains your custom domain name. This file informs GitHub Pages to correctly map your project’s output to your custom domain.

8. Updating Your Vite Configuration

To properly support a custom domain and ensure correct routing, update the base URL in your vite.config.ts. This step is crucial if you deploy your site in a subdirectory or if the hosting platform requires a specific base path.

Example Vite Config Base Update

The configuration snippet might look like this:


export default defineConfig({
  base: '/',  // Use '/' or '/sub-directory/' if needed.
  plugins: [react(), TanStackRouterVite()],
});

Ensuring the correct base path helps maintain the integrity of your application’s routing, especially when deployed on different hosting platforms.

Testing and Maintenance

9. Post-Deployment Testing

After your website has been deployed and the custom domain has been configured, it’s important to test the site thoroughly. Verify that:

All routes function correctly, even if the user refreshes the browser or navigates directly to a route.
The custom domain resolves to your deployed site without errors.
There are no broken links, especially in client-side routing managed by TanStack Router.

For static site hosting, consider adding a fallback 404 route or redirect mechanism to handle unmatched routes. This helps in cases where direct URL entry could otherwise lead to a broken page.

10. Continuous Maintenance and Updates

Deployment is not the end of your development journey. Ongoing maintenance is essential to ensure that your site remains secure, up-to-date, and performing optimally:

Periodically update dependencies such as Vite, TanStack Router, and other plugins to avoid potential security issues.
Monitor your DNS and hosting configurations to adjust for any changes made by your hosting provider.
Implement continuous integration and continuous deployment (CI/CD) workflows to periodically rebuild and redeploy your site as new features are added.

These steps help maintain a robust and agile deployment process, ensuring that your website can quickly adapt to new requirements or changes.

Advanced Considerations

11. Handling Client-Side Routing on Static Hosts

Modern single-page applications (SPA) often rely on client-side routing for navigation. However, hosting on static platforms can introduce challenges such as handling direct URL access or page refreshes. To combat this, many hosting platforms offer redirect options:

Redirect Rules and Fallbacks

For example, on GitHub Pages, you can use a custom 404.html page that automatically redirects users back to index.html while preserving the subpath as a query parameter. Similarly, on Netlify and Vercel, you can define a redirection configuration (often in a _redirects file) so that all traffic is properly served by your application.

These configurations ensure that refreshing the page or directly accessing a nested URL does not break your application’s routing logic and provides a seamless user experience.

12. Optimizing Your Build

To enhance the performance of your deployed website, consider several additional optimizations:

Code Splitting: Vite supports automatic code splitting which can reduce initial load time.
Lazy Loading: Load components only when needed to improve responsiveness.
Minification and Compression: Utilize Vite’s built-in minification options to reduce the size of your JavaScript and CSS bundles.
Edge Functions: If hosting on platforms like Netlify, explore using serverless functions for tasks that can benefit from edge computing.

These optimizations result in faster load times and improved overall performance, ensuring that your website remains competitive in terms of speed.

Conclusion and Final Thoughts

Deploying a TanStack + Vite website with a custom domain is a process that incorporates multiple critical steps—from initial project setup and routing configuration to selecting the best hosting platform and correctly configuring DNS records. The process involves:

Establishing a robust Vite project configuration with TanStack Router, ensuring a seamless development environment.
Building and optimizing your application for production use, with attention to techniques such as code splitting and lazy loading.
Deploying on a platform that suits your needs, whether it be GitHub Pages for a simple static site or Netlify/Vercel for added functionality and automation.
Carefully configuring your DNS and custom domain settings to ensure that your website is accessible by your chosen domain.
Implementing effective routing fallback mechanisms to handle direct URL access and page refresh in single-page applications.

With ongoing maintenance through regular updates and an emphasis on performance optimization, your deployed website will offer users a secure, fast, and engaging experience. This comprehensive approach not only guarantees a smooth deployment process but also ensures that any future updates or scaling decisions are easily managed. Overall, the integration of Vite and TanStack Router creates a solid foundation, while the chosen hosting platform and custom domain configuration add the necessary polish for a professional online presence.

Whether you choose GitHub Pages, Netlify, Vercel, or another modern hosting solution, following the best practices outlined in this guide will lead to a reliable and performant deployment of your web application. Embrace continuous integration and deployment strategies to make sure your site remains up-to-date, and enjoy the benefits of using cutting-edge development tools to create exceptional user experiences.

References

Deploying a Static Site | Vite - Vite
GitHub Pages for React: Vite Deployment and Custom Domain Configuration - Troncodes
TanStack Start - TanStack
Deploying a Static Vite React App - Dev.to