@razerspine/build 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Razerspine
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# @razerspine/build
+
+[![npm version](https://img.shields.io/npm/v/@razerspine/build.svg)](https://www.npmjs.com/package/@razerspine/build)
+[![Vitest](https://img.shields.io/badge/Vitest-92_passed-success?logo=vitest)](#)
+[![changelog](https://img.shields.io/badge/docs-changelog-blue.svg)](./CHANGELOG.md)
+[![license](https://img.shields.io/npm/l/@razerspine/build.svg)](./LICENSE)
+
+A scalable, modular, and highly extensible Webpack build system. Whether you are building template-driven MPA websites (
+Pug/HTML) or modern SPA applications (React), `@razerspine/build` provides a zero-hassle, production-ready foundation
+with smart auto-hosting capabilities.
+
+---
+
+## Table of Contents
+
+- [Key Features](#-key-features)
+- [Installation](#-installation)
+- [Usage (`defineConfig`)](#-usage)
+- [React Preset (Beta)](#-react-preset-beta)
+- [Application Modes (SPA/MPA)](#-application-modes)
+- [Template Engines](#-template-engines)
+- [Extensibility (Hooks & Plugins)](#-extensibility)
+- [Smart Hosting Adapter](#-smart-hosting-adapter)
+- [Architecture Principles](#-architecture-principles)
+- [Requirements](#-requirements)
+- [License](#-license)
+
+---
+
+## 🚀 Key Features
+
+- **New `defineConfig` API**: Single entry point for configuration with automatic mode-based resolution.
+- **Multi-Engine Templates**: Built-in support for `pug`, `html`, or `none`.
+- **React Support (Beta)**: DX with Fast Refresh and Babel pipeline via `reactPreset`.
+- **Hybrid Architectures**: Seamlessly switch between Multi-page (MPA) and Single-page (SPA) modes.
+- **Smart Auto-Hosting**: Automatically detects **Vercel, Netlify, Cloudflare**, and **GitHub Pages** to generate
+  required routing configs.
+- **Enhanced DX**: Recursive file watching (`src/**/*`), automatic browser opening, and detailed infrastructure logging.
+- **Build Plugins Lifecycle**: Extend the build process safely using `setup`, `applyBase`, `applyDev`, and `applyProd`
+  hooks.
+- **Rock Solid**: Covered by 90+ Unit, Integration, E2E, and Snapshot tests.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -D @razerspine/build
+```
+
+---
+
+## 📖 Usage
+
+Creating a Webpack config is now incredibly simple thanks to the `defineConfig` helper.
+It automatically handles `development` and `production` modes.
+
+### Basic Setup (Static)
+
+Create a `webpack.config.js`:
+
+```js
+const {defineConfig} = require('@razerspine/build');
+
+module.exports = defineConfig({
+  appType: 'spa', // 'spa' or 'mpa'
+  scripts: 'ts',  // 'ts' or 'js'
+  styles: 'scss', // 'scss' or 'less'
+  templates: {
+    type: 'pug',
+    entry: 'src/app/app.pug',
+  },
+});
+```
+
+### Dynamic & Async Configuration
+
+You can pass a function to `defineConfig` to access the current mode or fetch async data:
+
+```js
+const {defineConfig} = require('@razerspine/build');
+
+module.exports = defineConfig(async ({mode}) => {
+  return {
+    mode,
+    scripts: 'ts',
+    styles: 'scss',
+    // Options...
+  };
+});
+```
+
+---
+
+## ⚛️ React Preset (Beta)
+
+We've introduced a powerful React preset built on top of the new Build Plugins system.
+It provides a modern developer experience out of the box.
+
+**Features**: Babel pipeline, React Fast Refresh, automatic JSX runtime, and safe deduplication.
+
+### 1. Install Peer Dependencies
+
+```bash
+npm install -D babel-loader @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript @pmmmwh/react-refresh-webpack-plugin react-refresh
+```
+
+### 2. Update Configuration
+
+```js
+const {defineConfig, reactPreset} = require('@razerspine/build');
+
+module.exports = defineConfig({
+  scripts: 'ts',
+  styles: 'scss',
+  templates: {
+    type: 'none', // Handle templates manually or disable for raw React builds
+  },
+  presets: [
+    reactPreset()
+  ]
+});
+```
+
+---
+
+## 🛠 Application Modes
+
+Configure how your application structure is processed using the `appType` option.
+
+### MPA (Default)
+
+`appType: 'mpa'`
+
+- `templates.entry` must be a directory (e.g., `src/views/pages`).
+- Each file in the directory generates its own HTML file.
+
+### SPA
+
+`appType: 'spa'`
+
+- `templates.entry` must be a single file (e.g., `src/app/app.pug` or `index.html`).
+- Always outputs `index.html`.
+- Enables automatic SPA fallback routing (`404.html`) for static hosts.
+
+---
+
+## 📄 Template Engines
+
+You can now explicitly control template processing via `templates.type`:
+
+- `pug` (Default): Uses `PugTemplatesPlugin`. Dual-mode support (compiles components for JS imports, renders static HTML
+  for entries).
+- `html`: Uses `HtmlTemplatesPlugin` (wrapper around `html-webpack-plugin`).
+- `none`: Disables template handling entirely (useful for custom setups or pure JS/React builds).
+
+---
+
+## 🔌 Extensibility
+
+### Extending Rules & Plugins
+
+You can safely extend or override internal Webpack rules and plugins without breaking the core:
+
+```js
+module.exports = defineConfig({
+  // ...
+  rules: {
+    extend: [ /* your custom RuleSetRule */],
+  },
+  plugins: {
+    extend: [ /* your custom WebpackPluginInstance */],
+  }
+});
+```
+
+### Build Plugins System (Lifecycle Hooks)
+
+For advanced use cases or framework integrations, use the new internal plugin system:
+
+```js
+module.exports = defineConfig({
+  buildPlugins: [
+    {
+      setup(ctx) { /* run before config creation */
+      },
+      applyBase(config) { /* mutate base config object safely */
+      },
+      applyDev(config) { /* dev-only overrides */
+      },
+      applyProd(config) { /* prod-only overrides */
+      }
+    }
+  ]
+});
+```
+
+---
+
+## 🌍 Smart Hosting Adapter
+
+The core automatically detects your CI/CD environment during the production build and emits necessary routing
+configurations in-memory.
+
+| Platform                 | Generated File | Purpose                                                                  |
+|:-------------------------|:---------------|:-------------------------------------------------------------------------|
+| **Netlify / Cloudflare** | `_redirects`   | Handles SPA rewrites and MPA fallbacks.                                  |
+| **Vercel**               | `vercel.json`  | Configures Vercel Edge Network routing based on `appType`.               |
+| **GitHub Pages**         | `404.html`     | Duplicates `index.html` to prevent 404 errors on deep links in SPA mode. |
+| **Static / Others**      | `404.html`     | Generic fallback for SPA mode.                                           |
+
+---
+
+## 🏗 Architecture Principles
+
+- **Template-First**: While Webpack handles assets, templates (Pug/HTML) drive the entry points.
+- **Stability-First**: Aggressive optimizations (like `splitChunks`) are carefully tuned or disabled by default to
+  ensure reliable asset resolution within templates.
+- **Type Safety**: Built with TypeScript for excellent IDE support and internal build reliability.
+
+---
+
+## ⚠️ Requirements
+
+- **Node.js**: v20.0.0 or higher
+- **Webpack**: v5.0.0 or higher
+
+---
+
+## 📄 License
+
+This project is licensed under the ISC License.

package/dist/core/config-meta.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module config-meta
+ * @description Utilities for managing Webpack configuration metadata.
+ * Uses a WeakMap to associate extra properties with a configuration object
+ * without causing memory leaks.
+ */
+import { Configuration } from 'webpack';
+import { AppType, BuildPluginType } from '../types';
+/**
+ * Metadata structure for the Webpack configuration.
+ */
+type ConfigMeta = {
+    /** The application architecture: 'spa' (Single Page Application) or 'mpa' (Multi Page Application) */
+    appType: AppType;
+    /**
+     * Internal build plugins (framework-level extensions)
+     * Used for lifecycle hooks across base/dev/prod configs.
+     */
+    buildPlugins?: BuildPluginType[];
+};
+/**
+ * Associates metadata with a specific Webpack configuration object.
+ * @param {Configuration} config - The Webpack configuration object to tag.
+ * @param {ConfigMeta} meta - The metadata to store.
+ */
+export declare function setConfigMeta(config: Configuration, meta: ConfigMeta): void;
+/**
+ * Retrieves metadata associated with a Webpack configuration object.
+ * @param {Configuration} config - The Webpack configuration object.
+ * @returns {ConfigMeta | undefined} The stored metadata or undefined if not found.
+ */
+export declare function getConfigMeta(config: Configuration): ConfigMeta | undefined;
+export {};

package/dist/core/config-meta.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * @module config-meta
+ * @description Utilities for managing Webpack configuration metadata.
+ * Uses a WeakMap to associate extra properties with a configuration object
+ * without causing memory leaks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setConfigMeta = setConfigMeta;
+exports.getConfigMeta = getConfigMeta;
+const configMeta = new WeakMap();
+/**
+ * Associates metadata with a specific Webpack configuration object.
+ * @param {Configuration} config - The Webpack configuration object to tag.
+ * @param {ConfigMeta} meta - The metadata to store.
+ */
+function setConfigMeta(config, meta) {
+    configMeta.set(config, meta);
+}
+/**
+ * Retrieves metadata associated with a Webpack configuration object.
+ * @param {Configuration} config - The Webpack configuration object.
+ * @returns {ConfigMeta | undefined} The stored metadata or undefined if not found.
+ */
+function getConfigMeta(config) {
+    return configMeta.get(config);
+}

package/dist/core/create-base-config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module create-base-config
+ * @description Generates the base Webpack configuration shared across development and production.
+ */
+import { ConfigOptionType } from '../types';
+import { Configuration } from 'webpack';
+/**
+ * Creates a base Webpack configuration object.
+ * Also initializes internal metadata (appType) for use in dev/prod overrides.
+ *
+ * Supports controlled extension/override of internal rules and plugins.
+ *
+ * ---
+ * Template system:
+ *
+ * The build system supports multiple template engines via `templates.type`:
+ *
+ * - `pug`  → uses PugTemplatesPlugin (default)
+ * - `html` → uses HtmlTemplatesPlugin
+ * - `none` → disables template handling (React/Vue/custom setups)
+ *
+ * This allows flexible integration with different rendering strategies.
+ *
+ * ---
+ * Rules system:
+ *
+ * Internal rules pipeline:
+ * - assets
+ * - scripts (js/ts)
+ * - styles (scss/less)
+ * - pug (only when enabled)
+ *
+ * Users can:
+ * - extend rules safely (`rules.extend`)
+ * - fully override rules (`rules.override`)
+ *
+ * ---
+ * 🔌 Plugins system:
+ *
+ * Internal plugins are conditionally applied based on template type.
+ *
+ * Users can:
+ * - extend plugins (`plugins.extend`)
+ * - override plugins completely (`plugins.override`)
+ *
+ * ⚠️ Override should be used with caution — it disables all internal plugins.
+ *
+ * ---
+ * @param {ConfigOptionType} options - User-provided options for the build system.
+ * @returns {Configuration} The generated base Webpack configuration.
+ */
+export declare function createBaseConfig(options: ConfigOptionType): Configuration;

package/dist/core/create-base-config.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * @module create-base-config
+ * @description Generates the base Webpack configuration shared across development and production.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBaseConfig = createBaseConfig;
+const config_meta_1 = require("./config-meta");
+const options_1 = require("../options");
+const path_1 = __importDefault(require("path"));
+const rules_1 = require("../rules");
+const pug_templates_plugin_1 = require("../plugins/pug-templates-plugin");
+const html_templates_plugin_1 = require("../plugins/html-templates-plugin");
+const utils_1 = require("../utils");
+/**
+ * Creates a base Webpack configuration object.
+ * Also initializes internal metadata (appType) for use in dev/prod overrides.
+ *
+ * Supports controlled extension/override of internal rules and plugins.
+ *
+ * ---
+ * Template system:
+ *
+ * The build system supports multiple template engines via `templates.type`:
+ *
+ * - `pug`  → uses PugTemplatesPlugin (default)
+ * - `html` → uses HtmlTemplatesPlugin
+ * - `none` → disables template handling (React/Vue/custom setups)
+ *
+ * This allows flexible integration with different rendering strategies.
+ *
+ * ---
+ * Rules system:
+ *
+ * Internal rules pipeline:
+ * - assets
+ * - scripts (js/ts)
+ * - styles (scss/less)
+ * - pug (only when enabled)
+ *
+ * Users can:
+ * - extend rules safely (`rules.extend`)
+ * - fully override rules (`rules.override`)
+ *
+ * ---
+ * 🔌 Plugins system:
+ *
+ * Internal plugins are conditionally applied based on template type.
+ *
+ * Users can:
+ * - extend plugins (`plugins.extend`)
+ * - override plugins completely (`plugins.override`)
+ *
+ * ⚠️ Override should be used with caution — it disables all internal plugins.
+ *
+ * ---
+ * @param {ConfigOptionType} options - User-provided options for the build system.
+ * @returns {Configuration} The generated base Webpack configuration.
+ */
+function createBaseConfig(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const normalized = (0, options_1.resolveOptions)(options);
+    const templateType = (_b = (_a = normalized.templates) === null || _a === void 0 ? void 0 : _a.type) !== null && _b !== void 0 ? _b : 'pug';
+    /**
+     * Rules (core pipeline)
+     */
+    let rules = [
+        (0, rules_1.assetsRule)(),
+        (0, rules_1.scriptsRule)(normalized),
+        (0, rules_1.stylesRule)(normalized),
+    ];
+    /**
+     * Conditionally enable pug processing
+     */
+    if (templateType === 'pug') {
+        rules.unshift((0, rules_1.pugRule)());
+    }
+    /**
+     * Apply user rules overrides/extensions
+     */
+    if ((_c = options.rules) === null || _c === void 0 ? void 0 : _c.override) {
+        rules = options.rules.override;
+    }
+    else if ((_d = options.rules) === null || _d === void 0 ? void 0 : _d.extend) {
+        rules.push(...options.rules.extend);
+    }
+    /**
+     * Plugins (core pipeline)
+     */
+    let plugins = [];
+    /**
+     * PUG templates support
+     */
+    if (templateType === 'pug') {
+        if (!normalized.templates.entry) {
+            throw new Error('[build] templates.entry is required when templates.type is "pug"');
+        }
+        plugins.push(new pug_templates_plugin_1.PugTemplatesPlugin({
+            entry: normalized.templates.entry,
+            mode: normalized.mode,
+            appType: normalized.appType,
+        }));
+    }
+    /**
+     * HTML templates support (HtmlWebpackPlugin wrapper)
+     */
+    if (templateType === 'html') {
+        if (!normalized.templates.entry) {
+            throw new Error('[build] templates.entry is required when templates.type is "html"');
+        }
+        plugins.push(new html_templates_plugin_1.HtmlTemplatesPlugin({
+            entry: normalized.templates.entry,
+            mode: normalized.mode,
+            appType: normalized.appType,
+        }));
+    }
+    /**
+     * Apply user plugins overrides/extensions
+     */
+    if ((_e = options.plugins) === null || _e === void 0 ? void 0 : _e.override) {
+        plugins = options.plugins.override;
+    }
+    else if ((_f = options.plugins) === null || _f === void 0 ? void 0 : _f.extend) {
+        plugins.push(...options.plugins.extend);
+    }
+    const config = {
+        mode: normalized.mode,
+        context: process.cwd(),
+        output: {
+            path: path_1.default.join(process.cwd(), 'dist'),
+            clean: true,
+        },
+        module: {
+            rules,
+        },
+        plugins: (0, utils_1.dedupePlugins)(plugins),
+        resolve: {
+            extensions: ['.ts', '.tsx', '.js', '.json'],
+            alias: normalized.resolve.alias,
+        },
+    };
+    /**
+     * Build Plugins (lifecycle)
+     *
+     * These are NOT webpack plugins.
+     * They are internal framework plugins used to extend config behavior.
+     */
+    const buildPlugins = (_g = options.buildPlugins) !== null && _g !== void 0 ? _g : [];
+    // Run setup phase
+    for (const plugin of buildPlugins) {
+        (_h = plugin.setup) === null || _h === void 0 ? void 0 : _h.call(plugin, { options: normalized });
+    }
+    // Apply base config hooks
+    for (const plugin of buildPlugins) {
+        (_j = plugin.applyBase) === null || _j === void 0 ? void 0 : _j.call(plugin, config);
+    }
+    /**
+     * Re-dedupe rules after buildPlugins mutations
+     */
+    if ((_k = config.module) === null || _k === void 0 ? void 0 : _k.rules) {
+        config.module.rules = (0, utils_1.dedupeRules)(config.module.rules);
+    }
+    /**
+     * Re-dedupe plugins after buildPlugins mutations
+     */
+    if (config.plugins) {
+        config.plugins = (0, utils_1.dedupePlugins)(config.plugins);
+    }
+    /**
+     * Store metadata (appType + buildPlugins)
+     */
+    (0, config_meta_1.setConfigMeta)(config, {
+        appType: normalized.appType,
+        buildPlugins,
+    });
+    return config;
+}

package/dist/core/create-dev-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @module create-dev-config
+ * @description Extends the base configuration with Webpack Dev Server settings.
+ */
+import type { Configuration as DevServerConfiguration } from 'webpack-dev-server';
+import { BaseWebpackConfigType } from '../types';
+type DevConfig = BaseWebpackConfigType & {
+    devServer?: DevServerConfiguration;
+};
+/**
+ * Creates a development configuration by merging base settings with DevServer options.
+ * Automatically configures routing fallbacks based on whether the app is SPA or MPA.
+ * @param {BaseWebpackConfigType} baseConfig - The base configuration from createBaseConfig.
+ * @param {DevServerConfiguration} [options={}] - Optional DevServer overrides.
+ * @returns {DevConfig} The final development configuration.
+ */
+export declare function createDevConfig(baseConfig: BaseWebpackConfigType, options?: DevServerConfiguration): DevConfig;
+export {};

package/dist/core/create-dev-config.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * @module create-dev-config
+ * @description Extends the base configuration with Webpack Dev Server settings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDevConfig = createDevConfig;
+const webpack_merge_1 = require("webpack-merge");
+const config_meta_1 = require("./config-meta");
+const dedupe_plugins_1 = require("../utils/dedupe-plugins");
+/**
+ * Creates a development configuration by merging base settings with DevServer options.
+ * Automatically configures routing fallbacks based on whether the app is SPA or MPA.
+ * @param {BaseWebpackConfigType} baseConfig - The base configuration from createBaseConfig.
+ * @param {DevServerConfiguration} [options={}] - Optional DevServer overrides.
+ * @returns {DevConfig} The final development configuration.
+ */
+function createDevConfig(baseConfig, options = {}) {
+    var _a, _b;
+    const meta = (0, config_meta_1.getConfigMeta)(baseConfig);
+    const appType = (_a = meta === null || meta === void 0 ? void 0 : meta.appType) !== null && _a !== void 0 ? _a : 'mpa';
+    /** Default dev server settings */
+    const baseDevServer = {
+        hot: false,
+        open: true,
+        liveReload: true,
+        compress: true,
+        port: 8080,
+        watchFiles: ['src/**/*'],
+    };
+    /** Fallback logic: SPA redirects to index, MPA redirects to 404 */
+    const defaultFallbackConfig = {
+        historyApiFallback: {
+            disableDotRule: true,
+            rewrites: [
+                {
+                    from: /./,
+                    to: appType === 'spa' ? '/index.html' : '/404.html',
+                }
+            ]
+        }
+    };
+    // Use default fallbacks unless the user provided their own historyApiFallback config
+    const fallbackToMerge = options.historyApiFallback !== undefined
+        ? {}
+        : defaultFallbackConfig;
+    const resultDevServer = (0, webpack_merge_1.merge)(baseDevServer, fallbackToMerge, options);
+    const finalConfig = (0, webpack_merge_1.merge)(baseConfig, {
+        devtool: 'source-map',
+        devServer: resultDevServer,
+    });
+    /**
+     * Build Plugins (dev lifecycle)
+     */
+    const metaWithPlugins = (0, config_meta_1.getConfigMeta)(baseConfig);
+    if (metaWithPlugins === null || metaWithPlugins === void 0 ? void 0 : metaWithPlugins.buildPlugins) {
+        for (const plugin of metaWithPlugins.buildPlugins) {
+            (_b = plugin.applyDev) === null || _b === void 0 ? void 0 : _b.call(plugin, finalConfig);
+        }
+    }
+    /**
+     * Re-dedupe plugins after merge and buildPlugins mutations
+     */
+    if (finalConfig.plugins) {
+        finalConfig.plugins = (0, dedupe_plugins_1.dedupePlugins)(finalConfig.plugins);
+    }
+    return finalConfig;
+}

package/dist/core/create-prod-config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module create-prod-config
+ * @description Finalizes the configuration for production builds with optimizations.
+ */
+import { Configuration } from 'webpack';
+/**
+ * Creates a production configuration with minification and hosting-specific plugins.
+ * @param {Configuration} baseConfig - The base configuration from createBaseConfig.
+ * @param {Configuration} [options={}] - Additional Webpack overrides for production.
+ * @returns {Configuration} The optimized production configuration.
+ */
+export declare function createProdConfig(baseConfig: Configuration, options?: Configuration): Configuration;