@salt-ngx/builder

Enhanced Angular builders with custom webpack, esbuild, and development server support. This package extends Angular's build system to provide powerful customization capabilities while maintaining full compatibility with Angular CLI.

🚀 Features

• Custom Webpack Support - Extend Angular's webpack configuration with smart merging
• ESBuild Enhancement - Add custom plugins and transformers to esbuild builds
• Development Server Extensions - Custom middleware and enhanced dev servers
• Build Optimization - Advanced optimization techniques for better performance
• TypeScript Support - Full TypeScript definitions and IntelliSense support

📦 Installation

npm install @salt-ngx/builder
# or
yarn add @salt-ngx/builder
# or
pnpm add @salt-ngx/builder

🛠️ Available Builders

1. Browser Builder (@salt-ngx/builder:browser)

Purpose: Webpack-based browser builds with custom configuration support

Use Case: Legacy applications requiring specific webpack customizations

{
  "architect": {
    "build": {
      "builder": "@salt-ngx/builder:browser",
      "options": {
        "main": "src/main.ts",
        "tsConfig": "tsconfig.app.json",
        "outputPath": "dist",
        "customWebpackConfig": "webpack.config.js"
      }
    }
  }
}

Advanced Configuration:

{
  "customWebpackConfig": {
    "path": "webpack.config.js",
    "mergeRules": {
      "module": {
        "rules": {
          "test": "match",
          "use": "merge"
        }
      }
    },
    "replaceDuplicatePlugins": false,
    "verbose": {
      "properties": ["plugins", "resolve"],
      "serializationDepth": 3
    }
  }
}

2. Application Builder (@salt-ngx/builder:application)

Purpose: Modern esbuild-based builds with custom plugins

Use Case: High-performance builds with esbuild optimization

{
  "architect": {
    "build": {
      "builder": "@salt-ngx/builder:application",
      "options": {
        "browser": "src/main.ts",
        "tsConfig": "tsconfig.app.json",
        "outputPath": "dist",
        "plugins": ["./plugins/my-esbuild-plugin.js"],
        "indexHtmlTransformer": "./transformers/html-transformer.js"
      }
    }
  }
}

3. Webpack Dev-Server (@salt-ngx/builder:webpack-dev-server)

Purpose: Development server with custom webpack configuration

Use Case: Development environment with webpack-specific features

{
  "architect": {
    "serve": {
      "builder": "@salt-ngx/builder:webpack-dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "customWebpackConfig": "webpack.dev.config.js",
        "port": 4300,
        "ssl": true,
        "proxyConfig": "proxy.conf.json"
      }
    }
  }
}

4. ESBuild Dev-Server (@salt-ngx/builder:esbuild-dev-server)

Purpose: High-performance development server with custom middleware

Use Case: Fast development with custom server-side logic

{
  "architect": {
    "build": {
      "builder": "@salt-ngx/builder:application",
      "options": {
        "plugins": ["./plugins/dev-plugin.js"]
      }
    },
    "serve": {
      "builder": "@salt-ngx/builder:esbuild-dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "middlewares": [
          "./middlewares/auth-middleware.js",
          "./middleware/logging-middleware.js"
        ],
        "port": 4300
      }
    }
  }
}

📚 Examples

Custom Webpack Plugin

Create a custom webpack configuration:

webpack.config.js

const TerserPlugin = require('terser-webpack-plugin');

module.exports = (config, buildOptions) => {
  // Custom optimization
  config.optimization.minimizer.push(
    new TerserPlugin({
      extractComments: false,
      terserOptions: {
        compress: {
          drop_console: true
        }
      }
    })
  );

  return config;
};

ESBuild Plugin

Create a custom esbuild plugin:

plugins/custom-esbuild-plugin.js

const esbuildPlugin = (options) => ({
  name: 'custom-plugin',
  setup(build) {
    build.onResolve({ filter: /\.custom$/ }, args => {
      return { path: args.path + '.js' };
    });
  }
});

module.exports = esbuildPlugin;

Custom Middleware

Create a custom middleware for the dev-server:

middlewares/auth-middleware.js

module.exports = (req, res, next) => {
  // Custom authentication logic
  if (req.url.startsWith('/api/')) {
    req.headers['x-custom-header'] = 'authenticated';
  }
  next();
};

Index HTML Transformer

Create a custom HTML transformer:

transformers/html-transformer.js

module.exports = (target, indexHtml) => {
  // Custom HTML transformation
  return indexHtml.replace(
    '<title>',
    '<title>Custom Title - '
  );
};

⚙️ Configuration Options

Browser Builder Options

| Option | Type | Description | |--------|------|-------------| | customWebpackConfig | string \| object | Path to webpack config or detailed config object | | mergeRules | object | Custom merge rules for webpack-merge | | replaceDuplicatePlugins | boolean | Replace duplicate plugins instead of merging | | verbose.properties | string[] | List of config properties to log |

Application Builder Options

| Option | Type | Description | |--------|------|-------------| | plugins | string[] | Array of esbuild plugin paths | | indexHtmlTransformer | string | Path to HTML transformer module |

Dev-Server Options

| Option | Type | Description | |--------|------|-------------| | middlewares | string[] | Array of middleware file paths | | port | number | Development server port | | ssl | boolean | Enable HTTPS | | proxyConfig | string | Path to proxy configuration file |

🏗️ Project Structure

src/
├── builders/
│   ├── browser/              # Webpack browser builder
│   ├── application/          # ESBuild application builder
│   ├── webpack/
│   │   └── dev-server/       # Webpack dev-server builder
│   └── esbuild/
│       └── dev-server/       # ESBuild dev-server builder
├── utils/
│   ├── webpack-config-merger.ts
│   └── custom-webpack-builder.ts
└── builders.json             # Builder registration

🎯 Use Cases

Legacy Projects

Use the browser builder for projects that require:

• Existing webpack configurations
• Specific webpack loaders and plugins
• Complex module resolution rules

Modern Applications

Use the application builder for new projects that benefit from:

• Fast build times with esbuild
• Custom build optimizations
• Modern JavaScript features

Development Workflow

Use dev-server builders for enhanced development:

• Custom authentication middleware
• API proxying
• Performance monitoring
• Hot module replacement

🔗 Dependencies

• @angular-devkit/architect - Angular CLI builder framework
• @angular/build - Angular build system
• @angular-devkit/core - Core Angular utilities
• webpack-merge - Webpack configuration merging
• lodash - Utility functions
• @angular-builders/common - Common builder utilities

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Angular CLI team for the excellent build system
• Community contributors for feedback and improvements
• All users who help make this project better

Built with ❤️ by the Salt NGX team