Recap of Part 1: In the first installment of this series, we laid the groundwork for our modern React SPA boilerplate using Webpack 5.
We covered the basics of Webpack, including core
concepts like entry points, outputs, loaders, and plugins. We also set
up our npm environment, ensuring consistency with Node v20 LTS, and
introduced a basic TypeScript configuration.
With a foundational Webpack setup in place, we're now ready to dive into integrating Babel, Webpack Dev Server and React to enhance our SPA's capabilities.
Babel setup
In order to use latest JavaScript features, while supporting older browsers, we need to use transpiler. In this configuration step, we will use babel.
Install following dev-dependencies:
npm i -D babel-loader @babel/preset-typescript @babel/preset-react @babel/preset-env @babel/core
Since preset-env requires core-js we need to install it as well
npm install core-js@3
Additionally we need to specify what browsers need to be supported. You can create the required file with following command.
echo -e "> 0.25%\nnot dead" > .browserslistrc
Last but not least to finalize babel setup we would need to create babel.config.js file with following presets:
-
@babel/preset-env- simply allow to use latest JS syntax, without worry about browser support -
@babel/preset-typescript- project uses TypeScript, so we need it -
@babel/preset-react- allows Babel to parse JSX and other React related stuff
Final config file looks like this
//babel.config.js
/**
* @type {import('@babel/core').TransformOptions}
*/
const config = {
presets: [
[
"@babel/preset-env",
{
useBuiltIns: "usage",
corejs: { version: "3.35", shippedProposals: true }
},
],
"@babel/preset-typescript",
[
"@babel/preset-react",
{
runtime: "automatic",
development: process.env.NODE_ENV !== "production",
},
],
],
};
module.exports = config;
Now we need to tell Webpack how to handle tsx and ts files, current Webpack config need to be extended with following rules:
module: {
rules: [
{
test: /\.(js|mjs|ts|tsx)$/,
include: path.resolve(process.cwd(), "src"),
loader: "babel-loader",
},
],
},
resolve: {
extensions: [".ts", ".tsx", ".js"],
},
This allow to pass all the files (tsx, ts, js) in src directory through babel and apply changes to use it safely in the browser.
Environment variables
To clear any confusion around envs on the frontend, let's clarify one thing: every env listed in .env.prod will be publicly available. If you need a way to hide some sort of API_KEY - you need most likely a backend proxy layer.
With public nature of envs on frontend world, lets dive into implementation. The idea is to provide our envs and build time, so when application is being deployed the envs will be available in the runtime. Without it we would end up with runtime error: process is no defined as it is part of Node.js not browser runtime.
The whole mechanism is easily extendable for adding new environments (staging, test or whatever you want) - but for now we will stick with basic setup for:
- production
- local
With that in mind lets create 3 files:
- .env.prod - envs for production
- .env.local - envs for local development Note: it must be added to .gitignore to not expose it
- .env.example - example envs structure that matches .env.prod - new dev can easily copy it and fill with proper values
For now we can add only one variable called for instance ENVIRONMENT_NAME for simplicity it cane be either prod or local
Next install package dotenv which will help us manage the environment variables:
npm i -D dotenv
Once we have the envs and dotenv installed, we need to tell Webpack to add envs to code at build time. We need some helpers functions so it would be good idea to defined them under config/env.ts with following content:
import dotenv from "dotenv";
import path from "path";
type EnvironmentVariable = Record<string, string>;
export const loadEnvs = (): EnvironmentVariable => {
const environment = process.env.NODE_ENV || "prod";
const envPath = path.resolve(process.cwd(), `.env.${environment}`);
const result = dotenv.config({ path: envPath });
if (result.error) {
console.error(`Failed to load .env file: ${envPath}`, result.error);
throw result.error;
}
return result.parsed || {};
};
export const mapEnvsToConfig = (envs: {
[key: string]: string;
}): EnvironmentVariable => {
return Object.keys(envs).reduce<EnvironmentVariable>((prev, next) => {
prev[`process.env.${next}`] = JSON.stringify(envs[next]);
return prev;
}, {});
};
Function loadEnvs is getting proper env file based on NODE_ENV environment variable and creates config using dotenv package.
However we still need to provide envs to Webpack in proper format, this task is handled by mapEnvsToConfig
Last step is to import those functions to webpack config and provide NODE_ENV for build npm script:
Webpack
//...
import { loadEnvs, mapEnvsToConfig } from "./config/env";
const createWebpackConfig = (mode: Configuration["mode"]): Configuration => {
// load envs
const envs = loadEnvs();
const envsConfig = mapEnvsToConfig(envs);
return {
mode: mode,
entry: path.resolve(process.cwd(), "src/index.ts"),
module: {
rules: [
{
test: /\.(js|mjs|ts|tsx)$/,
include: path.resolve(process.cwd(), "src"),
loader: "babel-loader",
},
],
},
resolve: {
extensions: [".ts", ".tsx", ".js"],
},
output: {
path: path.resolve(process.cwd(), "dist"),
clean: true,
},
// pass them to Webpack so that process.env.ENVIRONMENT_NAME won't be undefined
plugins: [new DefinePlugin(envsConfig)],
};
};
Build script - we still need to pass NODE_ENV
"scripts": {
"build": "webpack --config scripts/build.ts --node-env=prod"
},
React
Install React
npm i react react-dom
And types for React
npm i -D @types/react-dom @types/react
Since we are working on SPA add index.html inside of new folder public
Example content of the index.html can be as follow
<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Webpack React Boilerplate</title>
</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="root"></div>
</body>
</html>
Additionally we need to tell TypeScript that we are using JSX, add following line to compilerOptions of tsconfig.json
"jsx": "react-jsx",
Next we need dummy react component and bootstrap to mount application in root
Dummy app
// src/App.tsx
export const App = () => {
return <p>Hello World</p>;
};
// src/bootstrap.tsx
import { createRoot } from "react-dom/client";
import { App } from "./App";
const render = () => {
const container = document.getElementById("root");
if (container) {
const root = createRoot(container);
root.render(<App />);
}
};
render();
Using render function allows us to have flexibility to pass some configuration to it, for instance when you switch from build-time envs to runtime.
Last we need to update the src/index.ts to address changes done in bootstrap
// src/index.ts
import('./bootstrap');
export {};
Finally we will setup the dev-server to be able spin up the development environment.
Install dev-server package and html plugin
npm i -D webpack-dev-server html-webpack-plugin
In order to include webpack bundles automatically as script tags in index.html we need to add HTML plugin with some configuration
//webpack.config.ts
plugins: [
new DefinePlugin(envsConfig),
// new plugin for dealing with HTML
new HtmlWebpackPlugin({
inject: true,
template: path.resolve(process.cwd(), "public/index.html"),
}),
],
Next we need function that encapsulate the creating dev-server setup create following file config/devServer.ts which will have that config function
import path from "path";
import { WebpackConfiguration } from "webpack-dev-server";
const defaultPort = Number(process.env.PORT) || 8080;
export const createDevServerConfig = (): WebpackConfiguration["devServer"] => ({
historyApiFallback: {
disableDotRule: true,
index: "/",
},
client: {
overlay: false,
logging: "info",
},
static: {
directory: path.resolve(process.cwd(), "public"),
serveIndex: true,
watch: true,
},
liveReload: false,
hot: true,
open: false,
port: defaultPort,
});
You can define PORT environment variable if you need more flexibility otherwise it will use default 8080
Generate the dev-server only for dev mode in webpack config
resolve: {
extensions: [".ts", ".tsx", ".js"],
},
// use it only for dev mode
...(mode === "development"
? {
devServer: createDevServerConfig(),
}
: {}),
output: {
path: path.resolve(process.cwd(), "dist"),
publicPath: "/",
clean: true,
},
Last but not least we need new scripts/start.ts to be able to use it in npm scripts like build command.
import createWebpackConfig from "../webpack.config";
export default () => {
return createWebpackConfig("development");
};
Additionally it has to be specified in package.json as well
"scripts": {
"build": "webpack --config scripts/build.ts --node-env=prod",
"start": "webpack serve --config scripts/start.ts --node-env=local"
},
That concludes this part. You can review all the details in following PR: https://github.com/Verthon/webpack-react-boilerplate/pull/2
Currently we have setup for modern JS, dev-server and React. In upcoming next part configuration will be extended with:
- providing assets handling configuration
- providing test configuration with Jest
- basic configuration for CSS
- adding bundle analyzer to track bundle-size in each build
- minimal docs in the readme
Thank you, any feedback is highly appreciated.
Top comments (0)