Add css.Build

Fixes #14609

Author: bep

internal/js/esbuild/batch.go

@@ -72,7 +72,7 @@ var (
 func NewBatcherClient(deps *deps.Deps) (js.BatcherClient, error) {
 	c := &BatcherClient{
 		d:            deps,
-		buildClient:  NewBuildClient(deps.BaseFs.Assets, deps.ResourceSpec),
+		buildClient:  NewBuildClient(deps.BaseFs.Assets, deps.ResourceSpec, false),
 		createClient: create.New(deps.ResourceSpec),
 		batcherStore: hmaps.NewCache[string, js.Batcher](),
 		bundlesStore: hmaps.NewCache[string, js.BatchPackage](),

internal/js/esbuild/build.go

@@ -32,17 +32,19 @@ import (
 )
 
 // NewBuildClient creates a new BuildClient.
-func NewBuildClient(fs *filesystems.SourceFilesystem, rs *resources.Spec) *BuildClient {
+func NewBuildClient(fs *filesystems.SourceFilesystem, rs *resources.Spec, cssMode bool) *BuildClient {
 	return &BuildClient{
-		rs:  rs,
-		sfs: fs,
+		rs:      rs,
+		sfs:     fs,
+		CssMode: cssMode,
 	}
 }
 
 // BuildClient is a client for building JavaScript resources using esbuild.
 type BuildClient struct {
-	rs  *resources.Spec
-	sfs *filesystems.SourceFilesystem
+	rs      *resources.Spec
+	sfs     *filesystems.SourceFilesystem
+	CssMode bool
 }
 
 // Build builds the given JavaScript resources using esbuild with the given options.

internal/js/esbuild/css_integration_test.go

@@ -0,0 +1,61 @@
+// 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 esbuild_test
+
+import (
+	"testing"
+
+	"github.com/gohugoio/hugo/hugolib"
+)
+
+func TestBundleCSS(t *testing.T) {
+	files := `
+-- hugo.toml --
+-- assets/a/pixel.png --
+iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==
+-- assets/css/main.css --
+@import "tailwindcss";
+@import url('https://example.org/foo.css');
+@import "./foo.css";
+@import "./bar.css" layer(mylayer);
+@import "./bar.css" layer;
+@import './baz.css' screen and (min-width: 800px);
+@import './qux.css' supports(display: grid);
+body {
+  background-image: url("a/pixel.png");
+}
+.mask1 {
+mask-image: url(a/pixel.png);
+mask-repeat: no-repeat;
+}
+-- assets/css/foo.css --
+p { background: red; }
+-- assets/css/bar.css --
+div { background: blue; }
+-- assets/css/baz.css --
+span { background: green; }
+-- assets/css/qux.css --
+article { background: yellow; }
+-- layouts/home.html --
+{{ with resources.Get "css/main.css"  }}
+{{ $engines := slice "chrome80" "firefox73" "safari13" "edge80" }}
+{{ with . | css.Build (dict "minify" true "engines" $engines "loaders" (dict ".png" "dataurl")  "externals" (slice  "tailwindcss"))  }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" />
+{{ end }}
+{{ end }}
+	`
+
+	b := hugolib.Test(t, files, hugolib.TestOptOsFs())
+	b.AssertFileContent("public/css/main.css", `webkit`)
+}

internal/js/esbuild/options.go

@@ -48,6 +48,20 @@ var (
 		"es2024": api.ES2024,
 	}
 
+	nameEngine = map[string]api.EngineName{
+		"chrome":  api.EngineChrome,
+		"deno":    api.EngineDeno,
+		"edge":    api.EngineEdge,
+		"firefox": api.EngineFirefox,
+		"hermes":  api.EngineHermes,
+		"ie":      api.EngineIE,
+		"ios":     api.EngineIOS,
+		"node":    api.EngineNode,
+		"opera":   api.EngineOpera,
+		"rhino":   api.EngineRhino,
+		"safari":  api.EngineSafari,
+	}
+
 	// source names: https://github.com/evanw/esbuild/blob/9eca46464ed5615cb36a3beb3f7a7b9a8ffbe7cf/internal/config/config.go#L208
 	nameLoader = map[string]api.Loader{
 		"none":       api.LoaderNone,
@@ -117,6 +131,11 @@ type ExternalOptions struct {
 	// Default is esnext.
 	Target string
 
+	// Engines to target, e.g. "chrome58" or "node12".
+	// TODO1 sensible default if not set. For css only.
+	// See https://esbuild.github.io/api/#target
+	Engines []string
+
 	// The output format.
 	// One of: iife, cjs, esm
 	// Default is to esm.
@@ -224,6 +243,22 @@ func (opts *Options) compile() (err error) {
 		return
 	}
 
+	var engines []api.Engine
+
+OUTER:
+	for _, value := range opts.Engines {
+		for engine, name := range nameEngine {
+			if strings.HasPrefix(value, engine) {
+				version := value[len(engine):]
+				if version == "" {
+					return fmt.Errorf("invalid engine version: %q", value)
+				}
+				engines = append(engines, api.Engine{Name: name, Version: version})
+				continue OUTER
+			}
+		}
+	}
+
 	var loaders map[string]api.Loader
 	if opts.Loaders != nil {
 		loaders = make(map[string]api.Loader)
@@ -252,6 +287,8 @@ func (opts *Options) compile() (err error) {
 		loader = api.LoaderTSX
 	case media.Builtin.JSXType.SubType:
 		loader = api.LoaderJSX
+	case media.Builtin.CSSType.SubType:
+		loader = api.LoaderCSS
 	default:
 		err = fmt.Errorf("unsupported Media Type: %q", opts.MediaType)
 		return
@@ -343,6 +380,7 @@ func (opts *Options) compile() (err error) {
 		AbsWorkingDir: opts.AbsWorkingDir,
 
 		Target:         target,
+		Engines:        engines,
 		Format:         format,
 		Platform:       platform,
 		Sourcemap:      sourceMap,

internal/js/esbuild/resolve.go

@@ -61,7 +61,7 @@ var extensionToLoaderMap = map[string]api.Loader{
 // This is a common sub-set of ESBuild's default extensions.
 // We assume that imports of JSON, CSS etc. will be using their full
 // name with extension.
-var commonExtensions = []string{".js", ".ts", ".tsx", ".jsx"}
+var commonExtensions = []string{".js", ".ts", ".tsx", ".jsx", ".css"}
 
 // ResolveComponent resolves a component using the given resolver.
 func ResolveComponent[T any](impPath string, resolve func(string) (v T, found, isDir bool)) (v T, found bool) {
@@ -93,6 +93,7 @@ func ResolveComponent[T any](impPath string, resolve func(string) (v T, found, i
 	}
 
 	base := filepath.Base(impPath)
+
 	if base == "index" {
 		// try index.esm.js etc.
 		v, found, _ = findFirst(impPath + ".esm")
@@ -159,6 +160,7 @@ func createBuildPlugins(rs *resources.Spec, assetsResolver *fsResolver, depsMana
 
 	resolveImport := func(args api.OnResolveArgs) (api.OnResolveResult, error) {
 		impPath := args.Path
+
 		shimmed := false
 		if opts.Shims != nil {
 			override, found := opts.Shims[impPath]
@@ -182,9 +184,9 @@ func createBuildPlugins(rs *resources.Spec, assetsResolver *fsResolver, depsMana
 		}
 
 		importer := args.Importer
-
 		isStdin := importer == stdinImporter
 		var relDir string
+
 		if !isStdin {
 			if after, ok := strings.CutPrefix(importer, PrefixHugoVirtual); ok {
 				relDir = filepath.Dir(after)

resources/resource_transformers/js/build.go

@@ -31,9 +31,9 @@ type Client struct {
 }
 
 // New creates a new client context.
-func New(fs *filesystems.SourceFilesystem, rs *resources.Spec) *Client {
+func New(fs *filesystems.SourceFilesystem, rs *resources.Spec, cssMode bool) *Client {
 	return &Client{
-		c: esbuild.NewBuildClient(fs, rs),
+		c: esbuild.NewBuildClient(fs, rs, cssMode),
 	}
 }
 

resources/resource_transformers/js/transform.go

@@ -30,11 +30,18 @@ type buildTransformation struct {
 }
 
 func (t *buildTransformation) Key() internal.ResourceTransformationKey {
-	return internal.NewResourceTransformationKey("jsbuild", t.optsm)
+	key := "jsbuild"
+	if t.c.c.CssMode {
+		key = "cssbuild"
+	}
+	return internal.NewResourceTransformationKey(key, t.optsm)
 }
 
 func (t *buildTransformation) Transform(ctx *resources.ResourceTransformationCtx) error {
 	ctx.OutMediaType = media.Builtin.JavascriptType
+	if ctx.InMediaType == media.Builtin.CSSType {
+		ctx.OutMediaType = media.Builtin.CSSType
+	}
 
 	var opts esbuild.Options
 
@@ -49,7 +56,7 @@ func (t *buildTransformation) Transform(ctx *resources.ResourceTransformationCtx
 	if opts.TargetPath != "" {
 		ctx.OutPath = opts.TargetPath
 	} else {
-		ctx.ReplaceOutPathExtension(".js")
+		ctx.ReplaceOutPathExtension(ctx.OutMediaType.FirstSuffix.FullSuffix)
 	}
 
 	src, err := io.ReadAll(ctx.From)

tpl/css/css.go

@@ -15,6 +15,7 @@ import (
 	"github.com/gohugoio/hugo/resources/resource"
 	"github.com/gohugoio/hugo/resources/resource_transformers/babel"
 	"github.com/gohugoio/hugo/resources/resource_transformers/cssjs"
+	jstransform "github.com/gohugoio/hugo/resources/resource_transformers/js"
 	"github.com/gohugoio/hugo/resources/resource_transformers/tocss/dartsass"
 	"github.com/gohugoio/hugo/resources/resource_transformers/tocss/sass"
 	"github.com/gohugoio/hugo/resources/resource_transformers/tocss/scss"
@@ -32,6 +33,7 @@ type Namespace struct {
 	postcssClient     *cssjs.PostCSSClient
 	tailwindcssClient *cssjs.TailwindCSSClient
 	babelClient       *babel.Client
+	jsTransformClient *jstransform.Client
 
 	// The Dart Client requires a os/exec process, so  only
 	// create it if we really need it.
@@ -147,6 +149,33 @@ func (ns *Namespace) Sass(args ...any) (resource.Resource, error) {
 	return client.ToCSS(r, m)
 }
 
+// Build processes the given CSS Resource with ESBuild.
+// Note that this method is identical to the one in the js Namespace.
+func (ns *Namespace) Build(args ...any) (resource.Resource, error) {
+	var (
+		r          resources.ResourceTransformer
+		m          map[string]any
+		targetPath string
+		err        error
+		ok         bool
+	)
+
+	r, targetPath, ok = resourcehelpers.ResolveIfFirstArgIsString(args)
+
+	if !ok {
+		r, m, err = resourcehelpers.ResolveArgs(args)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	if targetPath != "" {
+		m = map[string]any{"targetPath": targetPath}
+	}
+
+	return ns.jsTransformClient.Process(r, m)
+}
+
 func init() {
 	f := func(d *deps.Deps) *internal.TemplateFuncsNamespace {
 		scssClient, err := scss.New(d.BaseFs.Assets, d.ResourceSpec)
@@ -159,6 +188,7 @@ func init() {
 			postcssClient:     cssjs.NewPostCSSClient(d.ResourceSpec),
 			tailwindcssClient: cssjs.NewTailwindCSSClient(d.ResourceSpec),
 			babelClient:       babel.New(d.ResourceSpec),
+			jsTransformClient: jstransform.New(d.BaseFs.Assets, d.ResourceSpec, true),
 		}
 
 		ns := &internal.TemplateFuncsNamespace{

tpl/js/js.go

@@ -36,7 +36,7 @@ func New(d *deps.Deps) (*Namespace, error) {
 
 	return &Namespace{
 		d:                 d,
-		jsTransformClient: jstransform.New(d.BaseFs.Assets, d.ResourceSpec),
+		jsTransformClient: jstransform.New(d.BaseFs.Assets, d.ResourceSpec, false),
 		createClient:      create.New(d.ResourceSpec),
 		babelClient:       babel.New(d.ResourceSpec),
 	}, nil
@@ -51,7 +51,7 @@ type Namespace struct {
 	babelClient       *babel.Client
 }
 
-// Build processes the given Resource with ESBuild.
+// Build processes the given JavaScript Resource with ESBuild.
 func (ns *Namespace) Build(args ...any) (resource.Resource, error) {
 	var (
 		r          resources.ResourceTransformer