@asd14/vblocks 1.0.0 → 2.0.0

package/bin/vblocks.sh

@@ -8,20 +8,23 @@
 #
 # Available Commands:
 # ---
+# init: Creates a new project from the template
 # build: Creates a production-ready build of your project
 # serve: Starts a development server with live reload
-# eject: Copies default webpack and swc configs to your project for customization
+# eject: Prints a default config, save it in your project to customize it
 #
 # Usage Examples:
 # ---
+# npx vblocks init my-app    # Create a project in ./my-app
+# npx vblocks init my-flow --template xyflow-playground
 # npx vblocks build    # Build for production
 # npx vblocks serve    # Start dev server
-# npx vblocks eject    # Copy config files to your project
+# npx vblocks eject webpack > webpack.config.js    # Customize a config
 # =============================================================================
 
 # Directory where this script is located and
 # default configuration file paths (from this package).
-export VB_DIR="$(dirname "$(dirname "$(readlink -f "$0")")")"
+export VB_DIR="$(dirname "$(dirname "$(realpath "$0")")")"
 
 # Project directory (where you run the command from) and
 # project-specific config file paths.
@@ -37,7 +40,6 @@ select_config() {
 # Determine config files location.
 export VB_WEBPACK_CONFIG="$(select_config "webpack.config.js")"
 export VB_POSTCSS_CONFIG="$(select_config "postcss.config.js")"
-export VB_TAILWIND_CONFIG="$(select_config "tailwind.config.js")"
 export VB_SWC_CONFIG="$(select_config ".swcrc")"
 
 # Wrap webpack command with custom configs
@@ -62,15 +64,90 @@ run_webpack() {
     "$@"
 }
 
-# Copy config files to your project
-copy_config_files() {
-  project_path="$PROJECT_DIR/$1"
-  default_path=$(realpath "$VB_DIR/$1")
+# Print the template names, one per line. A template is a folder in
+# `template/` whose name has no `_` prefix
+list_templates() {
+  for list_dir in "$VB_DIR"/template/*/; do
+    [ -d "$list_dir" ] || continue
+    list_name=$(basename "$list_dir")
+
+    case "$list_name" in
+      _*) ;;
+      *) printf '%s\n' "$list_name" ;;
+    esac
+  done
+}
+
+# Copy `template/_common`, then one template over it, into a directory that
+# is missing or empty
+init_project() {
+  init_usage="Usage: vblocks init <directory> [--template <name>]"
+  init_dir=""
+  init_template="plain"
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --template)
+        if [ "$#" -lt 2 ]; then
+          echo "$init_usage" >&2
+          exit 1
+        fi
+        init_template=$2
+        shift 2
+        ;;
+      -*)
+        echo "$init_usage" >&2
+        exit 1
+        ;;
+      *)
+        if [ -n "$init_dir" ]; then
+          echo "$init_usage" >&2
+          exit 1
+        fi
+        init_dir=$1
+        shift
+        ;;
+    esac
+  done
 
-  if [ ! -f "$project_path" ]; then
-    cp "$default_path" "$project_path" \
-      && echo "Created $1 in your project" >&2
+  if [ -z "$init_dir" ]; then
+    echo "$init_usage" >&2
+    exit 1
   fi
+
+  init_templates=$(list_templates)
+  if ! printf '%s\n' "$init_templates" | grep -qxF -- "$init_template"; then
+    printf 'Unknown template "%s". Available: %s\n' "$init_template" \
+      "$(printf '%s\n' "$init_templates" | paste -sd, - | sed 's/,/, /g')" >&2
+    exit 1
+  fi
+
+  if [ -e "$init_dir" ] && [ -n "$(ls -A -- "$init_dir")" ]; then
+    printf '%s exists and is not empty\n' "$init_dir" >&2
+    exit 1
+  fi
+
+  mkdir -p -- "$init_dir" || exit 1
+  cp -R -- "$VB_DIR/template/_common/." "$init_dir" || exit 1
+  cp -R -- "$VB_DIR/template/$init_template/." "$init_dir" || exit 1
+
+  # npm leaves every `.gitignore` out of the package, so the template ships
+  # `_gitignore`
+  mv -- "$init_dir/_gitignore" "$init_dir/.gitignore" || exit 1
+
+  init_name=$(basename "$(realpath "$init_dir")")
+  init_version=$(node -p "require('$VB_DIR/package.json').version")
+
+  (
+    cd -- "$init_dir" \
+      && npm pkg set "name=$init_name" \
+        "devDependencies.@asd14/vblocks=^$init_version"
+  ) || exit 1
+
+  printf 'Created %s. Next:\n\n' "$init_name"
+  printf '  cd %s\n' "$init_dir"
+  printf '  npm install\n'
+  printf '  npm start\n'
 }
 
 print_hero() {
@@ -103,7 +180,6 @@ print_hero() {
   printf "│\n"
   printf "│ %b\n" " Webpack: $(format_config_path "$VB_WEBPACK_CONFIG")"
   printf "│ %b\n" " PostCSS: $(format_config_path "$VB_POSTCSS_CONFIG")"
-  printf "│ %b\n" " Tailwind: $(format_config_path "$VB_TAILWIND_CONFIG")"
   printf "│ %b\n" "󱡮 SWC: $(format_config_path "$VB_SWC_CONFIG")"
   printf "╰──┤\n\n"
 }
@@ -112,16 +188,23 @@ print_hero() {
 # │ Main
 # ╰────────
 
-print_hero
+# stdout carries the config `eject` prints, keep the hero out of it
+print_hero >&2
 
 case "$1" in
+  init)
+    shift
+    init_project "$@"
+    ;;
   build)
     shift
-    run_webpack build "$@"
+    # Without a mode Webpack falls back to `production`, also for `serve`.
+    # A `--mode` in "$@" comes later, so it wins.
+    run_webpack build --mode production "$@"
     ;;
   serve)
     shift
-    run_webpack serve "$@"
+    run_webpack serve --mode development "$@"
     ;;
   eject)
     shift
@@ -129,16 +212,22 @@ case "$1" in
 
     case "$file" in
       webpack)
-        cat "$VB_DIR/webpack.config.js"
+        cat "$VB_DIR/src/webpack.config.js"
+        ;;
+      postcss)
+        cat "$VB_DIR/src/postcss.config.js"
+        ;;
+      swc)
+        cat "$VB_DIR/src/.swcrc"
         ;;
       *)
-        echo "Unknown config file to eject. Available: webpack, postcss, tailwind and swc" >&2
+        echo "Unknown config file to eject. Available: webpack, postcss and swc" >&2
         exit 1
         ;;
     esac
     ;;
   *)
-    echo "Usage: $0 {build|serve|eject}" >&2
+    echo "Usage: $0 {init|build|serve|eject}" >&2
     exit 1
     ;;
 esac

package/package.json

@@ -1,8 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@asd14/vblocks",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "󱆃 POSIX +  Webpack, an unlikely story!",
+  "license": "MIT",
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
@@ -19,9 +20,16 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "template"
   ],
   "type": "module",
+  "exports": {
+    "./client": {
+      "types": "./src/types/client.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "vblocks": "bin/vblocks.sh"
   },
@@ -29,53 +37,55 @@
     "----UTIL": "",
     "prepare": "git config --local core.hooksPath .githook",
     "format": "eslint --fix .",
-    "----CODE-ANALYSIS": "",
+    "----CODE-QA": "",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "unit-test:template": "tools/verify-templates",
+    "unit-test": "npm run unit-test:template"
   },
   "dependencies": {
-    "@csstools/postcss-global-data": "^3.1.0",
     "@mdx-js/loader": "^3.1.1",
-    "@pmmmwh/react-refresh-webpack-plugin": "^0.6.1",
-    "browserslist": "^4.26.2",
-    "copy-webpack-plugin": "^13.0.1",
-    "css-loader": "^7.1.2",
-    "cssnano": "^7.1.1",
-    "dotenv-webpack": "^8.1.1",
-    "html-webpack-plugin": "^5.6.4",
-    "mini-css-extract-plugin": "^2.9.4",
-    "postcss": "^8.5.6",
-    "postcss-loader": "^8.2.0",
-    "postcss-preset-env": "^10.3.1",
-    "react-refresh": "^0.17.0",
-    "style-loader": "^4.0.0",
-    "swc-loader": "^0.2.6",
-    "tailwindcss": "^4.1.13",
-    "webpack": "^5.101.3",
-    "webpack-bundle-analyzer": "^4.10.2",
-    "webpack-cli": "^6.0.1",
-    "webpack-dev-server": "^5.2.2"
+    "@pmmmwh/react-refresh-webpack-plugin": "^0.6.3",
+    "@swc/helpers": "^0.5.23",
+    "browserslist": "^4.29.3",
+    "copy-webpack-plugin": "^14.0.0",
+    "css-loader": "^7.1.5",
+    "cssnano": "^9.6.0",
+    "dotenv-webpack": "^9.0.0",
+    "html-webpack-plugin": "^5.6.8",
+    "mini-css-extract-plugin": "^2.10.2",
+    "postcss": "^8.5.29",
+    "postcss-loader": "^8.2.1",
+    "postcss-preset-env": "^11.6.1",
+    "react-refresh": "^0.19.0",
+    "swc-loader": "^0.2.7",
+    "webpack": "^5.111.1",
+    "webpack-bundle-analyzer": "^5.4.0",
+    "webpack-cli": "^7.2.3",
+    "webpack-dev-server": "^6.0.0"
   },
   "devDependencies": {
-    "@asd14/eslint-config": "^14.4.0",
-    "@asd14/prettier-config": "^1.1.0",
-    "@asd14/ts-config": "^1.1.0",
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
-    "@semantic-release/git": "^10.0.1",
+    "@asd14/eslint-config": "^15.4.0",
+    "@asd14/prettier-config": "^1.5.0",
+    "@asd14/semantic-release-config": "^1.0.1",
+    "@asd14/ts-config": "^1.6.0",
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
+    "@tailwindcss/postcss": "^4.3.3",
     "@types/dotenv-webpack": "^7.0.8",
     "@types/webpack-bundle-analyzer": "^4.7.0",
-    "conventional-changelog-conventionalcommits": "^9.1.0",
-    "eslint": "^9.35.0",
-    "prettier": "^3.6.2",
-    "semantic-release": "^24.2.8",
-    "typescript": "^5.9.2"
+    "@xyflow/react": "^12.12.0",
+    "eslint": "^9.39.5",
+    "prettier": "^3.9.10",
+    "semantic-release": "^25.0.9",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^22.22.3 || ^24.15.0 || >=26.0"
   }
 }

package/src/postcss.config.js

@@ -1,13 +1,13 @@
-export default {
+/**
+ * @param {{ mode: "production" | "development" | "none" }} api
+ */
+export default ({ mode }) => ({
   plugins: {
     "postcss-preset-env": {
       stage: 2,
     },
-    "tailwindcss": {
-      config: process.env["VB_TAILWIND_CONFIG"],
+    "cssnano": mode === "production" && {
+      preset: "default",
     },
-    // "cssnano": {
-    //   preset: "default",
-    // },
   },
-}
+})

package/src/types/client.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Types for the files `../webpack.config.js` teaches `import` to load.
+ *
+ * @example
+ * // tsconfig.json
+ * { "compilerOptions": { "types": ["@asd14/vblocks/client"] } }
+ */
+
+declare module "*.module.css" {
+  /**
+   * Class names by their camelCase key, `.my-class` is `styles.myClass`.
+   *
+   * Typed `any` so `styles.myClass` passes `noPropertyAccessFromIndexSignature`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const classNames: any
+
+  export default classNames
+}
+
+declare module "*.css" {}
+
+/**
+ * The URL of the image, a `data:` URL when the build inlines it.
+ */
+declare module "*.jpg" {
+  const url: string
+
+  export default url
+}
+
+declare module "*.gif" {
+  const url: string
+
+  export default url
+}
+
+declare module "*.png" {
+  const url: string
+
+  export default url
+}
+
+declare module "*.svg" {
+  const url: string
+
+  export default url
+}
+
+/**
+ * The URL of the font, a `data:` URL in a single-file build.
+ */
+declare module "*.woff" {
+  const url: string
+
+  export default url
+}
+
+declare module "*.woff2" {
+  const url: string
+
+  export default url
+}
+
+declare module "*.ttf" {
+  const url: string
+
+  export default url
+}
+
+declare module "*.eot" {
+  const url: string
+
+  export default url
+}
+
+/**
+ * The `.env` variables Webpack writes into the bundle. The browser has no
+ * other part of Node's `process`.
+ *
+ * @example
+ * const apiUrl = process.env["API_URL"]
+ */
+declare const process: {
+  env: Record<string, string | undefined>
+}

package/src/webpack.config.js

@@ -7,6 +7,7 @@ import CopyPlugin from "copy-webpack-plugin"
 import DotenvPlugin from "dotenv-webpack"
 import HtmlWebPackPlugin from "html-webpack-plugin"
 import MiniCssExtractPlugin from "mini-css-extract-plugin"
+import webpack from "webpack"
 import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer"
 
 const VB_SWC_CONFIG = process.env["VB_SWC_CONFIG"]
@@ -20,8 +21,10 @@ if (!VB_POSTCONFIG_PATH)
 
 /**
  * Load, parse and provide targets defaults for SWC configuration
+ *
+ * @param {{ hasReactRefresh: boolean }} options
  */
-const loadSwcConfig = () => {
+const loadSwcConfig = ({ hasReactRefresh }) => {
   const content = fs.readFileSync(VB_SWC_CONFIG, "utf8")
   const config = /** @type {unknown} */ (JSON.parse(content))
   const typedConfig = /** @type {import("@swc/core").Config} */ (config)
@@ -29,9 +32,22 @@ const loadSwcConfig = () => {
   return {
     ...typedConfig,
     env: {
-      targets: "> 0.25, not dead",
+      targets: "> 0.25%, not dead",
       ...typedConfig.env,
     },
+    jsc: {
+      ...typedConfig.jsc,
+      transform: {
+        ...typedConfig.jsc?.transform,
+        react: {
+          ...typedConfig.jsc?.transform?.react,
+          // SWC marks components and their hooks, `ReactRefreshWebpackPlugin`
+          // loads the runtime that reads the marks. One without the other
+          // breaks the page
+          ...(hasReactRefresh ? { development: true, refresh: true } : {}),
+        },
+      },
+    },
   }
 }
 
@@ -55,12 +71,83 @@ const createCssModuleConfig = isProduction => ({
   localIdentName: isProduction ? "[hash:base64:8]" : "[local]__[hash:base64:5]",
 })
 
+/**
+ * Replace every script, stylesheet and icon tag of the HTML with the content
+ * of the file it points at, then drop that file from the output.
+ *
+ * Lives in this file so an ejected config stays one file.
+ *
+ * @param {import("webpack").Compiler} compiler
+ */
+const inlineAssets = compiler => {
+  compiler.hooks.compilation.tap("inlineAssets", compilation => {
+    /** @param {string} name */
+    const takeAsset = name => {
+      const content = compilation.getAsset(name)?.source.source() ?? ""
+
+      compilation.deleteAsset(name)
+
+      return content
+    }
+
+    /** @param {import("html-webpack-plugin").HtmlTagObject} tag */
+    const inlineTag = tag => {
+      const { src, href, rel } = tag.attributes
+
+      if (tag.tagName === "script" && typeof src === "string")
+        return {
+          ...tag,
+          attributes: {},
+          // The HTML parser reads `</script` and `<!--` inside a script, a
+          // `\x3C` means the same `<` to JavaScript and nothing to the parser
+          innerHTML: takeAsset(src)
+            .toString()
+            .replaceAll("</script", String.raw`\x3C/script`)
+            .replaceAll("<!--", String.raw`\x3C!--`),
+        }
+
+      if (rel === "stylesheet" && typeof href === "string")
+        return {
+          ...tag,
+          tagName: "style",
+          voidTag: false,
+          attributes: {},
+          innerHTML: takeAsset(href)
+            .toString()
+            .replaceAll("</style", String.raw`<\/style`),
+        }
+
+      if (rel === "icon" && typeof href === "string")
+        return {
+          ...tag,
+          attributes: {
+            rel,
+            // `bin/vblocks.sh` only ever passes a `favicon.svg`
+            href: `data:image/svg+xml;base64,${Buffer.from(takeAsset(href)).toString("base64")}`,
+          },
+        }
+
+      return tag
+    }
+
+    HtmlWebPackPlugin.getHooks(compilation).alterAssetTagGroups.tap(
+      "inlineAssets",
+      data => ({
+        ...data,
+        headTags: data.headTags.map(tag => inlineTag(tag)),
+        bodyTags: data.bodyTags.map(tag => inlineTag(tag)),
+      })
+    )
+  })
+}
+
 /**
  * @typedef {Object} VBlocksEnvironment
  *
  * @property {string} entryDir - Target directory from where vblocks cmd was called
  * @property {string} robotsPath - Path to robots.txt copied to the output directory
  * @property {string} faviconPath - Path to favicon.ico copied to the output directory
+ * @property {boolean} [single] - Build one standalone index.html, every asset inlined
  */
 
 /**
@@ -74,10 +161,12 @@ const createCssModuleConfig = isProduction => ({
  * @param {VBlocksProps} props
  * @returns {WebpackConfiguration}
  */
-export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
+export default ({ entryDir, robotsPath, faviconPath, single }, { mode }) => {
   const isProduction = mode === "production"
   const isServe = process.argv[2] == "serve"
-  const swcConfig = loadSwcConfig()
+  const isSingle = Boolean(single) && !isServe
+  const hasReactRefresh = isServe && mode === "development"
+  const swcConfig = loadSwcConfig({ hasReactRefresh })
   const commonPostCSSConfigs = createCssModuleConfig(isProduction)
 
   const paths = {
@@ -102,7 +191,8 @@ export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
     mode: mode,
 
     output: {
-      publicPath: "/",
+      // A standalone file opens from disk, where "/" is the filesystem root
+      publicPath: isSingle ? "" : "/",
       path: paths.output,
       // Cannot use 'contenthash' when hot reloading is enabled.
       filename: isServe ? "js/[name].js" : "js/[name].[contenthash].js",
@@ -201,19 +291,27 @@ export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
         },
         {
           test: /\.(jpg|gif|png|svg)$/,
-          type: "asset",
-          parser: {
-            dataUrlCondition: {
-              maxSize: 10 * 1024,
-            },
-          },
+          ...(isSingle
+            ? { type: "asset/inline" }
+            : {
+                type: "asset",
+                parser: {
+                  dataUrlCondition: {
+                    maxSize: 10 * 1024,
+                  },
+                },
+              }),
         },
         {
           test: /\.(woff|woff2|ttf|eot)$/,
-          type: "asset/resource",
-          generator: {
-            filename: "fonts/[name][ext]",
-          },
+          ...(isSingle
+            ? { type: "asset/inline" }
+            : {
+                type: "asset/resource",
+                generator: {
+                  filename: "fonts/[name][ext]",
+                },
+              }),
         },
       ],
     },
@@ -243,6 +341,9 @@ export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
       new HtmlWebPackPlugin({
         template: paths.htmlTemplate,
         favicon: paths.favicon,
+        // An inline script ignores `defer` and runs where it stands, so it
+        // must stand after the element the app renders into
+        inject: isSingle ? "body" : "head",
       }),
 
       new MiniCssExtractPlugin({
@@ -253,21 +354,27 @@ export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
         path: paths.dotenv,
       }),
 
-      new CopyPlugin({
-        patterns: [
-          {
-            from: paths.robots,
-            to: "robots.txt",
-          },
-        ],
-      }),
+      !isSingle &&
+        new CopyPlugin({
+          patterns: [
+            {
+              from: paths.robots,
+              to: "robots.txt",
+            },
+          ],
+        }),
+
+      // A dynamic `import()` would otherwise emit a second file
+      isSingle && new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
+
+      isSingle && inlineAssets,
 
       isServe &&
         new BundleAnalyzerPlugin({
           openAnalyzer: false,
         }),
 
-      isServe && new ReactRefreshWebpackPlugin(),
+      hasReactRefresh && new ReactRefreshWebpackPlugin(),
     ].filter(Boolean),
 
     resolve: {
@@ -285,7 +392,7 @@ export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
       runtimeChunk: false,
 
       // Extract node_module dependencies into a separate chunk for better caching
-      splitChunks: {
+      splitChunks: !isSingle && {
         chunks: "all",
         cacheGroups: {
           react: {
@@ -305,7 +412,8 @@ export default ({ entryDir, robotsPath, faviconPath }, { mode }) => {
     },
 
     performance: {
-      hints: isProduction ? "warning" : false,
+      // A standalone file is over the size limit by design
+      hints: isProduction && !isSingle ? "warning" : false,
     },
   }
 }

package/template/_common/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.env

package/template/_common/src/index.css

@@ -0,0 +1,4 @@
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+}