Vite: Serving Extra HTML In Nested Public Folders From CRA

Aug 20, 2025 by Henrik Larsen 59 views

Serving Extra HTML Files in Nested Public Folders with Vite: A Migration Headache from CRA

Hey everyone! So, I recently made the leap from Create React App (CRA) to Vite, and let me tell you, it's been quite the adventure. One particular issue that had me scratching my head for a while was serving an extra HTML file nestled inside a folder within my public directory. In my old CRA setup, I had an index.html file living happily under public/ohif-viewer, and accessing it was a breeze. But with Vite, things got a little... interesting. Let's dive into the nitty-gritty of the problem and how I eventually wrestled it into submission.

The Problem: CRA vs. Vite in Serving Static Assets

In the world of web development, serving static assets like HTML, CSS, images, and JavaScript files is a fundamental task. Create React App (CRA) and Vite, both popular build tools, handle this in slightly different ways, which can lead to unexpected behavior when migrating projects. CRA, with its zero-config philosophy, automatically serves files from the public directory. This means that any file placed in the public folder is directly accessible via the base URL of your application. For instance, if you have public/ohif-viewer/index.html, you could access it by navigating to /ohif-viewer/ in your browser. This simplicity is one of CRA's strengths, making it easy for developers to get started without worrying about complex configurations.

However, Vite takes a different approach. While it also has a public directory, Vite's primary focus is on serving assets that are explicitly imported or referenced in your JavaScript or CSS code. This is part of Vite's strategy to optimize the build process and improve performance. Vite uses a modern approach to asset handling, leveraging ES modules and dynamic imports to efficiently load and manage resources. This means that simply placing an HTML file in the public directory doesn't automatically make it accessible. Vite needs to be aware of the file and how it should be served. This difference in how CRA and Vite handle static assets is crucial to understand when migrating a project. The implicit serving of files in CRA becomes an explicit task in Vite, requiring a bit more configuration and planning.

This shift in paradigm can be a bit of a shock, especially if you're used to CRA's more hands-off approach. In my case, the index.html file in public/ohif-viewer was essentially invisible to Vite, causing a 404 error when I tried to access it. This is because Vite, by default, only serves the main index.html file in the root of the public directory and any assets that are explicitly linked in your application's code. This behavior is a deliberate design choice to optimize performance and ensure that only necessary files are served. Understanding this distinction is the first step in troubleshooting issues when migrating from CRA to Vite.

My Specific Scenario: The `ohif-viewer` Subdirectory

In my project, the extra index.html file wasn't just any static asset; it was the entry point for a specific part of my application, the OHIF Viewer. The OHIF Viewer is a powerful open-source medical imaging viewer, and I had integrated it into my project as a separate component. This meant that I needed a way to serve the viewer's HTML, CSS, and JavaScript files independently from the main application. Under CRA, this was straightforward: I simply placed the necessary files in the public/ohif-viewer directory, and CRA took care of the rest. The URL /ohif-viewer/ would magically serve the viewer, allowing users to interact with it seamlessly. This setup worked perfectly in the CRA environment, making the integration of the OHIF Viewer a breeze.

However, Vite's more explicit approach to asset serving threw a wrench in the works. When I migrated to Vite, the /ohif-viewer/ route returned a dreaded 404 error. Vite, unlike CRA, didn't automatically serve the index.html file in the subdirectory. This was because Vite's default configuration is designed to serve the main application's entry point and any assets that are explicitly imported or referenced in the application's code. The index.html file in public/ohif-viewer wasn't directly linked in my application's main JavaScript or HTML files, so Vite simply ignored it. This behavior is by design, as Vite aims to optimize the build process by only serving necessary files. This explicit approach, while beneficial for performance, required me to rethink how I served the OHIF Viewer within my Vite project.

The challenge was clear: I needed to find a way to tell Vite to serve the index.html file in public/ohif-viewer when a user navigated to /ohif-viewer/. This involved delving into Vite's configuration options and exploring different strategies for handling static assets. The solution had to be both efficient and maintainable, ensuring that the OHIF Viewer continued to function correctly within the Vite environment. This required a deeper understanding of Vite's plugin system and how it interacts with static assets.

Diving into Solutions: The `vite.config.js` File

The heart of any Vite project lies in its vite.config.js file. This file is where you configure Vite's behavior, from setting up aliases to defining custom plugins. It's the control center for your Vite build, and it's where I knew I needed to make changes to get my ohif-viewer subdirectory working. The vite.config.js file is essentially a JavaScript module that exports a configuration object. This object can contain various options that tell Vite how to build and serve your project. For example, you can specify the input files, the output directory, and how to handle different types of assets.

One of the key areas to explore in vite.config.js is the publicDir option. By default, Vite assumes that your static assets are located in the public directory at the root of your project. However, this option allows you to customize the location of the public directory. While this didn't directly solve my problem of serving a specific file in a subdirectory, understanding this option was crucial for exploring other solutions. Another important aspect of the vite.config.js file is the plugins array. Vite uses plugins to extend its functionality, and there are many community-developed plugins that can help with various tasks, such as handling static assets, optimizing images, and more. These plugins are essentially JavaScript modules that tap into Vite's build process and modify its behavior. This extensibility is one of the key strengths of Vite, allowing developers to tailor the build process to their specific needs.

To solve my issue, I considered several approaches using vite.config.js. One option was to explore the server configuration, which allows you to customize Vite's development server. This includes options for setting up proxies, custom middleware, and more. Another approach was to look for a Vite plugin that specifically handles serving static files in subdirectories. The Vite ecosystem is rich with plugins, and I was hopeful that someone had already tackled a similar problem. Ultimately, the solution involved a combination of understanding Vite's core configuration options and leveraging its plugin system. The vite.config.js file became my playground, where I experimented with different approaches until I found the right one. This hands-on approach not only solved my immediate problem but also deepened my understanding of Vite's inner workings.

The Solution: A Custom Plugin to the Rescue

After some digging and experimenting, I realized that the most flexible and maintainable solution was to create a custom Vite plugin. Vite's plugin system is incredibly powerful, allowing you to hook into various stages of the build process and modify Vite's behavior. A custom plugin would give me fine-grained control over how my index.html file in public/ohif-viewer was served. Creating a Vite plugin involves writing a JavaScript module that exports an object with a name property and a set of hooks that Vite calls during the build process. These hooks allow you to tap into different stages of the build, such as resolving modules, transforming code, and generating output files. The name property is simply a unique identifier for your plugin, and the hooks are where you implement the plugin's logic.

In my case, I needed to hook into the configureServer hook, which is called when Vite's development server is being configured. This hook provides access to the Connect server instance, allowing me to add custom middleware. Middleware functions are the building blocks of web servers, handling incoming requests and generating responses. By adding custom middleware, I could intercept requests for /ohif-viewer/ and serve the index.html file from the public/ohif-viewer directory. This approach would essentially mimic CRA's behavior of automatically serving files from the public directory, but with the added control and flexibility of Vite's plugin system.

The plugin itself was relatively simple. It checked if the incoming request URL matched /ohif-viewer/ and, if so, read the index.html file from public/ohif-viewer and served it. This approach ensured that the OHIF Viewer was accessible via the expected URL, just like it was in my CRA project. The key advantage of using a custom plugin is that it encapsulates the logic for serving the extra HTML file, making it reusable and maintainable. If I needed to serve other files in subdirectories, I could easily extend the plugin to handle those cases as well. This approach also keeps my vite.config.js file clean and organized, as the plugin's logic is separated from the main configuration.

Code Snippet: The Custom Vite Plugin

To give you a clearer picture, here's a simplified version of the custom Vite plugin I created:

// vite-plugin-ohif-viewer.js
import path from 'path';
import fs from 'fs';

function vitePluginOhifViewer() {
 return {
 name: 'vite-plugin-ohif-viewer',
 configureServer(server) {
 server.middlewares.use((req, res, next) => {
 if (req.url === '/ohif-viewer/') {
 const htmlPath = path.resolve(__dirname, 'public/ohif-viewer/index.html');
 const htmlContent = fs.readFileSync(htmlPath, 'utf-8');
 res.setHeader('Content-Type', 'text/html');
 res.end(htmlContent);
 } else {
 next();
 }
 });
 },
 };
}

export default vitePluginOhifViewer;

This plugin works by intercepting requests to /ohif-viewer/ and serving the index.html file from the public/ohif-viewer directory. Let's break down the code step by step:

Importing Modules: The plugin imports the path and fs modules from Node.js. The path module is used for resolving file paths, and the fs module is used for reading files.
Plugin Function: The vitePluginOhifViewer function is the main entry point for the plugin. It returns an object that represents the plugin.
Plugin Object: The plugin object has two properties: name and configureServer. The name property is a unique identifier for the plugin, and the configureServer property is a hook that Vite calls when configuring its development server.
configureServer Hook: The configureServer hook receives the Vite server instance as an argument. This instance has a middlewares property, which is an array of middleware functions. The plugin adds a custom middleware function to this array using the use method.
Middleware Function: The middleware function is an anonymous function that receives three arguments: req (the request object), res (the response object), and next (a function to call the next middleware in the chain).
Request Handling: The middleware function checks if the request URL (req.url) is equal to /ohif-viewer/. If it is, the plugin proceeds to serve the index.html file.
Reading the HTML File: The plugin uses the path.resolve function to construct the absolute path to the index.html file in the public/ohif-viewer directory. It then uses the fs.readFileSync function to read the contents of the file into a string.
Setting Headers and Sending the Response: The plugin sets the Content-Type header of the response to text/html and then sends the HTML content using the res.end method.
Calling next(): If the request URL is not /ohif-viewer/, the plugin calls the next() function to pass the request to the next middleware in the chain.

To use this plugin, you would import it into your vite.config.js file and add it to the plugins array:

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import vitePluginOhifViewer from './vite-plugin-ohif-viewer';

export default defineConfig({
 plugins: [
 react(),
 vitePluginOhifViewer(),
 ],
});

This code snippet demonstrates how a custom Vite plugin can be used to solve the problem of serving extra HTML files in subdirectories. The plugin's modular design makes it easy to reuse and maintain, and its integration with Vite's middleware system ensures that it works seamlessly with the rest of the application.

Lessons Learned and Best Practices

Migrating from CRA to Vite can be a smooth experience, but it's essential to understand the differences in how these tools handle static assets. Here are some key takeaways from my experience:

Explicit vs. Implicit Serving: CRA implicitly serves files from the public directory, while Vite requires you to explicitly link or reference assets in your code or configure custom behavior.
Vite's publicDir: While Vite has a publicDir option, it doesn't automatically serve files in subdirectories like CRA does.
Custom Plugins: Vite's plugin system is incredibly powerful. Creating custom plugins is a great way to handle specific needs and maintain a clean configuration.
Middleware Magic: Using middleware in a custom plugin allows you to intercept requests and serve files as needed, giving you fine-grained control over Vite's behavior.

In the future, I'll definitely keep these lessons in mind when structuring my projects and migrating between build tools. Understanding the underlying mechanisms of tools like Vite and CRA is crucial for building robust and maintainable applications. By embracing Vite's explicit approach and leveraging its plugin system, I was able to overcome this hurdle and create a better development experience for myself and my team.

So, if you're facing a similar issue with Vite and extra HTML files, don't despair! A custom plugin might be just the ticket. Happy coding, folks!