@razerspine/webpack-core 1.2.0 → 1.2.3

package/CHANGELOG.md

@@ -8,31 +8,78 @@ required to ensure correct behavior in both development and production modes.
 
 ---
 
+## [1.2.3] - 2026-02-17
+
+### Added
+
+- **Validation Layer**: Introduced `validateCoreOptions()` inside `createBaseConfig`.
+  - Validates `mode`, `scripts`, and `styles` values.
+  - Ensures the templates entry directory exists before Webpack initialization.
+  - Prevents silent runtime failures in pug-plugin due to invalid configuration.
+
+### Changed
+
+- **Dev Server Default Behavior**: Enabled `open: true` in default `devServer` configuration.
+  - Development server now automatically opens the browser.
+  - Improves developer experience for starter templates.
+
+### Notes
+
+- This release does **not introduce breaking changes**.
+- Public API remains unchanged.
+- Existing templates continue to work without modification.
+
+---
+
+## [1.2.1] - 2026-02-12
+
+### Added
+
+- **Flexible Configurations:** Added an optional `options` argument to both `createDevConfig` and `createProdConfig`.
+- Users can now override default `devServer` settings or Webpack production optimizations without losing the base
+  functionality.
+- Integrated `webpack-merge` into `createDevConfig` for safer property merging.
+
+### Fixed
+
+- Updated internal documentation and clarified version history in `CHANGELOG.md`.
+
+---
+
 ## [1.2.0] - 2026-02-12
 
 ### Changed
-- **Enhanced File Watching:** Updated `createDevConfig` to watch all files recursively in the `src/` directory (`src/**/*`). This ensures `webpack-dev-server` reacts to changes in any file type (images, JSON, new assets) without manual configuration.
+
+- **Enhanced File Watching:** Updated `createDevConfig` to watch all files recursively in the `src/` directory (
+  `src/**/*`). This ensures `webpack-dev-server` reacts to changes in any file type (images, JSON, new assets) without
+  manual configuration.
 - **Improved Dev Routing:** Configured `historyApiFallback` in development mode.
   - Set `disableDotRule: true` to allow dots in URLs (useful for complex routing).
-  - Added a global rewrite rule to serve `/404.html` for any non-existent paths, enabling better local testing of 404 error pages and SPA-like navigation.
-- **DevServer Optimization:** Set `hot: false` and `liveReload: true` as a stable default for multi-page template builds to ensure consistent page refreshes upon file changes.
+  - Added a global rewrite rule to serve `/404.html` for any non-existent paths, enabling better local testing of 404
+    error pages and SPA-like navigation.
+- **DevServer Optimization:** Set `hot: false` and `liveReload: true` as a stable default for multi-page template builds
+  to ensure consistent page refreshes upon file changes.
 
 ---
 
 ## [1.1.7] - 2026-02-11
 
 ### Changed
+
 - Updated `README.md`
 - Updated `package.json` metadata (keywords, published files)
 
 ### Stable Release Note
-- **Important:** Versions prior to 1.1.6 were part of a stabilization phase and are not recommended for production use. This release marks the stable baseline.
+
+- **Important:** Versions prior to 1.1.6 were part of a stabilization phase and are not recommended for production use.
+  This release marks the stable baseline.
 
 ---
 
 ## [1.1.6] - 2026-02-05
 
 ### Changed
+
 - Updated `package.json` metadata (keywords, published files)
 - Updated `README.md`
 
@@ -41,12 +88,14 @@ required to ensure correct behavior in both development and production modes.
 ## [1.1.5] - 2026-02-05
 
 ### Fixed
+
 - Stabilized production webpack configuration for pug-plugin driven builds
 - Disabled `splitChunks` and `runtimeChunk` to prevent asset resolution issues
 - Ensured predictable output structure in production mode
 - Reduced risk of entry-related build failures
 
 ### Notes
+
 - This release finalizes the stabilization phase of the production configuration
 - Recommended as a stable baseline for template usage
 
@@ -55,6 +104,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.1.4] - 2026-02-05
 
 ### Fixed
+
 - Final stabilization of production configuration
 - Ensured consistent build behavior for pug-plugin driven templates
 
@@ -63,6 +113,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.1.0 – 1.1.3] - 2026-02-05
 
 ### Fixed
+
 - Multiple fixes for production configuration edge cases
 - Improved compatibility between pug-plugin, assets loader, and webpack optimization
 - Stabilized production builds for template-driven entry points
@@ -72,6 +123,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.9] - 2026-02-05
 
 ### Fixed
+
 - Removed implicit webpack entry from production config
 - Fixed production build failure caused by default webpack entry resolution
 
@@ -80,6 +132,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.8] - 2026-02-05
 
 ### Fixed
+
 - Fixed `resolve.alias` handling across loaders and pug-plugin
 
 ---
@@ -87,6 +140,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.7] - 2026-02-05
 
 ### Fixed
+
 - Fixed Pug asset resolution in production mode
 - Passed webpack `resolve.alias` into pug-plugin resolver
 - Ensured consistent alias behavior in development and production
@@ -96,6 +150,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.6] - 2026-02-05
 
 ### Fixed
+
 - Fixed webpack plugin instance mismatch when used via `npm link`
 - Moved `webpack-dev-server` and `pug-plugin` to `peerDependencies`
 - Ensured a single webpack instance is used in consumer templates
@@ -105,6 +160,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.5] - 2026-02-04
 
 ### Fixed
+
 - Explicitly disabled webpack default entry (`./src`)
 - Ensured stable behavior when using pug-plugin as the primary entry system
 
@@ -113,6 +169,7 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.4] - 2026-02-04
 
 ### Fixed
+
 - Fixed TypeScript typing for `webpack-dev-server`
 - Properly extended webpack Configuration with devServer types
 
@@ -121,11 +178,13 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.3] - 2026-02-04
 
 ### Fixed
+
 - Fixed webpack default entry fallback (`./src`)
 - Prevented webpack from resolving non-existing JS entry when using pug-plugin
 - Stabilized template entry handling via `templatesLoader`
 
 ### Internal
+
 - Clarified responsibility between webpack entry and pug-plugin entry
 
 ---
@@ -133,9 +192,12 @@ required to ensure correct behavior in both development and production modes.
 ## [1.0.2] - 2026-02-04
 
 ### Fixed
+
 - Fixed ENV mode option typing
 - Stabilized base configuration behavior
 
 ## [Unreleased]
+
 ### Changed
+
 - Updated README.md

package/README.md

@@ -12,8 +12,9 @@ template-driven builds using `pug-plugin`.
 Versions prior to 1.1.6 were part of a stabilization phase and are not recommended for production use.
 
 Please use:
+
 ```bash
-npm install @razerspine/webpack-core@^1.1.6
+npm install @razerspine/webpack-core@^1.2.1
 ```
 
 ## Designed for
@@ -28,35 +29,40 @@ templates, but can also be used independently.
 
 ## Design principles
 
-- Webpack is responsible for:
-  - module resolution
-  - aliases (`resolve.alias`)
-  - asset handling
-
-- Loaders and plugins:
-  - do not define aliases
-  - do not depend on UI kits
-  - do not assume project structure
+- **Webpack is responsible for**: module resolution, aliases (`resolve.alias`), and asset handling.
+- **Flexibility:** Since v1.2.1, you can override any part of the dev or prod configuration using an optional `options`
+  argument.
+- **Stability:** `pug-plugin` is used to compile templates, and asset paths are resolved by webpack.
+- **Template-driven**: Webpack JS entry is intentionally disabled. Builds are driven by template entries in
+  `src/views/pages`.
+- **Sensible Defaults**: No aggressive production optimizations (like `splitChunks`) are enabled by default to prevent
+  asset resolution issues in templates.
+- **Validated configuration layer (v1.2.2+)**: Core options are validated before build initialization to prevent silent
+  runtime failures.
 
-- `pug-plugin` is used only to compile templates  
-  Asset paths are resolved by webpack.
+---
 
-- Webpack JS entry is intentionally disabled  
-  Builds are driven by template entries.
+## Features
 
-- No aggressive production optimizations by default  
-  (e.g. no `splitChunks`)
+- **Pug templates support** with auto-discovery.
+- **JavaScript / TypeScript** integration.
+- **SCSS / Less** styling support.
+- **Recursive File Watching**: Dev server watches all changes in `src/**/*`.
+- **SPA-friendly Dev Server**: Integrated historyApiFallback (redirects to 404.html).
+- **Customizable**: Easily override devServer or optimization settings.
+- **Configuration validation layer**
+- **Automatic browser open in development (v1.2.2+)**
 
 ---
 
-## Features
+## What’s New in v1.2.2
+
+- Added `validateCoreOptions()` inside `createBaseConfig`
+  - Validates `mode`, `scripts`, and `styles`
+  - Ensures templates entry directory exists before Webpack starts
+- Dev server now opens the browser automatically (`open: true` by default)
 
-- Pug templates support
-- JavaScript / TypeScript
-- SCSS / Less
-- Environment-aware configuration
-- No hardcoded aliases
-- Production-safe defaults
+> No breaking changes were introduced.
 
 ---
 
@@ -70,6 +76,8 @@ npm install @razerspine/webpack-core
 
 ## Usage
 
+### Basic Setup
+
 ```js
 const path = require('path');
 const {
@@ -83,8 +91,8 @@ module.exports = (env = {}, argv = {}) => {
 
   const baseConfig = createBaseConfig({
     mode,
-    scripts: 'js',
-    styles: 'less',
+    scripts: 'js', // or 'ts'
+    styles: 'scss', // or 'less'
     templates: {
       entry: 'src/views/pages',
     },
@@ -92,19 +100,76 @@ module.exports = (env = {}, argv = {}) => {
       alias: {
         '@views': path.resolve(process.cwd(), 'src/views'),
         '@styles': path.resolve(process.cwd(), 'src/assets/styles'),
-        '@scripts': path.resolve(process.cwd(), 'src/assets/scripts'),
-        '@images': path.resolve(process.cwd(), 'src/assets/images'),
       },
     },
   });
 
-  return mode === 'development'
-    ? createDevConfig(baseConfig)
-    : createProdConfig(baseConfig);
+  if (mode === 'development') {
+    return createDevConfig(baseConfig);
+  }
+
+  return createProdConfig(baseConfig);
 };
 ```
 
+### Customizing Configuration (v1.2.1+)
+
+You can now pass an optional second argument to `createDevConfig` and `createProdConfig` to override defaults:
+
+```js
+// Customizing the Dev Server (port, open browser, etc.)
+if (mode === 'development') {
+  return createDevConfig(baseConfig, {
+    port: 3000,
+    open: true,
+    // extra devServer options...
+  });
+}
+
+// Customizing Production (minification, performance hints, etc.)
+if (mode === 'production') {
+  return createProdConfig(baseConfig, {
+    performance: {
+      hints: 'warning',
+    }
+  });
+}
+```
+
 ---
 
+## API Reference
+
+`createBaseConfig(options)`
+
+Core configuration factory.
+
+**Options include**:
+
+- `mode` — `'development' | 'production'`
+- `scripts` — `'js' | 'ts'`
+- `styles` — `'scss' | 'less'`
+- `templates.entry` — Path to template pages directory
+- `resolve.alias` — Webpack aliases
+
+All options are validated before initialization.
+
+---
+
+`createDevConfig(baseConfig, options?)`
+
+- `baseConfig`: The configuration returned by createBaseConfig.
+- `options`: (Optional) webpack-dev-server configuration object.
+- **Default behavior**: Watches `src/**/*`, uses port `8080`, and rewrites 404s to `/404.html`.
+
+---
+
+`createProdConfig(baseConfig, options?)`
+
+- `baseConfig`: The configuration returned by createBaseConfig.
+- `options`: (Optional) Webpack configuration object for production overrides.
+- **Default behavior**: Enables source maps, minification, and disables `splitChunks` for template compatibility.
+
 ## 📄 License
+
 This project is licensed under the ISC License.

package/dist/config/base.js

@@ -9,8 +9,10 @@ const scripts_1 = require("../loaders/scripts");
 const styles_1 = require("../loaders/styles");
 const templates_1 = require("../loaders/templates");
 const path_1 = __importDefault(require("path"));
+const validate_core_options_1 = require("../validation/validate-core-options");
 function createBaseConfig(options) {
     var _a, _b, _c, _d;
+    (0, validate_core_options_1.validateCoreOptions)(options);
     const mode = (_a = options.mode) !== null && _a !== void 0 ? _a : 'development';
     return {
         mode,

package/dist/config/dev.d.ts

@@ -3,5 +3,5 @@ import type { Configuration as DevServerConfiguration } from 'webpack-dev-server
 type DevConfig = WebpackConfiguration & {
     devServer?: DevServerConfiguration;
 };
-export declare function createDevConfig(baseConfig: WebpackConfiguration): DevConfig;
+export declare function createDevConfig(baseConfig: WebpackConfiguration, options?: DevServerConfiguration): DevConfig;
 export {};

package/dist/config/dev.js

@@ -1,24 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDevConfig = createDevConfig;
-function createDevConfig(baseConfig) {
-    return {
-        ...baseConfig,
-        devtool: 'source-map',
-        devServer: {
-            hot: false,
-            liveReload: true,
-            compress: true,
-            port: 8080,
-            watchFiles: [
-                'src/**/*',
-            ],
-            historyApiFallback: {
-                disableDotRule: true,
-                rewrites: [
-                    { from: /./, to: '/404.html' }
-                ]
-            }
+const webpack_merge_1 = require("webpack-merge");
+function createDevConfig(baseConfig, options = {}) {
+    const defaultDevServer = {
+        hot: false,
+        open: true,
+        liveReload: true,
+        compress: true,
+        port: 8080,
+        watchFiles: ['src/**/*'],
+        historyApiFallback: {
+            disableDotRule: true,
+            rewrites: [{ from: /./, to: '/404.html' }]
         }
     };
+    return (0, webpack_merge_1.merge)(baseConfig, {
+        devtool: 'source-map',
+        devServer: (0, webpack_merge_1.merge)(defaultDevServer, options)
+    });
 }

package/dist/config/prod.d.ts

@@ -1,2 +1,2 @@
 import type { Configuration } from 'webpack';
-export declare function createProdConfig(baseConfig: Configuration): Configuration;
+export declare function createProdConfig(baseConfig: Configuration, options?: Configuration): Configuration;

package/dist/config/prod.js

@@ -2,18 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createProdConfig = createProdConfig;
 const webpack_merge_1 = require("webpack-merge");
-function createProdConfig(baseConfig) {
-    return (0, webpack_merge_1.merge)(baseConfig, {
+function createProdConfig(baseConfig, options = {}) {
+    const defaultConfig = {
         devtool: 'source-map',
         optimization: {
             minimize: true,
-            // ⚠️ splitChunks deliberately disabled
-            // pug-plugin manages assets & entries itself
             splitChunks: false,
             runtimeChunk: false,
         },
         performance: {
             hints: false,
         },
-    });
+    };
+    return (0, webpack_merge_1.merge)(baseConfig, defaultConfig, options);
 }

package/dist/validation/validate-core-options.d.ts

@@ -0,0 +1,2 @@
+import { ConfigOptionType } from '../types/config-option-type';
+export declare function validateCoreOptions(options: ConfigOptionType): void;

package/dist/validation/validate-core-options.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCoreOptions = validateCoreOptions;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function validateCoreOptions(options) {
+    var _a, _b;
+    if (!options) {
+        throw new Error('[webpack-core] Options are required.');
+    }
+    const { mode, scripts, styles } = options;
+    // --- mode
+    if (!['development', 'production'].includes(mode)) {
+        throw new Error(`[webpack-core] Invalid mode "${mode}". Expected "development" or "production".`);
+    }
+    // --- scripts
+    if (!['js', 'ts'].includes(scripts)) {
+        throw new Error(`[webpack-core] Invalid scripts option "${scripts}". Expected "js" or "ts".`);
+    }
+    // --- styles
+    if (!['scss', 'less'].includes(styles)) {
+        throw new Error(`[webpack-core] Invalid styles option "${styles}". Expected "scss" or "less".`);
+    }
+    // --- templates entry
+    const entryRelative = (_b = (_a = options.templates) === null || _a === void 0 ? void 0 : _a.entry) !== null && _b !== void 0 ? _b : 'src/views/pages';
+    const entryAbsolute = path_1.default.resolve(process.cwd(), entryRelative);
+    if (!fs_1.default.existsSync(entryAbsolute)) {
+        throw new Error(`[webpack-core] Templates entry directory does not exist: ${entryAbsolute}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@razerspine/webpack-core",
-  "version": "1.2.0",
+  "version": "1.2.3",
   "description": "Core webpack config and loaders for starter templates",
   "keywords": [
     "webpack",