websmith-loader

A drop-in replacement for the ts-loader to add the websmith compiler to your build and bundling process. Websmith provides an API to create compiler addons to modify the compilation input before, during and after compiled artifacts are created, compilation profiles to specify individual environments for different outputs, and integrates seamlessly with webpack build commands.

Visit the websmith github repository for more information and examples.

Getting started

Whenever you use the ts-loader to compile your TypeScript project, you can replace it with the websmith-loader command and apply compiler addons.

Installation

Add the loader to your TypeScript project with the websmith-loader package. For example, use the following command with pnpm:

pnpm add --dev websmith-loader

Use websmith-loader in your webpack configuration

You can use the websmith-loader loader in your webpack configuration by adding the following entry to your module.rules configuration:

// ./webpack.config.js
const { join } = require("path");

module.exports = {
    // ...
    module: {
        rules: [
            {
                test: /\.(?:[j|t]sx?)$/,
                use: [
                    {
                        loader: "websmith-loader",
                        options: {
                            tsConfigFile: join(__dirname, "tsconfig.json"),
                            config: {
                                addonsDir: join(__dirname, "addons"),
                                addons: ["export-yaml-generator"],
                            },
                            transpileOnly: true,
                            addonEmitOnly: false, // Set to true to only emit files processed by addons
                        },
                    },
                ],
            },
            // ...
        ],
    },
};

The default configuration uses the tsconfig.json file in your project root to compile the TypeScript files. Add a custom compilation config to the loader options or use the websmith.config.json file to configure the compilation output.

Loader Options

• tsConfigFile (string): Path to the TypeScript configuration file
• config (object): Websmith configuration (can also be loaded from websmith.config.json)
• transpileOnly (boolean): Enable transpile-only mode for faster builds without type checking
• addonEmitOnly (boolean): Only emit files that are processed by active addons. When enabled, all files are still compiled for dependencies and type checking, but only files processed by addon callbacks (generators, processors, transformers) are written to disk. This is useful for code generation workflows where you want to preserve original source files unchanged while emitting only generated or transformed files.
• profile (string): Name of the compilation profile to use

Add websmith configuration

You can use a websmith.config.json file to configure which addons should be used for what profile by websmith during the webpack compilation process:

// websmith.config.json
{
    "profiles": {
        "executeAddons": {
            "addons": ["my-addon"],
        },
    }
}

Note: The webpack loader will expect a profile called executeAddons which we need to configure in the webpack configuration.

Read more about compilation profiles in the websmith compiler documentation. Or check out more details on the configuration file in the compiler documentation.