@razerspine/webpack-core 1.4.1 → 1.7.1

package/CHANGELOG.md

@@ -8,6 +8,54 @@ required to ensure correct behavior in both development and production modes.
 
 ---
 
+## [1.7.0] - 2026-02-20
+
+### Added
+
+- **SPA Support (Experimental Stable API)**
+  - Introduced new `appType` option: `'mpa' | 'spa'`
+  - `mpa` remains the default mode (template directory driven)
+  - `spa` mode supports a single Pug entry file and outputs `index.html`
+  - Enables SPA-style projects while preserving template-driven architecture
+
+- **Options Normalization Layer**
+  - Introduced `normalizeCoreOptions()` (internal utility)
+  - Centralized default resolution for:
+    - `mode`
+    - `appType`
+    - `templates.entry`
+    - `resolve.alias`
+  - Eliminates duplicated fallback logic across config layers
+  - Establishes a single source of truth for configuration defaults
+
+- **Improved Templates Validation**
+  - Validation logic now differentiates between:
+    - Directory entry (MPA)
+    - Single file entry (SPA)
+  - Prevents incorrect entry usage at build initialization
+
+### Changed
+
+- **Architecture Refactor**
+  - Removed default resolution logic from `templatesLoader`
+  - Simplified `validateCoreOptions` to focus only on value validation
+  - Moved filesystem validation responsibility into template loader
+  - Improved internal separation of concerns
+
+- **Cleaner Internal API Design**
+  - Base config now operates on normalized options
+  - Reduced configuration coupling
+  - Improved long-term scalability (SSR / future app types)
+
+### Notes
+
+- No breaking changes were introduced.
+- Default behavior remains `mpa`.
+- Fully backward compatible with existing templates.
+- SPA mode is stable but recommended for controlled usage.
+
+---
+
 ## [1.4.1] - 2026-02-19
 
 ### Changed

package/README.md

@@ -11,38 +11,63 @@ template-driven builds using `pug-plugin`.
 
 ---
 
-## ⚠️ Important
+## Designed for
 
-Versions prior to 1.1.6 were part of a stabilization phase and are not recommended for production use.
+Part of the
+[Webpack Starter Monorepo](https://github.com/Razerspine/webpack-starter-monorepo).
 
-Please use:
+Can be used independently in any Pug-based project.
 
-```bash
-npm install @razerspine/webpack-core@^1.2.1
+---
+
+## Key Features
+
+- Pug template-driven builds (no implicit JS entry)
+- Multi-page (MPA) and Single-page (SPA) modes
+- JavaScript or TypeScript support
+- SCSS or Less support
+- Recursive file watching (`src/**/*`)
+- SPA-friendly dev server
+- Config validation layer
+- Centralized options normalization (v1.7.0+)
+- Fully customizable dev & prod configs
+
+---
+
+## Application Modes (v1.7.0+)
+
+### MPA (Default)
+
+```js
+appType: 'mpa'
 ```
 
-## Designed for
+- `templates.entry` must be a directory
+- Example: `src/views/pages`
+- Each page generates its own HTML file
 
-This package is developed as part of the  
-[Webpack Starter Monorepo](https://github.com/Razerspine/webpack-starter-monorepo).
+### SPA
 
-It contains shared webpack configuration and loaders used by the starter
-templates, but can also be used independently.
+```js
+appType: 'spa'
+```
+
+- `templates.entry` must be a single Pug file
+- Example: `src/views/app.pug`
+- Always outputs: `index.html`
 
 ---
 
-## Design principles
+## Design Principles
 
 - **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.
+- **Template-driven architecture**: Webpack JS entry is intentionally disabled. Builds are driven by Pug template entries.
+- **MPA by default**: Directory-based page generation remains the primary mode.
+- **Optional SPA support (v1.7.0+)**: Single-entry template mode is supported without breaking MPA workflow.
+- **Stability-first production defaults**: No aggressive optimizations (e.g. `splitChunks`) are enabled by default to prevent template asset resolution issues.
+- **Validated configuration layer**: Core options are validated before Webpack initialization.
+- **Centralized option normalization (v1.7.0+)**: Default resolution is handled internally through a normalization layer to avoid configuration drift.
+- **Flexible overrides**: Dev and Prod configs can be extended safely via optional parameters.
 
 ---
 
@@ -59,17 +84,6 @@ templates, but can also be used independently.
 
 ---
 
-## 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)
-
-> No breaking changes were introduced.
-
----
-
 ## Installation
 
 ```bash
@@ -95,6 +109,7 @@ module.exports = (env = {}, argv = {}) => {
 
   const baseConfig = createBaseConfig({
     mode,
+    appType: 'mpa', // or 'spa'
     scripts: 'js', // or 'ts'
     styles: 'scss', // or 'less'
     templates: {
@@ -142,6 +157,22 @@ if (mode === 'production') {
 
 ---
 
+## Architecture Principles
+- Webpack handles module resolution and asset processing
+- PugPlugin handles template compilation
+- No implicit webpack JS entry
+- No aggressive production optimizations by default
+- Options validated before build initialization
+- Defaults resolved through a normalization layer (v1.7.0+)
+
+---
+
+## Stability
+
+Versions prior to 1.1.6 were part of a stabilization phase and are not recommended for production use.
+
+---
+
 ## API Reference
 
 `createBaseConfig(options)`
@@ -174,6 +205,8 @@ All options are validated before initialization.
 - `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.d.ts

@@ -1,7 +1,6 @@
-import { ModeType } from '../types/mode-type';
 import { ConfigOptionType } from '../types/config-option-type';
 export declare function createBaseConfig(options: ConfigOptionType): {
-    mode: ModeType;
+    mode: import("..").ModeType;
     context: string;
     output: {
         path: string;
@@ -77,6 +76,6 @@ export declare function createBaseConfig(options: ConfigOptionType): {
             onlyModule?: boolean;
         }[] | {
             [index: string]: string | false | string[];
-        };
+        } | undefined;
     };
 };

package/dist/config/base.js

@@ -4,18 +4,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBaseConfig = createBaseConfig;
+const path_1 = __importDefault(require("path"));
 const assets_1 = require("../loaders/assets");
 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");
+const normalize_core_options_1 = require("../utils/normalize-core-options");
+const webpack_1 = require("webpack");
 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';
+    const normalized = (0, normalize_core_options_1.normalizeCoreOptions)(options);
     return {
-        mode,
+        mode: normalized.mode,
         context: process.cwd(),
         output: {
             path: path_1.default.join(process.cwd(), 'dist'),
@@ -24,19 +25,27 @@ function createBaseConfig(options) {
         module: {
             rules: [
                 (0, assets_1.assetsLoader)(),
-                (0, scripts_1.scriptsLoader)(options),
-                (0, styles_1.stylesLoader)(options),
+                (0, scripts_1.scriptsLoader)(normalized),
+                (0, styles_1.stylesLoader)(normalized),
             ],
         },
         plugins: [
+            new webpack_1.LoaderOptionsPlugin({
+                options: {
+                    _meta: {
+                        appType: normalized.appType,
+                    }
+                }
+            }),
             ...(0, templates_1.templatesLoader)({
-                entry: (_b = options.templates) === null || _b === void 0 ? void 0 : _b.entry,
-                mode
+                entry: normalized.templates.entry,
+                mode: normalized.mode,
+                appType: normalized.appType,
             }),
         ],
         resolve: {
             extensions: ['.ts', '.tsx', '.js', '.json'],
-            alias: (_d = (_c = options.resolve) === null || _c === void 0 ? void 0 : _c.alias) !== null && _d !== void 0 ? _d : {}
+            alias: normalized.resolve.alias,
         },
     };
 }

package/dist/config/dev.d.ts

@@ -1,7 +1,7 @@
-import type { Configuration as WebpackConfiguration } from 'webpack';
 import type { Configuration as DevServerConfiguration } from 'webpack-dev-server';
-type DevConfig = WebpackConfiguration & {
+import { BaseWebpackConfigType } from '../types/base-webpack-config-type';
+type DevConfig = BaseWebpackConfigType & {
     devServer?: DevServerConfiguration;
 };
-export declare function createDevConfig(baseConfig: WebpackConfiguration, options?: DevServerConfiguration): DevConfig;
+export declare function createDevConfig(baseConfig: BaseWebpackConfigType, options?: DevServerConfiguration): DevConfig;
 export {};

package/dist/config/dev.js

@@ -1,8 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDevConfig = createDevConfig;
+const webpack_1 = require("webpack");
 const webpack_merge_1 = require("webpack-merge");
 function createDevConfig(baseConfig, options = {}) {
+    var _a, _b, _c, _d, _e;
+    const loaderPlugin = (_a = baseConfig.plugins) === null || _a === void 0 ? void 0 : _a.find((p) => p instanceof webpack_1.LoaderOptionsPlugin);
+    const appType = (_e = (_d = (_c = (_b = loaderPlugin === null || loaderPlugin === void 0 ? void 0 : loaderPlugin.options) === null || _b === void 0 ? void 0 : _b.options) === null || _c === void 0 ? void 0 : _c._meta) === null || _d === void 0 ? void 0 : _d.appType) !== null && _e !== void 0 ? _e : 'mpa';
+    const historyApiFallBack = {
+        disableDotRule: true,
+        rewrites: [
+            {
+                from: /./,
+                to: appType === 'spa' ? '/index.html' : '/404.html',
+            }
+        ]
+    };
     const defaultDevServer = {
         hot: false,
         open: true,
@@ -10,10 +23,7 @@ function createDevConfig(baseConfig, options = {}) {
         compress: true,
         port: 8080,
         watchFiles: ['src/**/*'],
-        historyApiFallback: {
-            disableDotRule: true,
-            rewrites: [{ from: /./, to: '/404.html' }]
-        }
+        historyApiFallback: historyApiFallBack,
     };
     return (0, webpack_merge_1.merge)(baseConfig, {
         devtool: 'source-map',

package/dist/index.d.ts

@@ -4,4 +4,6 @@ export { createProdConfig } from './config/prod';
 export * from './types/mode-type';
 export * from './types/script-type';
 export * from './types/style-type';
+export * from './types/app-type';
 export * from './types/config-option-type';
+export * from './types/base-webpack-config-type';

package/dist/index.js

@@ -24,4 +24,6 @@ Object.defineProperty(exports, "createProdConfig", { enumerable: true, get: func
 __exportStar(require("./types/mode-type"), exports);
 __exportStar(require("./types/script-type"), exports);
 __exportStar(require("./types/style-type"), exports);
+__exportStar(require("./types/app-type"), exports);
 __exportStar(require("./types/config-option-type"), exports);
+__exportStar(require("./types/base-webpack-config-type"), exports);

package/dist/loaders/templates.d.ts

@@ -1,4 +1,7 @@
+import { ModeType } from '../types/mode-type';
+import { AppType } from '../types/app-type';
 export declare function templatesLoader(options: {
-    entry?: string;
-    mode: 'development' | 'production';
+    entry: string;
+    mode: ModeType;
+    appType: AppType;
 }): any[];

package/dist/loaders/templates.js

@@ -5,16 +5,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.templatesLoader = templatesLoader;
 const pug_plugin_1 = __importDefault(require("pug-plugin"));
-const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
 function templatesLoader(options) {
-    var _a;
+    const { entry, appType } = options;
+    if (!fs_1.default.existsSync(entry)) {
+        throw new Error(`[webpack-core] Templates entry not found: ${entry}`);
+    }
+    const stats = fs_1.default.statSync(entry);
+    if (appType === 'spa' && !stats.isFile()) {
+        throw new Error(`[webpack-core] SPA requires a single pug file as templates.entry`);
+    }
+    if (appType === 'mpa' && !stats.isDirectory()) {
+        throw new Error(`[webpack-core] MPA requires templates.entry to be a directory`);
+    }
+    const pluginEntry = appType === 'spa' ? { index: entry } : entry;
     return [
         new pug_plugin_1.default({
-            entry: path_1.default.resolve(process.cwd(), (_a = options.entry) !== null && _a !== void 0 ? _a : 'src/views/pages/'),
+            entry: pluginEntry,
             loaderOptions: {
-                method: 'compile',
+                method: 'compile'
             },
             filename: ({ chunk }) => {
+                if (appType === 'spa') {
+                    return 'index.html';
+                }
                 let [name] = chunk.name.split('/');
                 if (name === 'home')
                     name = 'index';

package/dist/types/app-type.d.ts

@@ -0,0 +1 @@
+export type AppType = 'mpa' | 'spa';

package/dist/types/app-type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/base-webpack-config-type.d.ts

@@ -0,0 +1,2 @@
+import type { Configuration as WebpackConfiguration } from 'webpack';
+export type BaseWebpackConfigType = WebpackConfiguration;

package/dist/types/base-webpack-config-type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/config-option-type.d.ts

@@ -1,11 +1,13 @@
 import { ModeType } from './mode-type';
 import { ScriptType } from './script-type';
 import { StyleType } from './style-type';
+import { AppType } from './app-type';
 import { Configuration } from 'webpack';
 export type ConfigOptionType = {
     mode: ModeType;
     scripts: ScriptType;
     styles: StyleType;
+    appType?: AppType;
     templates?: {
         /**
          * Path to pug pages directory

package/dist/utils/normalize-core-options.d.ts

@@ -0,0 +1,15 @@
+import { ConfigOptionType } from '../types/config-option-type';
+import { AppType } from '../types/app-type';
+import { ModeType } from '../types/mode-type';
+import { Configuration } from 'webpack';
+export interface NormalizedCoreOptions {
+    mode: ModeType;
+    appType: AppType;
+    scripts: 'js' | 'ts';
+    styles: 'scss' | 'less';
+    templates: {
+        entry: string;
+    };
+    resolve: NonNullable<Configuration['resolve']>;
+}
+export declare function normalizeCoreOptions(options: ConfigOptionType): NormalizedCoreOptions;

package/dist/utils/normalize-core-options.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCoreOptions = normalizeCoreOptions;
+const path_1 = __importDefault(require("path"));
+function normalizeCoreOptions(options) {
+    var _a, _b, _c, _d, _e, _f;
+    const mode = (_a = options.mode) !== null && _a !== void 0 ? _a : 'development';
+    const appType = (_b = options.appType) !== null && _b !== void 0 ? _b : 'mpa';
+    const templatesEntry = (_d = (_c = options.templates) === null || _c === void 0 ? void 0 : _c.entry) !== null && _d !== void 0 ? _d : (appType === 'spa' ? 'src/views/app.pug' : 'src/views/pages');
+    return {
+        mode,
+        appType,
+        scripts: options.scripts,
+        styles: options.styles,
+        templates: {
+            entry: path_1.default.resolve(process.cwd(), templatesEntry),
+        },
+        resolve: {
+            alias: (_f = (_e = options.resolve) === null || _e === void 0 ? void 0 : _e.alias) !== null && _f !== void 0 ? _f : {},
+        },
+    };
+}

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

@@ -1,17 +1,11 @@
 "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;
+    const { mode, scripts, styles, appType = 'mpa' } = options;
     // --- mode
     if (!['development', 'production'].includes(mode)) {
         throw new Error(`[webpack-core] Invalid mode "${mode}". Expected "development" or "production".`);
@@ -24,10 +18,8 @@ function validateCoreOptions(options) {
     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}`);
+    // --- appType
+    if (!['spa', 'mpa'].includes(appType)) {
+        throw new Error(`[webpack-core] Invalid appType "${appType}". Expected "spa" or "mpa".`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@razerspine/webpack-core",
-  "version": "1.4.1",
+  "version": "1.7.1",
   "description": "Core webpack config and loaders for starter templates",
   "keywords": [
     "webpack",
@@ -12,7 +12,7 @@
   "author": "Razerspine",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Razerspine/webpack-starter-monorepo",
+    "url": "git+https://github.com/Razerspine/webpack-starter-monorepo.git",
     "directory": "packages/webpack-core"
   },
   "homepage": "https://github.com/Razerspine/webpack-starter-monorepo/blob/main/packages/webpack-core#readme",