Restructure Component Scripts and Add Build Steps

[derkan]

Hi! The component structure is very clear and easy to follow — great work!

I have a few suggestions that could help improve the developer experience and performance:

📦 Decouple Script Logic from Components

Move the <script> section out of the component files into separate .js files with the same name. Then use esbuild to bundle everything into a single file named templui.js (minified in production). This file can be included in index.templ.

Benefits:

• Improved IDE support for JS files
• Reduced bandwidth usage (JS sent once from the server)(also with minification much smaller)
• Cleaner and smaller HTML responses
• A separate utils.js can host a common registerEvents function, which components call with their initAllComponents parameter
• CLI installer support: the CLI could build a main JS file that imports all installed components from ui/components, and esbuild can generate the final bundle from that

🛠️ Proposed Makefile Additions

Here are three new make targets: dev/esbuild, esbuild and dev/assets (note: not yet tested):

# Watch mode with templ
dev/templ:
	templ generate --watch --proxy="http://localhost:8090" --open-browser=false

# Dev server
dev/server:
	air --build.cmd ...

# TailwindCSS watch mode
dev/tailwind:
	tailwindcss -i ./ui.css -o ./ui/assets/out.min.css  --watch

# JS bundler - watch mode
dev/esbuild:
	esbuild ./ui/components/templui.js  --sourcemap --bundle --outfile=./assets/js/templ.min.js --watch

# JS bundler - production
esbuild:
	esbuild ./ui/components/templui.js  --sourcemap --bundle --outfile=./assets/js/templ.min.js  --minify

# Browser reload on JS changes
dev/assets:
	air \
	--build.cmd "templ generate --notify-proxy" \
	--build.bin "true" \
	--build.delay "100" \
	--build.exclude_dir "" \
	--build.include_dir "./ui/translations,./ui/assets" \
	--build.include_ext "js,css,yaml"

# Dev startup
dev:
	make tailwind-clean
	make -j5 dev/templ dev/tailwind dev/server dev/esbuild dev/assets

Let me know what you think!

[chris-perardi]

Great concept. I’d love to see it in this project.

ESBuild is so easy to work with. My team is developing an internal app using TemplUI and ESBuild, and it’s been a smooth experience so far.

We have a build system that handles custom CSS, TS, and static assets.

Here’s what that looks like…

package main

import (
	"context"
	"fmt"
	"io"
	"os"
	"os/exec"
	"path/filepath"
	"strings"

	"github.com/evanw/esbuild/pkg/api"
	"github.com/sodahealth/harmony/pkg/logging"
	"go.uber.org/zap"
)

func main() {
	ctx := context.Background()
	logger := logging.NewLogger()
	defer logger.Logger.Sync()

	// Use the logger directly without trying to add it to the context
	if err := buildFrontendAssets(ctx); err != nil {
		logger.Error("Failed to build frontend assets", zap.Error(err))
		os.Exit(1)
	}
}

// Path constants for better maintainability
const (
	// Base directories
	srcDir  = "./pkg/csrx/ui/src"
	distDir = "./pkg/csrx/ui/dist"

	// CSS paths
	cssSourceDir        = srcDir + "/css"
	cssDistDir          = distDir + "/css"
	tailwindInputPath   = cssSourceDir + "/tailwind.styles.css"
	tailwindOutputPath  = cssDistDir + "/tailwind.min.css"
	customCSSOutputPath = cssDistDir + "/custom.min.css"
	combinedCSSPath     = cssDistDir + "/styles.min.css"

	// JS paths
	jsSourceDir    = srcDir + "/ts"
	jsDistDir      = distDir + "/js"
	vendorDir      = srcDir + "/vendor"
	combinedJSPath = jsDistDir + "/app.min.js"

	// Assets paths
	assetsSourceDir = srcDir + "/assets"
	assetsDistDir   = distDir + "/assets"
)

// isProduction returns true if running in production mode
func isProduction() bool {
	return os.Getenv("GO_ENV") == "production"
}

// buildFrontendAssets builds frontend assets including Tailwind CSS, custom CSS, JS, and static assets
func buildFrontendAssets(ctx context.Context) error {
	logger := logging.FromContext(ctx)

	// Skip build if assets are up to date and in production
	if isProduction() {
		logger.Info("Frontend assets are up to date, skipping build")
		return nil
	}

	logger.Info("Building frontend assets...")

	// Ensure output directories exist
	if err := ensureDirsExist(); err != nil {
		return err
	}

	// Build CSS (Tailwind and custom)
	if err := buildCSS(ctx); err != nil {
		return err
	}

	// Build JS/TS with esbuild and process vendor JS
	if err := buildJavaScript(ctx); err != nil {
		return err
	}

	// Process static assets
	if err := processAssets(ctx); err != nil {
		return err
	}

	logger.Info("Frontend assets built successfully")
	return nil
}

// ensureDirsExist creates all necessary output directories
func ensureDirsExist() error {
	dirs := []string{
		cssDistDir,
		jsDistDir,
		assetsDistDir,
	}

	for _, dir := range dirs {
		if err := os.MkdirAll(dir, os.ModePerm); err != nil {
			return fmt.Errorf("failed to create directory %s: %w", dir, err)
		}
	}

	return nil
}

// buildCSS handles all CSS processing (Tailwind and custom)
func buildCSS(ctx context.Context) error {
	// Build Tailwind CSS
	if err := buildTailwindCSS(ctx); err != nil {
		return err
	}

	// Process custom CSS files
	customFiles, err := filepath.Glob(filepath.Join(cssSourceDir, "*.css"))
	if err != nil {
		return fmt.Errorf("failed to find custom CSS files: %w", err)
	}

	// Filter out styles.css (Tailwind input)
	var customCSSFiles []string
	for _, file := range customFiles {
		if !strings.Contains(file, filepath.Base(tailwindInputPath)) {
			customCSSFiles = append(customCSSFiles, file)
		}
	}

	if len(customCSSFiles) > 0 {
		if err := processCustomCSS(ctx, customCSSFiles); err != nil {
			return err
		}
	}

	return nil
}

// buildTailwindCSS runs the Tailwind CLI to process CSS files
func buildTailwindCSS(ctx context.Context) error {
	logger := logging.FromContext(ctx)
	logger.Info("Processing Tailwind CSS...")

	args := []string{
		"tailwindcss",
		"-i", tailwindInputPath,
		"-o", tailwindOutputPath,
	}

	if isProduction() {
		args = append(args, "--minify")
	}

	cmd := exec.Command("npx", args...)
	output, err := cmd.CombinedOutput()

	if err != nil {
		logger.Error("Tailwind CSS build failed",
			zap.Error(err),
			zap.String("output", string(output)))
		return fmt.Errorf("tailwind CSS build failed: %w", err)
	}

	logger.Info("Tailwind CSS processed successfully")
	return nil
}

// processCustomCSS processes custom CSS files using esbuild
func processCustomCSS(ctx context.Context, files []string) error {
	if len(files) == 0 {
		return nil
	}

	logger := logging.FromContext(ctx)
	logger.Info("Processing custom CSS files...")

	buildOptions := api.BuildOptions{
		EntryPoints: files,
		Outfile:     customCSSOutputPath,
		Bundle:      true,
		Write:       true,
		LogLevel:    api.LogLevelInfo,
	}

	if isProduction() {
		buildOptions.MinifyWhitespace = true
		buildOptions.MinifySyntax = true
	}

	result := api.Build(buildOptions)

	if len(result.Errors) > 0 {
		return fmt.Errorf("custom CSS build failed: %v", result.Errors[0].Text)
	}

	logger.Info("Custom CSS processed successfully")
	return nil
}

// buildJavaScript builds all JS/TS files and vendor scripts
func buildJavaScript(ctx context.Context) error {
	logger := logging.FromContext(ctx)
	logger.Info("Building JavaScript/TypeScript...")

	// Build TypeScript files
	if err := buildTypeScript(ctx); err != nil {
		return err
	}

	// Copy vendor JS files
	if err := processVendorJS(ctx); err != nil {
		return err
	}

	return nil
}

// buildTypeScript builds TypeScript files with esbuild
func buildTypeScript(ctx context.Context) error {
	logger := logging.FromContext(ctx)

	// Find all TypeScript files
	tsFiles, err := filepath.Glob(filepath.Join(jsSourceDir, "*.ts"))
	if err != nil {
		return fmt.Errorf("failed to find TypeScript files: %w", err)
	}

	if len(tsFiles) == 0 {
		logger.Info("No TypeScript files found")
		return nil
	}

	// Process each TypeScript file
	for _, tsFile := range tsFiles {
		baseName := filepath.Base(tsFile)
		outFile := filepath.Join(jsDistDir, strings.TrimSuffix(baseName, ".ts")+".min.js")

		buildOptions := api.BuildOptions{
			Bundle:      true,
			EntryPoints: []string{tsFile},
			Outfile:     outFile,
			LogLevel:    api.LogLevelInfo,
			Write:       true,
		}

		// Add environment-specific settings
		if isProduction() {
			buildOptions.MinifyIdentifiers = true
			buildOptions.MinifySyntax = true
			buildOptions.MinifyWhitespace = true
			buildOptions.Sourcemap = api.SourceMapNone
		} else {
			buildOptions.Sourcemap = api.SourceMapExternal
		}

		result := api.Build(buildOptions)

		if len(result.Errors) > 0 {
			for _, err := range result.Errors {
				logger.Error("Build error", zap.String("error", err.Text))
			}
			return fmt.Errorf("TypeScript build failed for %s", baseName)
		}
	}

	logger.Info("TypeScript files built successfully")
	return nil
}

// processVendorJS copies vendor JS files to the dist directory
func processVendorJS(ctx context.Context) error {
	logger := logging.FromContext(ctx)
	logger.Info("Processing vendor JS files...")

	// Find all vendor JS files
	vendorFiles, err := filepath.Glob(filepath.Join(vendorDir, "*.js"))
	if err != nil {
		return fmt.Errorf("failed to find vendor JS files: %w", err)
	}

	if len(vendorFiles) == 0 {
		logger.Info("No vendor JS files found")
		return nil
	}

	// Copy each vendor file to dist
	for _, file := range vendorFiles {
		baseName := filepath.Base(file)
		destPath := filepath.Join(jsDistDir, baseName)

		if err := copyFile(file, destPath); err != nil {
			logger.Error("Failed to copy vendor JS", zap.Error(err), zap.String("file", file))
			return err
		}
	}

	logger.Info("Vendor JS files processed successfully")
	return nil
}

// processAssets copies and optionally optimizes assets
func processAssets(ctx context.Context) error {
	logger := logging.FromContext(ctx)
	logger.Info("Processing assets...")

	// Check if assets directory exists
	if _, err := os.Stat(assetsSourceDir); os.IsNotExist(err) {
		logger.Info("Assets directory does not exist, skipping")
		return nil
	}

	// Copy assets from src to dist
	return filepath.Walk(assetsSourceDir, func(path string, info os.FileInfo, err error) error {
		if err != nil {
			return err
		}

		// Skip directories
		if info.IsDir() {
			return nil
		}

		// Get relative path
		relPath, err := filepath.Rel(assetsSourceDir, path)
		if err != nil {
			return err
		}

		// Create destination path
		destPath := filepath.Join(assetsDistDir, relPath)

		// Ensure destination directory exists
		destDir := filepath.Dir(destPath)
		if err := os.MkdirAll(destDir, os.ModePerm); err != nil {
			return err
		}

		// Copy file
		return copyFile(path, destPath)
	})
}

// copyFile copies a file from src to dest
func copyFile(src, dest string) error {
	srcFile, err := os.Open(src)
	if err != nil {
		return fmt.Errorf("failed to open source file %s: %w", src, err)
	}
	defer srcFile.Close()

	destFile, err := os.Create(dest)
	if err != nil {
		return fmt.Errorf("failed to create destination file %s: %w", dest, err)
	}
	defer destFile.Close()

	_, err = io.Copy(destFile, srcFile)
	if err != nil {
		return fmt.Errorf("failed to copy file content: %w", err)
	}

	return nil
}

[axzilla]

Thanks for the great feedback!

I see both sides when it comes to separating the JS logic from the components.

On one hand, I think the current structure offers the best developer experience. In my opinion, there’s nothing better DX-wise than self-contained components.

Benefits:

• Better IDE support for JS files
• Less bandwidth (JS is only sent once from the server, and it's much smaller when minified)
• Cleaner and smaller HTML responses

On the other hand, I also understand the arguments for building a shared JS file via CLI:

CLI installer support: the CLI could build a main JS file that imports all installed components from ui/components, and esbuild can generate the final bundle.

But for me, this is actually the opposite of a good DX. It means, as a user every time I add a new component, I have to rebuild my JS file. That feels slow and error-prone.

A middle ground might be: as the maintainer, I just provide a prebuilt, minified .js file that includes the JS for all components. You only have to include it once in your layout.

Better DX? Yes!
More overhead? Also yes.
But to me, it’s the best compromise.

Am I missing something?
I’d love to hear your thoughts!

[chris-perardi]

Well, what I really want is for you to keep jamming out quality components. The vagaries of how the JS is organized aren’t that important, we can work with whatever. (Trust me, compared to the legacy stuff I am rebuilding right now, this is all a dream in comparison.)

That being said, having one discrete JS file that I could build into my asset builder pipeline would theoretically be nice. Our ui system is structured like this:

- components
- dist
	- assets
		- fonts/
	- css
		- tailwind.min.css
	- js
	  	- htmx-2.0.4.min.js
- icon_utils
- layouts
- nav
- src
	- css
  		- tailwind.styles.css
	- vendor
    	        - htmx-2.0.4.min.js
- strings
- ui_utils
- views

build.go takes CSS, JS, and TS sources from src and process and minifies output to dist.

It would be nice to have on vendor TemplUI JS file to work with. Easy to diff, easy to extend if needed, and we can concat/minify into the rest of our JS at build time. But I don’t consider it a critical need.

So, in the end, food for thought.

[axzilla]

I'm working on a global script import per page for now — just one JS file for the whole library, to keep things simple and developer-friendly in the first version.

The file is about 400kb (includes the core library, charts.js, floatingUI, and highlight.js).
I don’t think that’s a big performance issue, but what do you think?

Let’s discuss this further in the issue: #179