canopy-webpack-config 4.4.5 → 4.5.0

package/README.md

@@ -1,19 +1,24 @@
 # canopy-webpack-config
+
 Some defaults for webpack configs at Canopy.
 
 ## Goals
+
 - Ensure webpack externals for common dependencies are correct. This ensures smaller bundle sizes.
 - Provide some defaults for people implementing sofe services.
 - Still be 100% overrideable.
 
 ## Things we don't want
+
 - Hiding webpack configs at a level comparable to create-react-app or angular-cli. Nothing will need to be "ejected," you can always override anything you want.
 - Discouraging people from experimenting with their webpack config.
 - Discouraging people from knowing webpack.
 - Being overly opininated about how you do things like css (or other "autonomy" areas of building a sofe service).
 
 ## Usage
+
 First, install the library as a devDependency.
+
 ```bash
 yarn add --dev canopy-webpack-config @babel/runtime @babel/plugin-transform-runtime
 ```
@@ -24,17 +29,17 @@ file, call the `canopyWebpackConfig()` function to get some defaults and add/ove
 ```js
 // webpack.config.js
 
-const canopyWebpackConfig = require('canopy-webpack-config');
+const canopyWebpackConfig = require("canopy-webpack-config");
 
-module.exports = canopyWebpackConfig('login-ui', {
+module.exports = canopyWebpackConfig("login-ui", {
   // Override or add anything you want to your webpack config
   module: {
     rules: [
       // e.g. apply a css loader if using css-modules
-      { loader: 'css-loader' },
+      { loader: "css-loader" },
     ],
   },
-})
+});
 ```
 
 Finally, create the following `scripts` in your package.json:
@@ -55,6 +60,7 @@ Now add `yarn build` to your `.gitlab-ci.yml` file for the build step. You can r
 will start up a web server that is ready to go as a sofe override.
 
 ## API
+
 - `canopyWebpackConfig(name, config)`: The default export of the canopy-webpack-config npm library. This function requires both of its arguments.
   The first argument is a string name for the library you are exporting. The second is a webpack config that will be merged with the defaults that
   canopy-webpack-config provides. The library will put the bundled files into the "build" directory. Note that this project assumes that you use
@@ -67,10 +73,13 @@ will start up a web server that is ready to go as a sofe override.
   needing to do anything.
 
 ## Debugging
+
 To see your full webpack config, simply add a `--env.debug` to your webpack cli command.
 
 ## Features and assumptions
+
 canopy-webpack-config assumes a few things about your project and provides defaults for those things:
+
 - It automatically uses babel-loader to compile js files.
 - It compiles your library to AMD format
 - It compiles your code into the `build` directory relative to where you started the webpack process.
@@ -78,20 +87,49 @@ canopy-webpack-config assumes a few things about your project and provides defau
 - Requires webpack-dev-server >= 3.4.0
 
 ## Limitations
+
 the webpack config for canopy-webpack-config will always create the output bundle in the directory that the webpack process was started in. This
 is different than how webpack configs normally work -- they usually create the output bundle in relation to the directory in which the webpack config
 file is placed.
 
 ## Optional modifiers
+
 We support a few config options for builds, including typescript and an externals submodule.
+
 ```
 module.exports = canopyWebpackConfig('login-ui', {}, {
   typescript: true,
   externals: true
 })
 ```
+
 ### Typescript `<bool>`
+
 Pass an options object with `{typescript: true}` when your service uss typescript.
 
 ### Externals `<bool>`
+
 Pass an options object with `{externals: true}` when you are looking to export a submodule from `/src/externals.{js|ts}`. This should be for exports that must be imported synchronously such as hooks or queries that do not have other internal dependencies (to avoid circular dependencies).
+
+### Tailwind `<object>`
+
+Pass `{ tailwind: { prefix: '<service_prefix>' } }` and import the stylesheet in your app entry:
+
+Use https://github.com/CanopyTax/frontend-docs/wiki/Repo-abbreviations to get the correct prefix for the service.
+
+```js
+// webpack.config.js
+module.exports = canopyWebpackConfig(
+  "<service_name>",
+  {},
+  {
+    typescript: true,
+    tailwind: { prefix: "ru" },
+  },
+);
+```
+
+```js
+// src/<service_name>.ts
+import "canopy-webpack-config/tailwind.css";
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "canopy-webpack-config",
-  "version": "4.4.5",
+  "version": "4.5.0",
   "description": "Some defaults for webpack configs at canopy",
   "main": "src/canopy-webpack-config.js",
   "exports": {
     ".": "./src/canopy-webpack-config.js",
-    "./esm": "./src/canopy-webpack-config-esm.mjs"
+    "./esm": "./src/canopy-webpack-config-esm.mjs",
+    "./tailwind.css": "./src/tailwind/base.css"
   },
   "repository": "git@github.com:CanopyTax/canopy-webpack-config.git",
   "license": "Apache-2.0",
@@ -17,7 +18,13 @@
     "prettier": "^3.6.2"
   },
   "dependencies": {
+    "@tailwindcss/postcss": "4.3.3",
     "clean-webpack-plugin": "^4.0.0",
+    "css-loader": "^7.1.2",
+    "postcss": "^8.4.49",
+    "postcss-loader": "^8.1.1",
+    "style-loader": "^4.0.0",
+    "tailwindcss": "4.3.3",
     "url": "^0.11.0",
     "webpack-bundle-analyzer": "^4.7.0",
     "webpack-merge": "^4.2.1"

package/src/canopy-webpack-config-esm.mjs

@@ -4,6 +4,7 @@ import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
 import merge from "webpack-merge";
 import fs from "fs";
 import os from "os";
+import { tailwindSupport } from "./tailwind/index.js";
 
 const homedir = os.homedir();
 
@@ -49,7 +50,7 @@ const externalPatterns = [
 ];
 
 export default function (name, overridesConfig = {}, options = {}) {
-  const { externals: hasExternals } = options;
+  const { externals: hasExternals, tailwind } = options;
 
   if (typeof name !== "string") {
     throw new Error(
@@ -66,6 +67,12 @@ export default function (name, overridesConfig = {}, options = {}) {
     );
   }
 
+  const {
+    rules: tailwindRules,
+    plugins: tailwindPlugins,
+    alias: tailwindAlias,
+  } = tailwindSupport(tailwind);
+
   return function (env = {}) {
     const defaultCanopyConfig = {
       mode: env.dev || isDevServer ? "development" : "production",
@@ -122,6 +129,7 @@ export default function (name, overridesConfig = {}, options = {}) {
         fullySpecified: false,
         extensions: [".tsx", ".ts", ".js", ".jsx", ".json"],
         modules: [process.cwd(), "node_modules"],
+        alias: tailwindAlias,
       },
 
       module: {
@@ -131,6 +139,7 @@ export default function (name, overridesConfig = {}, options = {}) {
             exclude: /node_modules/,
             use: "babel-loader",
           },
+          ...tailwindRules,
         ],
       },
 
@@ -138,6 +147,7 @@ export default function (name, overridesConfig = {}, options = {}) {
         new CleanWebpackPlugin({
           cleanOnceBeforeBuildPatterns: ["**/*", "!.gitkeep"],
         }),
+        ...tailwindPlugins,
         env.analyze === "server" &&
           new BundleAnalyzerPlugin({ analyzerMode: "server" }),
         env.analyze === "static" &&

package/src/canopy-webpack-config.js

@@ -5,6 +5,7 @@ const BundleAnalyzerPlugin =
 const merge = require("webpack-merge");
 const fs = require("fs");
 const homedir = require("os").homedir();
+const { tailwindSupport } = require("./tailwind/index.js");
 
 let isDevServer = false;
 
@@ -25,7 +26,7 @@ const port =
     : "8080";
 
 module.exports = function (name, overridesConfig = {}, options = {}) {
-  const { typescript, externals } = options;
+  const { typescript, externals, tailwind } = options;
   if (typeof name !== "string") {
     throw new Error(
       "canopy-webpack-config expects a string name as the first argument",
@@ -42,6 +43,12 @@ module.exports = function (name, overridesConfig = {}, options = {}) {
     );
   }
 
+  const {
+    rules: tailwindRules,
+    plugins: tailwindPlugins,
+    alias: tailwindAlias,
+  } = tailwindSupport(tailwind);
+
   return function (env) {
     if (!env) {
       env = {};
@@ -81,6 +88,7 @@ module.exports = function (name, overridesConfig = {}, options = {}) {
               ],
             },
           },
+          ...tailwindRules,
         ],
       },
       resolve: {
@@ -90,6 +98,7 @@ module.exports = function (name, overridesConfig = {}, options = {}) {
             }
           : {}),
         modules: [process.cwd(), "node_modules"],
+        alias: tailwindAlias,
         fallback: {
           url: require.resolve("url/"),
           "react/jsx-runtime": "react/jsx-runtime.js",
@@ -101,6 +110,7 @@ module.exports = function (name, overridesConfig = {}, options = {}) {
         new BundleAnalyzerPlugin({
           analyzerMode: env.analyze || "disabled",
         }),
+        ...tailwindPlugins,
       ],
       devtool: "source-map",
       externals: [

package/src/tailwind/base.css

@@ -0,0 +1,18 @@
+/*
+ * The shared half of every Canopy app's Tailwind entry.
+ *
+ * canopy-webpack-config copies this file into a generated per-repo entry, underneath the
+ * two prefixed Tailwind `@import` lines (theme + utilities) that only the generator can write.
+ *
+ * Use only bare package specifiers here. The generated entry lives in the consuming repo's
+ * node_modules/.cache, and these imports resolve from there (e.g. @canopytax/understory).
+ */
+
+/* Shared Canopy design system tokens */
+@import "@canopytax/understory/tailwind/theme.css";
+
+/* 10px base font rem recalculation */
+@plugin "@canopytax/understory/tailwind/base-font-size";
+
+/* Dark mode variant (same selector as understory) */
+@custom-variant dark (&:is(:root.dark *, [data-mode="dark"] *));

package/src/tailwind/index.js

@@ -0,0 +1,250 @@
+const fs = require("fs");
+const path = require("path");
+
+const PLUGIN_NAME = "CanopyTailwindCandidatesPlugin";
+const CACHE_DIR = "node_modules/.cache/canopy-tailwind";
+// Deliberately not `.css`. Every repo has a `{ test: /\.css$/, include: [node_modules] }`
+// rule, and webpack applies every matching rule, so a generated `.css` in here would pick
+// up a second loader chain alongside ours and ship unprocessed Tailwind directives.
+const ENTRY_FILE = "entry.tailwind";
+const CANDIDATES_FILE = "candidates";
+const BASE_CSS = path.resolve(__dirname, "base.css");
+
+// tailwindcss is our dependency, not the consuming repo's, so the entry cannot reach it
+// with a bare specifier — the entry resolves from the repo's node_modules, where it may
+// not be hoisted. An absolute path produces byte-identical output and always resolves.
+const TAILWIND_CSS_DIR = path.dirname(
+  require.resolve("tailwindcss/package.json"),
+);
+
+// What a consumer writes in their app entry. Aliased to the generated file below.
+const PUBLIC_SPECIFIER = "canopy-webpack-config/tailwind.css";
+
+const DEFAULT_SOURCES = ["src/**/*.{js,jsx,ts,tsx}"];
+
+// Tailwind's built-in prefix only generates a utility when the prefixed candidate
+// appears literally in a scanned file. Our tw() helper composes the prefix at runtime,
+// so the scanner never sees it. We run Tailwind's own extractor ourselves, prepend the
+// prefix to everything it finds, and hand the result back through @source.
+//
+// oxide is a native binary pinned to an exact version by @tailwindcss/postcss, and the
+// extraction has to match the Tailwind that actually builds the CSS. Both are our
+// dependencies now, so resolving from here is what guarantees they agree.
+function loadScanner() {
+  try {
+    return require("@tailwindcss/oxide").Scanner;
+  } catch (err) {
+    throw new Error(
+      `${PLUGIN_NAME}: could not load @tailwindcss/oxide. It ships with our own ` +
+        `@tailwindcss/postcss, so this is a broken canopy-webpack-config install — on ` +
+        `CI more often a missing platform binary than a missing package; see the cause.`,
+      { cause: err },
+    );
+  }
+}
+
+function buildEntry(prefix, extendPath) {
+  let base;
+  try {
+    base = fs.readFileSync(BASE_CSS, "utf8");
+  } catch (err) {
+    throw new Error(
+      `${PLUGIN_NAME}: could not read the shared Tailwind base at ${BASE_CSS}. This is ` +
+        `a broken canopy-webpack-config install, not a problem with your repo.`,
+      { cause: err },
+    );
+  }
+
+  return [
+    `/* Generated by canopy-webpack-config on every build — edits here are lost.`,
+    ` * Change the \`tailwind\` option in your webpack config, or src/tailwind/base.css`,
+    ` * in canopy-webpack-config for boilerplate every app shares. */`,
+    ``,
+    `@import "${TAILWIND_CSS_DIR}/theme.css" prefix(${prefix});`,
+    `@import "${TAILWIND_CSS_DIR}/utilities.css" prefix(${prefix});`,
+    ``,
+    base.trim(),
+    ``,
+    // Absolute so it does not depend on where the repo-specific file sits.
+    ...(extendPath ? [`@import "${extendPath}";`, ``] : []),
+    `@source "./${CANDIDATES_FILE}";`,
+    ``,
+  ].join("\n");
+}
+
+class TailwindCandidatesPlugin {
+  constructor(options = {}) {
+    const {
+      prefix,
+      context = process.cwd(),
+      sources = DEFAULT_SOURCES,
+      extend,
+    } = options;
+
+    if (typeof prefix !== "string" || !prefix) {
+      throw new Error(
+        `${PLUGIN_NAME}: \`prefix\` is required, e.g. { prefix: "ru" }`,
+      );
+    }
+
+    this.prefix = prefix;
+    this.context = context;
+    this.sources = sources;
+    this.extendPath = extend ? path.resolve(context, extend) : null;
+    this.cacheDir = path.resolve(context, CACHE_DIR);
+    this.entryPath = path.join(this.cacheDir, ENTRY_FILE);
+    this.candidatesPath = path.join(this.cacheDir, CANDIDATES_FILE);
+  }
+
+  // Rewriting an unchanged file would invalidate the Tailwind entry on every compile and
+  // loop the dev server.
+  writeIfChanged(filePath, contents) {
+    let previous;
+    try {
+      previous = fs.readFileSync(filePath, "utf8");
+    } catch (err) {
+      if (err && err.code === "ENOENT") {
+        previous = null;
+      } else {
+        throw err;
+      }
+    }
+
+    if (previous === contents) return false;
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, contents);
+    return true;
+  }
+
+  generate() {
+    if (this.extendPath && !fs.existsSync(this.extendPath)) {
+      throw new Error(
+        `${PLUGIN_NAME}: \`tailwind.extend\` points at ${this.extendPath}, which does ` +
+          `not exist.`,
+      );
+    }
+
+    const Scanner = loadScanner();
+    const scanner = new Scanner({
+      sources: this.sources.map((pattern) => ({
+        base: this.context,
+        pattern,
+        negated: false,
+      })),
+    });
+
+    const candidates = scanner.scan();
+
+    if (candidates.length === 0) {
+      throw new Error(
+        `${PLUGIN_NAME}: found no Tailwind candidates under ${this.sources.join(", ")}. ` +
+          `Building it would produce an empty stylesheet.`,
+      );
+    }
+
+    // Everything the extractor found gets the prefix
+    const contents =
+      candidates.map((c) => `${this.prefix}:${c}`).join("\n") + "\n";
+
+    const changed = this.writeIfChanged(this.candidatesPath, contents);
+    this.writeIfChanged(
+      this.entryPath,
+      buildEntry(this.prefix, this.extendPath),
+    );
+
+    return { count: candidates.length, files: scanner.files, changed };
+  }
+
+  apply(compiler) {
+    // beforeCompile lands before any module is resolved or built, so both generated
+    // files are on disk by the time webpack resolves the alias and postcss-loader reads the entry
+    compiler.hooks.beforeCompile.tap(PLUGIN_NAME, () => {
+      this.lastError = null;
+      try {
+        this.lastRun = this.generate();
+      } catch (err) {
+        this.lastError = err;
+        if (!compiler.watchMode) throw err;
+      }
+    });
+
+    compiler.hooks.afterCompile.tap(PLUGIN_NAME, (compilation) => {
+      if (this.lastError) {
+        compilation.errors.push(this.lastError);
+        return;
+      }
+
+      const run = this.lastRun;
+      if (!run) return;
+
+      // @tailwindcss/postcss reports the candidates file as a dependency and
+      // postcss-loader forwards it, so edits to a file already in the graph rebuild on
+      // their own. Registering the scanned files and their roots covers additions and
+      // deletions.
+      for (const file of run.files) {
+        compilation.fileDependencies.add(file);
+      }
+      for (const pattern of this.sources) {
+        compilation.contextDependencies.add(
+          path.resolve(this.context, pattern.split("*")[0]),
+        );
+      }
+      if (this.extendPath) {
+        compilation.fileDependencies.add(this.extendPath);
+      }
+
+      compilation
+        .getLogger(PLUGIN_NAME)
+        .info(
+          `${run.changed ? "wrote" : "reused"} ${run.count} prefixed candidates ` +
+            `(${this.prefix}:) from ${run.files.length} files`,
+        );
+    });
+  }
+}
+
+function tailwindRule(entryPath) {
+  return {
+    test: (resource) => resource === entryPath,
+    use: [
+      { loader: require.resolve("style-loader") },
+      { loader: require.resolve("css-loader") },
+      {
+        loader: require.resolve("postcss-loader"),
+        options: {
+          postcssOptions: { plugins: [require("@tailwindcss/postcss")] },
+        },
+      },
+    ],
+  };
+}
+
+// Returns the rule, plugin and alias a consuming config needs, or empty ones when the
+// repo has not opted in.
+function tailwindSupport(tailwind) {
+  if (!tailwind) {
+    return { rules: [], plugins: [], alias: {} };
+  }
+
+  const plugin = new TailwindCandidatesPlugin(tailwind);
+
+  return {
+    rules: [tailwindRule(plugin.entryPath)],
+    plugins: [plugin],
+    // `$` makes this an exact match, so it only ever catches the stylesheet import.
+    alias: { [`${PUBLIC_SPECIFIER}$`]: plugin.entryPath },
+  };
+}
+
+module.exports = {
+  TailwindCandidatesPlugin,
+  tailwindRule,
+  tailwindSupport,
+  buildEntry,
+  BASE_CSS,
+  CACHE_DIR,
+  ENTRY_FILE,
+  CANDIDATES_FILE,
+  PUBLIC_SPECIFIER,
+};