Build Process

Velocity uses esbuild, a powerful JavaScript and TypeScript bundler and minifier. The build script, located in ./build.mjs, leverages esbuild's capabilities to compile and optimize both the client and server code.

About esbuild

esbuild is a modern build tool for JavaScript applications, known for its remarkable speed and efficient bundling. It's utilized in the Velocity project for both client and server builds, showcasing the flexibility and power of esbuild in handling complex configurations and delivering optimized code.

Running the Build Process

You can manually initiate the build process using pnpm build, but in most cases, you will execute it through the development script, pnpm dev. This command ensures that the application is rebuilt whenever necessary, making it ideal for development use. The build result is then placed in the .build directory.

Esbuild Configuration

Esbuild is highly customizable and allows us to create shared and target-specific configurations. Our shared configurations include options for tree shaking, defining environment variables, and setting loader configurations for different file types. For target-specific configurations, we tweak settings such as output directories, source maps, platform, format, and code splitting (client), or target setting, minification, JSX options, and output file path (server).

Esbuild and TypeScript

Esbuild natively supports TypeScript, which means you can import TypeScript files directly without needing a separate compilation step. The type checking, however, is not performed by esbuild. While esbuild transforms TypeScript syntax into JavaScript, it does not check the types, which is one of the main benefits of using TypeScript.

In our build script, we use esbuild to transform and bundle TypeScript files, but we still run the TypeScript compiler (tsc) in the background to check types. This gives us the best of both worlds: the exceptional build speed of esbuild and the robust type checking of TypeScript.

During development, esbuild watches for changes in TypeScript files and triggers rebuilds as needed. This feature allows for a faster, more efficient development process.

Build Execution

In the build execution stage, the script sets up the environment, rebuilds Tailwind CSS (in production mode), and initiates the client and server builds. For the client build, files ending with a .entry.ts or .entry.css suffix are selected as entry points. If in development mode, the script also watches for changes and triggers rebuilds when necessary, starts a local server, sets up an HTTPS proxy for Storyblok's preview mode, and watches the 'src' directory to track changes to .entry.ts and .entry.css files. In contrast, production mode runs the builds once.