[webpack] Packaging and Publishing Front-End Projects in Relative Paths

The project I deployed here is the one built in my previous article "Manually Setting Up a React Development Environment." Today, when trying to deploy the package to Tencent Cloud, I encountered some issues.

#Modify nginx configuration

There is already a project deployed at the root path of this server. This time, the project being deployed is an independent one intended for embedding into other applications, so I planned to deploy it under the /a/b path.

I directly copied the existing path configuration and modified it as follows:

shell
location /a/b/ {
    root  html;
    index  /a/b/index.html;
    try_files $uri $uri/ /a/b/index.html;
}

By the way, for single-page applications using history routing, the above try_files needs to be configured so that nginx loads the entry file when the corresponding path resource cannot be found.

#Build and deploy

Create the directory for the corresponding project in nginx and upload the packaged files into it. Then access the project via /a/b.

As a result, the page rendered:

Unexpected Application Error!

404 Not Found

Opening the console, there were no errors, and resources loaded normally. To confirm it was a React error, I copied Unexpected Application Error! and searched in the build files — indeed, it could be found, confirming this was a front-end React error.

This kind of vague error message feels very hard to troubleshoot. Sure enough, both Baidu and GPT failed to provide strongly relevant answers for "React Unexpected Application Error!".

I vaguely suspected it was a routing issue but couldn’t figure out where the problem lay, since my nginx configuration seemed fine and the previous project was deployed the same way.

So I tried changing the project’s routing mode to hash mode, and after deploying to the server, the project worked correctly. Looking at the routing configuration, I suddenly realized that the single-page application internally determines which page to render based on URL matching, and my project running with React couldn’t find the path /a/b.

#Using history routing

#Modify React routing configuration

Actually, we already had a solution in the previous step: use hash routing (if you and your users can tolerate the #).

Since our project is deployed under /a/b, our React routing needs to parse URLs based on this path. Modify our createBrowserRouter function:

js
const router = createBrowserRouter(
  routes,
  process.env.NODE_ENV == "production"
    ? { basename: "/a/b/" }
    : undefined,
)

By configuring the basename property, we set a base path so that in production, React Router can correctly parse our URLs (React Router v6). At the same time, by checking the runtime environment, we only set basename in production, keeping the development environment unchanged.

#Modify webpack configuration

Modifying the routing configuration only makes the project run correctly at runtime; we also need to adjust the webpack build configuration so the project can load resources properly.

Modify the output option in webpack.prod.js:

js
output: {
    publicPath: "/a/b/"
}

Now all relative-path resources will be loaded based on this publicPath (though since the final packaged paths are all relative, adding or omitting it here doesn’t matter much).

After repackaging and redeploying, the project can now load normally under /a/b.

#Start the project in development environment based on a relative path

If you also want to start the project under a path like /a/b in the development environment, you need to modify the following configurations:

• Configure basename in createBrowserRouter
• Change the output publicPath in webpack.dev.js to /a/b, so that your build output is served under the local server’s /a/b path.
• Modify the historyApiFallback configuration in webpack.dev.js:

js
historyApiFallback: {
    rewrites: [
        {
            from: /./,
            to: "/a/b/",
        },
    ],
},

The official explanation is that enabling this setting will make the local server return the project’s entry file for all 404 responses. Since our entry file address is based on the /a/b path, we need to configure the entry file path accordingly.

Now we can debug the project under the /a/b path.