Add saving local transformed styles and skip bundling features

Author: jaredcwhite

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 dist
 test/fixture/out.*
+*.css-local

README.md

@@ -83,6 +83,8 @@ htmlModulesPlugin({
   experimental: {
     extractGlobalStyles: true,
     extractScopedStyles: true,
+    exportLocalStylesExtension: "css-local",
+    skipBundlingFilter: /\.tmpl\.html$/,
     transformLocalStyles: async (css, { filePath }) => {
       const postCssConfig = await postcssrc()
       const postCssProcessor = postcss([...postCssConfig.plugins])
@@ -102,6 +104,14 @@ If you define `extractScopedStyles: true`, then any `style` tag featuring a `sco
 
 If you define a `transformLocalStyles` function, then any local style tag contained within your HTML (not explicitly scoped) will have its contents transformed by the function. Above you can see this done using PostCSS, but you could use another processor such as Sass if you prefer. This is useful for style tags which get included in shadow DOM templates (and you wouldn't want to include those styles in the CSS bundle).
 
+## Bundling Lifecycle
+
+As part of transforming local styles, you can optionally export those transformed styles into "sidecar" CSS output file. This can be helpful if you would like another process to use those styles in SSR. By setting the `exportLocalStylesExtension` option, a file with the provided extension will be saved right alongside the HTML module.
+
+You can also specify a filename filter for HTML modules you do _not_ wish to include in esbuild's bundled JS output. This will effectively set their exported default template to a blank fragment and ignore all script tags. You would want to do this for HTML modules which are intended purely for SSR and are not designed for inclusion in a frontend JS bundle. In the `skipBundlingFilter: /\.tmpl\.html$/` example above, any HTML module ending in the double extension `.tmpl.html` will be skipped in this fashion.
+
+**Note:** this does _not_ skip the styles processing. Any local style tags will still be transformed if those options have been set, and any scoped or global styles will be extracted if those options have been set.
+
 ## Testing
 
 Run:

index.js

@@ -2,6 +2,7 @@ const fsLib = require("fs")
 const fs = fsLib.promises
 
 const { parse } = require("node-html-parser")
+const path = require("path")
 
 module.exports = (options = {}) => ({
   name: "htmlmodules",
@@ -17,7 +18,7 @@ module.exports = (options = {}) => ({
       const root = parse(results)
 
       const scriptTags = root.getElementsByTagName("script")
-      scriptTags.forEach(node => {
+      scriptTags.forEach((node) => {
         if (node.getAttribute("type") === "module") {
           scripts.push(node.rawText)
         }
@@ -26,7 +27,7 @@ module.exports = (options = {}) => ({
 
       let globalCSS = ""
       if (options.experimental?.extractGlobalStyles) {
-        root.querySelectorAll("style[scope=global]").forEach(styleTag => {
+        root.querySelectorAll("style[scope=global]").forEach((styleTag) => {
           globalCSS += `${styleTag.textContent}\n`
           styleTag.remove()
         })
@@ -36,14 +37,14 @@ module.exports = (options = {}) => ({
         const styleTransform = await import("@enhance/enhance-style-transform")
         const transform = styleTransform.default
 
-        root.querySelectorAll("style[scope]").forEach(styleTag => {
+        root.querySelectorAll("style[scope]").forEach((styleTag) => {
           const scope = styleTag.getAttribute("scope")
           const styles = styleTag.textContent
 
           styleTag.textContent = transform({
             tagName: scope,
-            context: 'markup',
-            raw: styles
+            context: "markup",
+            raw: styles,
           })
 
           globalCSS += `${styleTag.textContent}\n`
@@ -53,36 +54,63 @@ module.exports = (options = {}) => ({
 
       const styleTags = root.getElementsByTagName("style")
 
+      let styleExports = ""
       await Promise.all(
         styleTags.map(async (styleTag) => {
           if (options.experimental?.transformLocalStyles) {
-            const transformedCSS = await options.experimental.transformLocalStyles(styleTag.textContent, { filePath: args.path })
+            const transformedCSS = await options.experimental.transformLocalStyles(
+              styleTag.textContent,
+              { filePath: args.path }
+            )
             styleTag.textContent = transformedCSS
+            if (options.experimental?.exportLocalStylesExtension) {
+              styleExports += transformedCSS
+            }
           }
         })
       )
+      if (styleExports.length > 0) {
+        const basepath = path.join(
+          path.dirname(args.path),
+          path.basename(args.path, path.extname(args.path))
+        )
+        await fs.writeFile(
+          `${basepath}.${options.experimental.exportLocalStylesExtension}`,
+          styleExports
+        )
+      }
 
       const scriptContent = scripts.join("")
-      removeNodes.forEach(node => node.remove())
+      removeNodes.forEach((node) => node.remove())
 
       const htmlFragment = root.toString()
 
       let wrapper = globalCSS.length > 0 ? `import "data:text/css,${encodeURI(globalCSS)}"\n` : ""
 
-      wrapper += `
-        var import_meta_document = new DocumentFragment()
-        const htmlFrag = "<body>" + ${JSON.stringify(htmlFragment)} + "</body>"
-        const fragment = new DOMParser().parseFromString(htmlFrag, 'text/html')
-        import_meta_document.append(...fragment.body.childNodes)
-
-        ${scriptContent.replace(/import[\s]*?\.meta[\s]*?\.document/g, "import_meta_document")}
-        export default import_meta_document
-      `
+      if (
+        options.experimental?.skipBundlingFilter &&
+        args.path.match(options.experimental.skipBundlingFilter)
+      ) {
+        // we'll export nothing
+        wrapper += `
+          export default new DocumentFragment()
+        `
+      } else {
+        wrapper += `
+          var import_meta_document = new DocumentFragment()
+          const htmlFrag = "<body>" + ${JSON.stringify(htmlFragment)} + "</body>"
+          const fragment = new DOMParser().parseFromString(htmlFrag, 'text/html')
+          import_meta_document.append(...fragment.body.childNodes)
+
+          ${scriptContent.replace(/import[\s]*?\.meta[\s]*?\.document/g, "import_meta_document")}
+          export default import_meta_document
+        `
+      }
 
       return {
         contents: wrapper,
-        loader: "js"
+        loader: "js",
       }
     })
-  }
+  },
 })

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "esbuild-plugin-html-modules",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "An esbuild plugin to load HTML modules",
   "main": "index.js",
   "scripts": {
@@ -24,5 +24,10 @@
   "dependencies": {
     "@enhance/enhance-style-transform": "^0.0.1",
     "node-html-parser": "^5.4.2"
+  },
+  "prettier": {
+    "semi": false,
+    "singleQuote": false,
+    "printWidth": 100
   }
 }

package.json

@@ -17,13 +17,15 @@ esbuild.build({
       experimental: {
         extractGlobalStyles: true,
         extractScopedStyles: true,
+        exportLocalStylesExtension: "css-local",
+        skipBundlingFilter: /\.tmpl\.html$/,
         transformLocalStyles: async (css, { filePath }) => {
           const postCssConfig = await postcssrc()
           const postCssProcessor = postcss([...postCssConfig.plugins])
 
           const results = await postCssProcessor.process(css, { ...postCssConfig.options, from: filePath })
           return results.css
-        }
+        },
       }
     })
   ]

test/fixture/esbuild.config.js

@@ -1,7 +1,9 @@
 import HelloWorld, { howdy, yo } from "./hello-world.html" assert { type: "html" }
+import Nothing from "./ssr-only.tmpl.html" assert { type: "html" }
 
 window.testing = {
   HelloWorld,
   howdy,
-  yo
+  yo,
+  Nothing
 }

test/fixture/main.js

@@ -0,0 +1,19 @@
+<p>This should all get completely ignored!</p>
+
+<script type="module">
+  This should also get ignored!
+</script>
+
+<style>
+  .nest {
+    & .me {
+      --only-this-will-work: var(--value);
+    }
+  }
+</style>
+
+<style scope="global">
+  :root {
+    --root-of-the-matter: var(--indeed);
+  }
+</style>

test/fixture/ssr-only.tmpl.html

@@ -46,4 +46,14 @@ test('global CSS bundled', (t) => {
 
   assert.match(css, /tag-name > h1/)
   assert.match(css, /tag-name > p\[slot=here\]/)
+
+  assert.match(css, /--root-of-the-matter: var\(--indeed\)/)
+})
+
+test('ssr only output', (t) => {
+  const testing = processBundle()
+  const sidecarCSS = readFileSync("test/fixture/ssr-only.tmpl.css-local").toString()
+
+  assert.match(sidecarCSS, /\.nest \.me/)
+  assert.equal(testing.Nothing.children.length, 0)
 })