common/hexec: Make NODE_PATH a fallback for ESM bare imports

Node's ESM resolver does not consult NODE_PATH (unlike CJS require), so
an ESM postcss.config.js shipped by a Hugo theme fails when loaded from
the module cache: bare imports like `import x from "postcss-import"`
have no node_modules to walk up to.

Install a synchronous resolver hook (module.registerHooks) via
--import=data:... on every Node invocation. On ERR_MODULE_NOT_FOUND for
a bare specifier it resolves the package from each NODE_PATH entry via
createRequire().resolve(). No-op for relative, absolute, URL-scheme and
non-MODULE_NOT_FOUND failures. Synchronous hooks run on the main thread,
so no --allow-worker is needed under the Node permission model.

Fixes #13987

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

common/hexec/esmloader.go

@@ -0,0 +1,30 @@
+// Copyright 2026 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package hexec
+
+import (
+	_ "embed"
+	"encoding/base64"
+	"sync"
+)
+
+//go:embed esmloader.mjs
+var esmLoaderSource string
+
+// nodeESMLoaderImportArg returns a "--import=data:..." argument that installs
+// a Node.js ESM resolver hook making NODE_PATH a fallback for failed bare
+// imports. See esmloader.mjs for the rationale.
+var nodeESMLoaderImportArg = sync.OnceValue(func() string {
+	return "--import=data:text/javascript;base64," + base64.StdEncoding.EncodeToString([]byte(esmLoaderSource))
+})

common/hexec/esmloader.mjs

@@ -0,0 +1,52 @@
+// Node.js ESM resolver hook installed by Hugo.
+//
+// Node's ESM resolver does not consult NODE_PATH, unlike CJS require().
+// That breaks postcss.config.js / babel.config.js / etc. files written in
+// ESM and loaded from outside the project tree (typically the Hugo module
+// cache): bare imports like `import x from "postcss-import"` cannot be
+// resolved by walking up from the file's location.
+//
+// This hook makes the ESM resolver fall back to NODE_PATH for bare
+// specifiers when Node's normal resolution fails. It is a no-op for
+// relative/absolute paths and URL-scheme specifiers, and it never fires
+// unless Node would itself have thrown ERR_MODULE_NOT_FOUND.
+//
+// Uses the synchronous registerHooks API so it runs on the main thread and
+// does not require --allow-worker under the Node permission model.
+
+import { registerHooks, createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const resolvers = [];
+const np = process.env.NODE_PATH;
+if (np) {
+	const sep = process.platform === 'win32' ? ';' : ':';
+	for (const p of np.split(sep)) {
+		if (p) resolvers.push(createRequire(p + '/_'));
+	}
+}
+
+function isBareSpecifier(s) {
+	if (!s) return false;
+	if (s.startsWith('.') || s.startsWith('/') || s.startsWith('#')) return false;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(s)) return false;
+	return true;
+}
+
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		try {
+			return nextResolve(specifier, context);
+		} catch (err) {
+			if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err;
+			if (!isBareSpecifier(specifier)) throw err;
+			for (const r of resolvers) {
+				try {
+					const resolved = r.resolve(specifier);
+					return { url: pathToFileURL(resolved).href, shortCircuit: true, format: null };
+				} catch (_) { /* try next */ }
+			}
+			throw err;
+		}
+	},
+});

common/hexec/exec.go

@@ -234,6 +234,10 @@ func (e *Exec) newNode(name, scriptPath string, arg ...any) (Runner, error) {
 	for _, pa := range e.nodePermissionArgs(name, scriptPath) {
 		allArgs = append(allArgs, pa)
 	}
+	// Install an ESM resolver hook that makes NODE_PATH a fallback for failed
+	// bare imports, so postcss.config.js / babel.config.js / etc. written in
+	// ESM work when loaded from the Hugo module cache. See esmloader.mjs.
+	allArgs = append(allArgs, nodeESMLoaderImportArg())
 	allArgs = append(allArgs, scriptPath)
 	allArgs = append(allArgs, arg...)
 	// When the script lives outside the working dir (a globally installed

resources/resource_transformers/cssjs/postcss_integration_test.go

@@ -15,6 +15,7 @@ package cssjs_test
 
 import (
 	"fmt"
+	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -214,3 +215,73 @@ Styles Content: Len: 770917
 
 	}
 }
+
+// See Issue 13987.
+func TestTransformPostCSSESMConfigInModule(t *testing.T) {
+	if !htesting.IsCI() {
+		t.Skip("Skip long running test when running locally")
+	}
+
+	c := qt.New(t)
+	// Use htesting.CreateTempDir to get canonical paths on macOS
+	// (/private/var/...); Node's --permission model rejects the symlinked
+	// /var/folders/... form when crossing the project boundary.
+	rootDir, clean, err := htesting.CreateTempDir(hugofs.Os, "hugo-integration-test")
+	c.Assert(err, qt.IsNil)
+	c.Cleanup(clean)
+
+	projectDir := filepath.Join(rootDir, "project")
+	moduleDir := filepath.Join(rootDir, "external-module")
+	c.Assert(os.MkdirAll(projectDir, 0o755), qt.IsNil)
+	c.Assert(os.MkdirAll(moduleDir, 0o755), qt.IsNil)
+
+	files := `
+-- hugo.toml --
+disableKinds = ['taxonomy', 'term', 'page']
+baseURL = "https://example.com"
+[[module.imports]]
+path = "github.com/bep/hugo-mod-nop"
+-- assets/css/styles.css --
+body { color: red }
+-- layouts/home.html --
+{{ $styles := resources.Get "css/styles.css" | css.PostCSS }}
+RelPermalink: {{ $styles.RelPermalink }}|HasBody: {{ in $styles.Content "color:" }}|
+-- content/_index.md --
+---
+title: home
+---
+-- package.json --
+{
+  "devDependencies": {
+    "postcss-cli": "11.0.0",
+    "postcss-import": "16.0.0"
+  }
+}
+-- go.mod --
+module github.com/example/project
+
+go 1.20
+
+replace github.com/bep/hugo-mod-nop => ../external-module
+-- ../external-module/go.mod --
+module github.com/bep/hugo-mod-nop
+
+go 1.20
+-- ../external-module/postcss.config.js --
+import postcssImport from "postcss-import";
+export default { plugins: [postcssImport()] };
+
+`
+
+	b := hugolib.Test(c, files,
+		hugolib.TestOptWithConfig(func(cfg *hugolib.IntegrationTestConfig) {
+			cfg.WorkingDir = projectDir
+			cfg.NeedsOsFS = true
+			cfg.NeedsNpmInstall = true
+		}),
+	)
+
+	b.AssertFileContent("public/index.html",
+		"RelPermalink: /css/styles.css|HasBody: true|",
+	)
+}