@razerspine/webpack-core 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@ required to ensure correct behavior in both development and production modes.
 
 ---
 
+## [1.9.0] - 2026-03-13
+
+### Added
+- **Smart Auto-Hosting Adapter**
+  - Integrated `detectHosting()` utility to automatically identify deployment platforms (**Vercel, Netlify, Cloudflare, GitHub Pages**).
+  - **Zero-Config Routing**: Automatically generates platform-specific configuration files (`_redirects`, `vercel.json`) based on `appType`.
+  - **Interactive Build Logs**: Added `infrastructureLogger` integration. The build now informs the developer about detected platforms (e.g., `📦 Netlify detected. Generating _redirects for SPA...`).
+- **Enhanced SPA Fallback Strategy**
+  - Automated `404.html` generation for **GitHub Pages** and static hosts when in SPA mode.
+  - Ensures seamless client-side routing without manual file duplication.
+
+### Changed
+- **Architectural Refactoring**
+  - Decoupled hosting logic into specialized utilities: `getRedirects`, `getVercelConfig`, and `detectHosting`.
+  - Improved `createProdConfig` maintainability by moving business logic out of the main configuration factory.
+- **Production Alignment**
+  - `createProdConfig` now actively reads `_meta.appType` from `LoaderOptionsPlugin` to synchronize routing logic with the development server.
+
+### Fixed
+- **Type Safety**: Improved Webpack 5 internal typing for asset emission using `sources.RawSource`.
+- **Build Reliability**: Replaced `copy-webpack-plugin` for generated assets with a native Webpack emission strategy to prevent "file not found" errors during build.
+
+---
+
 ## [1.8.0] - 2026-03-13
 
 ### Added

package/README.md

@@ -1,92 +1,62 @@
 # @razerspine/webpack-core
+
 [![npm version](https://img.shields.io/npm/v/@razerspine/webpack-core.svg)](https://www.npmjs.com/package/@razerspine/webpack-core)
 [![changelog](https://img.shields.io/badge/docs-changelog-blue.svg)](./CHANGELOG.md)
 [![license](https://img.shields.io/npm/l/@razerspine/webpack-core.svg)](./LICENSE)
 
-
 Core webpack configuration and loaders for **Pug-based** projects.
 
-This package provides a stable, production-safe webpack foundation for
-template-driven builds using `pug-plugin`.
+This package provides a stable, production-safe webpack foundation for template-driven builds using `pug-plugin`, now
+with **Smart Auto-Hosting** support.
 
 ---
 
-## Designed for
-
-Part of the
-[Webpack Starter Monorepo](https://github.com/Razerspine/webpack-starter-monorepo).
+## 🚀 Key Features
 
-Can be used independently in any Pug-based project.
+- **Pug template-driven builds**: Webpack JS entry is intentionally disabled.
+- **Hybrid Modes**: Full support for Multi-page (MPA) and Single-page (SPA) architectures.
+- **Smart Auto-Hosting (v1.9.0)**: Automatically detects **Vercel, Netlify, Cloudflare**, and **GitHub Pages** to
+  generate required routing configs.
+- **Zero-Config SPA Fallback**: Automatic `404.html` generation for GitHub Pages to fix client-side routing.
+- **Full Tech Stack**: Native support for TypeScript/JavaScript and SCSS/Less.
+- **Developer Experience**: Recursive file watching (`src/**/*`), auto-browser open, and infrastructure logging.
+- **Validation Layer**: Core options are validated and normalized before Webpack initialization.
 
 ---
 
-## 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.1+)
-- Fully customizable dev & prod configs
-- **New (v1.8.0) Automatic Deployment Configs**: Generates `_redirects` and `vercel.json` automatically.
-- **New (v1.8.0) GitHub Pages SPA Support**: Automatic `404.html` fallback for single-page apps.
-
----
-
-## Application Modes (v1.7.1+)
+## 🛠 Application Modes
 
 ### MPA (Default)
 
-```js
-appType: 'mpa'
-```
+`appType: 'mpa'`
 
-- `templates.entry` must be a directory
-- Example: `src/views/pages`
-- Each page generates its own HTML file
+- `templates.entry` must be a **directory** (e.g., `src/views/pages`).
+- Each Pug file in the directory generates its own HTML file.
 
 ### SPA
 
-```js
-appType: 'spa'
-```
+`appType: 'spa'`
 
-- `templates.entry` must be a single Pug file
-- Example: `src/views/app.pug`
-- Always outputs: `index.html`
+- `templates.entry` must be a **single Pug file** (e.g., `src/app/app.pug`).
+- Always outputs `index.html`.
+- Enables automatic routing configuration for production hosting.
 
 ---
 
-## Design Principles
-
-- **Webpack is responsible for**: module resolution, aliases (`resolve.alias`), and asset handling.
-- **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.1+)**: 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.1+)**: 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.
-
----
+## 🌍 Smart Hosting Adapter (New v1.9.0)
 
-## Features
+The core now detects the environment during the production build and emits the necessary configuration files:
 
-- **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+)**
+| Platform                 | Generated File | Purpose                                                      |
+|:-------------------------|:---------------|:-------------------------------------------------------------|
+| **Netlify / Cloudflare** | `_redirects`   | Handles SPA rewrites and MPA fallbacks.                      |
+| **Vercel**               | `vercel.json`  | Configures Vercel Edge Network routing.                      |
+| **GitHub Pages**         | `404.html`     | Duplicates `index.html` to prevent 404 errors on deep links. |
+| **Static / Others**      | `404.html`     | Generic fallback for SPA mode.                               |
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @razerspine/webpack-core
@@ -94,7 +64,7 @@ npm install @razerspine/webpack-core
 
 ---
 
-## Usage
+## 📖 Usage
 
 ### Basic Setup
 
@@ -107,20 +77,20 @@ const {
 } = require('@razerspine/webpack-core');
 
 module.exports = (env = {}, argv = {}) => {
-  const mode = argv.mode || 'development';
+  const mode = argv.mode || process.env.NODE_ENV || 'development';
 
   const baseConfig = createBaseConfig({
     mode,
-    appType: 'mpa', // or 'spa'
-    scripts: 'js', // or 'ts'
-    styles: 'scss', // or 'less'
+    appType: 'spa', // 'spa' or 'mpa'
+    scripts: 'ts',  // 'js' or 'ts'
+    styles: 'scss', // 'scss' or 'less'
     templates: {
-      entry: 'src/views/pages',
+      entry: 'src/app/app.pug',
     },
     resolve: {
       alias: {
-        '@views': path.resolve(process.cwd(), 'src/views'),
-        '@styles': path.resolve(process.cwd(), 'src/assets/styles'),
+        '@app': path.resolve(process.cwd(), 'src/app'),
+        '@styles': path.resolve(process.cwd(), 'src/styles'),
       },
     },
   });
@@ -133,21 +103,20 @@ module.exports = (env = {}, argv = {}) => {
 };
 ```
 
-### Customizing Configuration (v1.2.1+)
+### Customizing Configuration
 
-You can now pass an optional second argument to `createDevConfig` and `createProdConfig` to override defaults:
+You can override any default setting by passing an object as the second argument:
 
 ```js
-// Customizing the Dev Server (port, open browser, etc.)
+// Customizing the Dev Server
 if (mode === 'development') {
   return createDevConfig(baseConfig, {
     port: 3000,
     open: true,
-    // extra devServer options...
   });
 }
 
-// Customizing Production (minification, performance hints, etc.)
+// Customizing Production optimizations
 if (mode === 'production') {
   return createProdConfig(baseConfig, {
     performance: {
@@ -159,57 +128,13 @@ 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.1+)
-
----
-
-## Stability
-
-Versions prior to 1.1.6 were part of a stabilization phase and are not recommended for production use.
-
----
-
-## 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?)`
+## 🏗 Architecture Principles
 
-- `baseConfig`: The configuration returned by createBaseConfig.
-- `options`: (Optional) Webpack configuration object for production overrides.
-- **Default behavior**:
-  - Enables source maps and minification.
-  - Disables `splitChunks` for template compatibility.
-  - **New**: Generates routing assets (`_redirects`, `vercel.json`) based on `appType`.
-  - **New**: Creates `404.html` fallback for SPA mode.
+- **Template-First**: Webpack handles assets, but Pug templates drive the entry points.
+- **Stability-First**: Aggressive optimizations (like `splitChunks`) are disabled by default to ensure reliable asset
+  resolution in templates.
+- **Environment Aware**: The build process is aware of CI/CD environments and adapts output artifacts accordingly.
+- **Type Safe**: Improved internal typing for Webpack 5 asset emission.
 
 ---
 

package/dist/config/prod.js

@@ -3,40 +3,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createProdConfig = createProdConfig;
 const webpack_1 = require("webpack");
 const webpack_merge_1 = require("webpack-merge");
-function getRedirects(appType) {
-    return appType === 'spa'
-        ? '/* /index.html   200\n'
-        : '/* /404.html     404\n';
-}
-function getVercelConfig(appType) {
-    const config = appType === 'spa'
-        ? { routes: [{ src: '/(.*)', dest: '/index.html' }] }
-        : {
-            routes: [
-                { handle: 'filesystem' },
-                { src: '/(.*)', dest: '/404.html', status: 404 }
-            ]
-        };
-    return JSON.stringify(config, null, 2);
-}
+const detect_hosting_1 = require("../utils/detect-hosting");
+const get_vercel_config_1 = require("../utils/get-vercel-config");
+const get_redirects_1 = require("../utils/get-redirects");
 function createProdConfig(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 hosting = (0, detect_hosting_1.detectHosting)();
     const routingPlugin = {
         apply(compiler) {
+            const logger = compiler.getInfrastructureLogger('@razerspine/webpack-core');
             compiler.hooks.thisCompilation.tap('RoutingPlugin', (compilation) => {
                 compilation.hooks.processAssets.tap({
                     name: 'RoutingPlugin',
                     stage: webpack_1.Compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
                 }, () => {
-                    const { RawSource } = webpack_1.sources;
-                    compilation.emitAsset('_redirects', new RawSource(getRedirects(appType)));
-                    compilation.emitAsset('vercel.json', new RawSource(getVercelConfig(appType)));
+                    /**
+                     * Netlify / Cloudflare
+                     */
+                    if (hosting === 'netlify' || hosting === 'cloudflare') {
+                        logger.info(`📦 ${hosting.charAt(0).toUpperCase() + hosting.slice(1)} detected. Generating _redirects for ${appType.toUpperCase()}...`);
+                        compilation.emitAsset('_redirects', new webpack_1.sources.RawSource((0, get_redirects_1.getRedirects)(appType)));
+                    }
+                    /**
+                     * Vercel
+                     */
+                    if (hosting === 'vercel') {
+                        logger.info(`📦 Vercel detected. Generating vercel.json for ${appType.toUpperCase()}...`);
+                        compilation.emitAsset('vercel.json', new webpack_1.sources.RawSource((0, get_vercel_config_1.getVercelConfig)(appType)));
+                    }
+                    /**
+                     * SPA fallback
+                     * Needed for:
+                     * - GitHub Pages
+                     * - static hosting
+                     */
                     if (appType === 'spa') {
                         const indexAsset = compilation.getAsset('index.html');
                         if (indexAsset) {
-                            compilation.emitAsset('404.html', indexAsset.source);
+                            const source = indexAsset.source.source().toString();
+                            if (hosting === 'github' || hosting === 'static') {
+                                const hostName = hosting === 'github' ? 'GitHub Pages' : 'Static hosting';
+                                logger.info(`📦 ${hostName} detected. Creating 404.html fallback for SPA...`);
+                                compilation.emitAsset('404.html', new webpack_1.sources.RawSource(source));
+                            }
                         }
                     }
                 });

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export * from './types/style-type';
 export * from './types/app-type';
 export * from './types/config-option-type';
 export * from './types/base-webpack-config-type';
+export * from './types/hosting-type';

package/dist/index.js

@@ -27,3 +27,4 @@ __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);
+__exportStar(require("./types/hosting-type"), exports);

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

@@ -0,0 +1 @@
+export type HostingType = 'netlify' | 'vercel' | 'cloudflare' | 'github' | 'static';

package/dist/types/hosting-type.js

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

package/dist/utils/detect-hosting.d.ts

@@ -0,0 +1,2 @@
+import { HostingType } from '../types/hosting-type';
+export declare function detectHosting(): HostingType;

package/dist/utils/detect-hosting.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectHosting = detectHosting;
+function detectHosting() {
+    if (process.env.NETLIFY)
+        return 'netlify';
+    if (process.env.VERCEL)
+        return 'vercel';
+    if (process.env.CF_PAGES)
+        return 'cloudflare';
+    if (process.env.GITHUB_ACTIONS)
+        return 'github';
+    return 'static';
+}

package/dist/utils/get-redirects.d.ts

@@ -0,0 +1,2 @@
+import { AppType } from '../types/app-type';
+export declare function getRedirects(appType: AppType): string;

package/dist/utils/get-redirects.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRedirects = getRedirects;
+function getRedirects(appType) {
+    return appType === 'spa'
+        ? '/* /index.html 200\n'
+        : '/* /404.html 404\n';
+}

package/dist/utils/get-vercel-config.d.ts

@@ -0,0 +1,2 @@
+import { AppType } from '../types/app-type';
+export declare function getVercelConfig(appType: AppType): string;

package/dist/utils/get-vercel-config.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVercelConfig = getVercelConfig;
+function getVercelConfig(appType) {
+    const config = appType === 'spa'
+        ? {
+            routes: [
+                {
+                    src: '/(.*)',
+                    dest: '/index.html',
+                },
+            ],
+        }
+        : {
+            routes: [
+                {
+                    handle: 'filesystem'
+                },
+                {
+                    src: '/(.*)',
+                    dest: '/404.html',
+                    status: 404,
+                },
+            ],
+        };
+    return JSON.stringify(config, null, 2);
+}

package/package.json

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