@vyriy/webpack-config 0.3.4 → 0.3.8

package/README.md

@@ -4,20 +4,24 @@ Shared Webpack config for Vyriy projects.
 
 ## Purpose
 
-This package provides two small typed Webpack config generators for Vyriy client and server builds.
+This package provides small typed Webpack helpers for Vyriy client and server builds:
+
+- browser and SSR config generators
+- an HTML plugin helper backed by `html-webpack-plugin` and `@vyriy/html`
+- a node_modules externalizer for server bundles
 
 ## Install
 
 With npm:
 
 ```bash
-npm install @vyriy/webpack-config webpack webpack-cli
+npm install @vyriy/webpack-config webpack-cli
 ```
 
 With Yarn:
 
 ```bash
-yarn add @vyriy/webpack-config webpack webpack-cli
+yarn add @vyriy/webpack-config webpack-cli
 ```
 
 The `webpack` package is listed in the install command because the shared config is consumed by Webpack at build time. Add `webpack-cli` only when the consumer project runs Webpack through CLI commands.
@@ -39,44 +43,36 @@ export default csr('./src/index.tsx', {
 For SSR bundles:
 
 ```js
-import { ssr } from '@vyriy/webpack-config';
-
-export default ssr(['@w/api'], {
-  path: '/absolute/path/to/dist/api',
-  filename: 'index.js',
-  library: { type: 'commonjs2' },
-  clean: true,
-});
-```
-
-The second parameter is a regular Webpack `output` config passed as-is.
-
-Both generators accept a third parameter with a local Webpack config transform. The transform receives the shared config and returns the final config, so the consumer can choose where to extend defaults and where to replace them:
+import { ssr, external } from '@vyriy/webpack-config';
 
-```js
-import { csr } from '@vyriy/webpack-config';
-
-export default csr(
-  './src/index.tsx',
+export default ssr(
+  ['@w/api'],
   {
-    path: '/absolute/path/to/dist/client',
+    path: '/absolute/path/to/dist/api',
     filename: 'index.js',
+    library: { type: 'commonjs2' },
     clean: true,
   },
   (config) => ({
     ...config,
-    optimization: {
-      ...config.optimization,
-      splitChunks: true,
-    },
+    externals: [
+      ...(Array.isArray(config.externals) ? config.externals : []),
+      external({
+        allowlist: [/^@p/, /^@w/, /^@vyriy/],
+      }),
+    ],
   }),
 );
 ```
 
-For example, append a local CSR plugin while keeping the shared CSR plugin:
+The second parameter is a regular Webpack `output` config passed as-is.
+
+Both generators accept a third parameter with a local Webpack config transform. The transform receives the shared config and returns the final config, so the consumer can choose where to extend defaults and where to replace them.
+
+For example, add an HTML document to a client build:
 
 ```js
-import { csr } from '@vyriy/webpack-config';
+import { csr, html } from '@vyriy/webpack-config';
 
 export default csr(
   './src/index.tsx',
@@ -89,12 +85,32 @@ export default csr(
     ...config,
     plugins: [
       ...(config.plugins ?? []),
-      new LocalPlugin(),
+      html({
+        title: '<title>App</title>',
+        body: '<div id="root"></div>',
+      }),
     ],
   }),
 );
 ```
 
+The `html` helper accepts `HtmlProps` from `@vyriy/html` as the first parameter and optional `html-webpack-plugin` options as the second parameter:
+
+```js
+import { html } from '@vyriy/webpack-config';
+
+html(
+  {
+    title: '<title>App</title>',
+    meta: '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+    body: '<div id="root"></div>',
+  },
+  {
+    filename: 'index.html',
+  },
+);
+```
+
 With types:
 
 ```ts
@@ -113,6 +129,8 @@ export default config;
 
 - `csr(entry, output, transform?)` creates a browser-oriented Webpack config.
 - `ssr(entry, output, transform?)` creates a node-oriented SSR Webpack config.
+- `html(props, options?)` creates an `HtmlWebpackPlugin` instance from `@vyriy/html` document sections.
+- `external(options?)` creates a Webpack `externals` function that leaves bare package imports as CommonJS runtime imports.
 - `WebpackConfig`, `WebpackConfigTransform`, `WebpackEntry`, and `WebpackOutput` expose the shared config helper types.
 
 Shared defaults:
@@ -123,4 +141,18 @@ Shared defaults:
 - production `optimization` with `TerserPlugin`
 - merged `resolve` defaults
 
+CSR defaults:
+
+- production builds extract CSS with `MiniCssExtractPlugin`
+- development builds enable React refresh with `ReactRefreshWebpackPlugin`
+
+HTML plugin defaults:
+
+- `templateContent` rendered from `@vyriy/html`
+- `publicPath: '/'`
+- `hash: true`
+- `inject: 'body'`
+- minification enabled for whitespace, comments, JS, and CSS
+- local plugin options override shared defaults
+
 See the article with a complete browser and SSR bundling walkthrough: <https://vyriy.dev/examples/vyriy-webpack-config/>.

package/csr.js

@@ -1,6 +1,6 @@
-import { path } from '@vyriy/path';
 import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import { path } from '@vyriy/path';
 import { mode } from './mode.js';
 import { optimization } from './optimization.js';
 import { performance } from './performance.js';

package/external.d.ts

@@ -0,0 +1,2 @@
+import type { NodeModulesExternalOptions, WebpackExternal } from './types.js';
+export declare const external: (options?: NodeModulesExternalOptions) => WebpackExternal;

package/external.js

@@ -0,0 +1,15 @@
+import { isAbsolute } from 'node:path';
+const isPackageRequest = (request) => !request.startsWith('.') && !isAbsolute(request);
+const matchesPattern = (pattern, request) => typeof pattern === 'string' ? pattern === request : pattern.test(request);
+export const external = (options = {}) => {
+    const allowlist = options.allowlist ?? [];
+    return ({ request }, callback) => {
+        const shouldBundle = !request || !isPackageRequest(request) || allowlist.some((pattern) => matchesPattern(pattern, request));
+        if (shouldBundle) {
+            callback();
+        }
+        else {
+            callback(null, `commonjs ${request}`);
+        }
+    };
+};

package/html.d.ts

@@ -0,0 +1,3 @@
+import HtmlWebpackPlugin, { type Options } from 'html-webpack-plugin';
+import { type HtmlProps } from '@vyriy/html';
+export declare const html: (props: HtmlProps, options?: Options) => HtmlWebpackPlugin;

package/html.js

@@ -0,0 +1,18 @@
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+import { html as page } from '@vyriy/html';
+export const html = (props, options = {}) => {
+    return new HtmlWebpackPlugin({
+        templateContent: page(props),
+        publicPath: '/',
+        hash: true,
+        inject: 'body',
+        minify: {
+            removeComments: true,
+            collapseWhitespace: true,
+            removeAttributeQuotes: false,
+            minifyJS: true,
+            minifyCSS: true,
+        },
+        ...options,
+    });
+};

package/index.d.ts

@@ -1,3 +1,5 @@
 export * from './csr.js';
+export * from './external.js';
+export * from './html.js';
 export * from './ssr.js';
 export type * from './types.js';

package/index.js

@@ -1,2 +1,4 @@
 export * from './csr.js';
+export * from './external.js';
+export * from './html.js';
 export * from './ssr.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyriy/webpack-config",
-  "version": "0.3.4",
+  "version": "0.3.8",
   "description": "Shared Webpack config for Vyriy projects",
   "type": "module",
   "main": "./index.js",
@@ -13,22 +13,24 @@
     "@babel/register": "^7.29.3",
     "@babel/runtime": "^7.29.2",
     "@pmmmwh/react-refresh-webpack-plugin": "^0.6.2",
-    "@vyriy/env": "0.3.4",
-    "@vyriy/path": "0.3.4",
+    "@vyriy/env": "0.3.8",
+    "@vyriy/html": "0.3.8",
+    "@vyriy/path": "0.3.8",
     "babel-loader": "^10.1.1",
     "css-loader": "^7.1.4",
     "cssnano": "^8.0.1",
+    "html-webpack-plugin": "^5.6.7",
     "mini-css-extract-plugin": "^2.10.2",
     "null-loader": "^4.0.1",
-    "postcss": "^8.5.14",
+    "postcss": "^8.5.15",
     "postcss-loader": "^8.2.1",
     "postcss-preset-env": "^11.3.0",
     "react-refresh": "^0.18.0",
     "sass": "^1.99.0",
-    "sass-loader": "^16.0.8",
+    "sass-loader": "^17.0.0",
     "style-loader": "^4.0.0",
     "terser-webpack-plugin": "^5.6.0",
-    "webpack": "^5.106.2"
+    "webpack": "^5.107.0"
   },
   "agents": "./AGENTS.md",
   "license": "MIT",
@@ -64,6 +66,26 @@
       "import": "./csr.js",
       "default": "./csr.js"
     },
+    "./external": {
+      "types": "./external.d.ts",
+      "import": "./external.js",
+      "default": "./external.js"
+    },
+    "./external.js": {
+      "types": "./external.d.ts",
+      "import": "./external.js",
+      "default": "./external.js"
+    },
+    "./html": {
+      "types": "./html.d.ts",
+      "import": "./html.js",
+      "default": "./html.js"
+    },
+    "./html.js": {
+      "types": "./html.d.ts",
+      "import": "./html.js",
+      "default": "./html.js"
+    },
     "./index": {
       "types": "./index.d.ts",
       "import": "./index.js",

package/types.d.ts

@@ -3,3 +3,7 @@ export type WebpackConfig = Configuration;
 export type WebpackEntry = WebpackConfig['entry'];
 export type WebpackOutput = WebpackConfig['output'];
 export type WebpackConfigTransform = (config: WebpackConfig) => WebpackConfig;
+export type WebpackExternal = Extract<NonNullable<Configuration['externals']>, unknown[]>[number];
+export type NodeModulesExternalOptions = {
+    allowlist?: (RegExp | string)[];
+};