feat: format js and css with prettier if prettier is on the $PATH (#1230)

Author: a-h

.github/copilot-instructions.md

@@ -1,5 +1,10 @@
 # Coding standards
 
+## Behaviour
+
+* Always run `go fmt` after making changes to Go code.
+* Always run unit tests after making changes to Go code.
+
 ## Environment setup
 
 * Ensure that the user has direnv installed, and that it is set up correctly in their shell. See https://direnv.net/docs/installation.html
@@ -25,13 +30,14 @@ The most useful tasks for local development are:
 * `xc install-snapshot` - builds the templ CLI and installs it into `~/bin`. Ensure that this is in your path.
 * `xc generate` - generates Go code from the templ files in the project.
 * `xc test` - regenerates all templates, and runs the unit tests.
+* `xc test-short` - runs shorter tests, avoiding long running tests for filesystem watchers etc.
 * `xc fmt` - runs `gofmt` to format all Go code.
 * `xc lint` - run the same linting as run in the CI process.
 * `xc docs-run` - run the Docusaurus documentation site.
 
 templ has a code generation step, this is automatically carried out using `xc test`.
 
-Don't install templ globally using `xc install-snapshot` or `go install`. Use the `xc generate` or `xc test` tasks to generate the code, which will also run the tests.
+Don't install templ globally using `xc install-snapshot` or `go install`. Use the `xc generate` or `xc test-short` tasks to generate the code, which will also run the tests.
 
 ## Commit messages
 
@@ -63,6 +69,7 @@ Examples:
 * Use the `xc fmt` and `xc lint` build tasks to format and lint code before committing.
 * Don't use unnecessary comments that explain what the code does.
 * If comments are used, ensure that they are full sentences, and use proper punctuation, including ending with a full stop.
+* Don't write comments after the end of keywords, e.g. `continue // Only process pairs`
 
 ## Tests
 

.version

@@ -1 +1 @@
-0.3.935
+0.3.935

cmd/templ/fmtcmd/main.go

@@ -8,37 +8,66 @@ import (
 	"log/slog"
 	"os"
 	"runtime"
-	"sync"
 	"time"
 
-	"github.com/a-h/templ/cmd/templ/imports"
 	"github.com/a-h/templ/cmd/templ/processor"
-	parser "github.com/a-h/templ/parser/v2"
+	"github.com/a-h/templ/internal/format"
 	"github.com/natefinch/atomic"
 )
 
 type Arguments struct {
-	FailIfChanged bool
-	ToStdout      bool
-	StdinFilepath string
-	Files         []string
-	WorkerCount   int
+	FailIfChanged    bool
+	ToStdout         bool
+	StdinFilepath    string
+	Files            []string
+	WorkerCount      int
+	PrettierCommand  string
+	PrettierRequired bool
 }
 
 func Run(log *slog.Logger, stdin io.Reader, stdout io.Writer, args Arguments) (err error) {
 	// If no files are provided, read from stdin and write to stdout.
+	formatterConfig := format.Config{
+		PrettierCommand:  args.PrettierCommand,
+		PrettierRequired: args.PrettierRequired,
+	}
 	if len(args.Files) == 0 {
-		out, _ := format(writeToWriter(stdout), readFromReader(stdin, args.StdinFilepath), true)
-		return out
+		src, err := io.ReadAll(stdin)
+		if err != nil {
+			return fmt.Errorf("failed to read from stdin: %w", err)
+		}
+		formatted, _, err := format.Templ(src, args.StdinFilepath, formatterConfig)
+		if err != nil {
+			return fmt.Errorf("failed to format stdin: %w", err)
+		}
+		if _, err = stdout.Write(formatted); err != nil {
+			return fmt.Errorf("failed to write to stdout: %w", err)
+		}
+		return nil
 	}
+	// If files are provided, process each file.
 	process := func(fileName string) (error, bool) {
-		read := readFromFile(fileName)
-		write := writeToFile
+		src, err := os.ReadFile(fileName)
+		if err != nil {
+			return fmt.Errorf("failed to read file %q: %w", fileName, err), false
+		}
+		formatted, changed, err := format.Templ(src, fileName, formatterConfig)
+		if err != nil {
+			return fmt.Errorf("failed to format file %q: %w", fileName, err), false
+		}
+		if !changed && !args.ToStdout {
+			return nil, false
+		}
 		if args.ToStdout {
-			write = writeToWriter(stdout)
+			if _, err := stdout.Write(formatted); err != nil {
+				return fmt.Errorf("failed to write to stdout: %w", err), false
+			}
+			return nil, true
+		}
+		if err := atomic.WriteFile(fileName, bytes.NewBuffer(formatted)); err != nil {
+			return fmt.Errorf("failed to write file %q: %w", fileName, err), false
 		}
-		writeIfUnchanged := args.ToStdout
-		return format(write, read, writeIfUnchanged)
+		return nil, true
 	}
 	dir := args.Files[0]
 	return NewFormatter(log, dir, process, args.WorkerCount, args.FailIfChanged).Run()
@@ -101,69 +130,3 @@ func (f *Formatter) Run() (err error) {
 
 	return nil
 }
-
-type reader func() (fileName, src string, err error)
-
-func readFromReader(r io.Reader, stdinFilepath string) func() (fileName, src string, err error) {
-	return func() (fileName, src string, err error) {
-		b, err := io.ReadAll(r)
-		if err != nil {
-			return "", "", fmt.Errorf("failed to read stdin: %w", err)
-		}
-		return stdinFilepath, string(b), nil
-	}
-}
-
-func readFromFile(name string) reader {
-	return func() (fileName, src string, err error) {
-		b, err := os.ReadFile(name)
-		if err != nil {
-			return "", "", fmt.Errorf("failed to read file %q: %w", fileName, err)
-		}
-		return name, string(b), nil
-	}
-}
-
-type writer func(fileName, tgt string) error
-
-var mu sync.Mutex
-
-func writeToWriter(w io.Writer) func(fileName, tgt string) error {
-	return func(fileName, tgt string) error {
-		mu.Lock()
-		defer mu.Unlock()
-		_, err := w.Write([]byte(tgt))
-		return err
-	}
-}
-
-func writeToFile(fileName, tgt string) error {
-	return atomic.WriteFile(fileName, bytes.NewBufferString(tgt))
-}
-
-func format(write writer, read reader, writeIfUnchanged bool) (err error, fileChanged bool) {
-	fileName, src, err := read()
-	if err != nil {
-		return err, false
-	}
-	t, err := parser.ParseString(src)
-	if err != nil {
-		return err, false
-	}
-	t.Filepath = fileName
-	t, err = imports.Process(t)
-	if err != nil {
-		return err, false
-	}
-	w := new(bytes.Buffer)
-	if err = t.Write(w); err != nil {
-		return fmt.Errorf("formatting error: %w", err), false
-	}
-
-	fileChanged = (src != w.String())
-
-	if !writeIfUnchanged && !fileChanged {
-		return nil, fileChanged
-	}
-	return write(fileName, w.String()), fileChanged
-}

cmd/templ/lspcmd/proxy/server.go

@@ -10,12 +10,12 @@ import (
 	"strings"
 
 	"github.com/a-h/parse"
+	"github.com/a-h/templ/internal/imports"
 	"github.com/a-h/templ/internal/lazyloader"
 	lsp "github.com/a-h/templ/lsp/protocol"
 	"github.com/a-h/templ/lsp/uri"
 
 	"github.com/a-h/templ"
-	"github.com/a-h/templ/cmd/templ/imports"
 	"github.com/a-h/templ/generator"
 	"github.com/a-h/templ/parser/v2"
 )

cmd/templ/main.go

@@ -172,6 +172,10 @@ Args:
     Set log verbosity level. (default "info", options: "debug", "info", "warn", "error")
   -w
     Number of workers to use when formatting code. (default runtime.NumCPUs).
+  -prettier-command
+    Set the command to use for formatting HTML, CSS, and JS blocks. Default is "prettier --stdin-filepath $TEMPL_PRETTIER_FILENAME".
+  -prettier-required
+    Set to true to return an error the prettier command is not available. Default is false.
   -fail
     Fails with exit code 1 if files are changed. (e.g. in CI)
   -help
@@ -185,6 +189,8 @@ func fmtCmd(stdin io.Reader, stdout, stderr io.Writer, args []string) (code int)
 	verboseFlag := cmd.Bool("v", false, "")
 	logLevelFlag := cmd.String("log-level", "info", "")
 	failIfChanged := cmd.Bool("fail", false, "")
+	prettierCommand := cmd.String("prettier-command", "", "")
+	prettierRequired := cmd.Bool("prettier-required", false, "")
 	stdoutFlag := cmd.Bool("stdout", false, "")
 	stdinFilepath := cmd.String("stdin-filepath", "", "")
 	err := cmd.Parse(args)
@@ -200,11 +206,13 @@ func fmtCmd(stdin io.Reader, stdout, stderr io.Writer, args []string) (code int)
 	log := sloghandler.NewLogger(*logLevelFlag, *verboseFlag, stderr)
 
 	err = fmtcmd.Run(log, stdin, stdout, fmtcmd.Arguments{
-		ToStdout:      *stdoutFlag,
-		Files:         cmd.Args(),
-		WorkerCount:   *workerCountFlag,
-		StdinFilepath: *stdinFilepath,
-		FailIfChanged: *failIfChanged,
+		ToStdout:         *stdoutFlag,
+		Files:            cmd.Args(),
+		WorkerCount:      *workerCountFlag,
+		StdinFilepath:    *stdinFilepath,
+		FailIfChanged:    *failIfChanged,
+		PrettierCommand:  *prettierCommand,
+		PrettierRequired: *prettierRequired,
 	})
 	if err != nil {
 		return 1

cmd/templ/visualize/sourcemapvisualisation.templ

@@ -19,8 +19,12 @@ templ combine(templFileName string, left, right templ.Component) {
 		<head>
 			<title>{ templFileName }- Source Map Visualisation</title>
 			<style type="text/css">
-				.mapped { background-color: green }
-				.highlighted { background-color: yellow }
+				.mapped {
+					background-color: green;
+				}
+				.highlighted {
+					background-color: yellow;
+				}
 			</style>
 		</head>
 		<body>

cmd/templ/visualize/sourcemapvisualisation_templ.go

@@ -15,6 +15,8 @@ templ body() {
 }
 ```
 
+If you have `prettierd`, `prettier` or `npx` on your `PATH`, `templ` will use it to format the `<script>` tag contents.
+
 :::tip
 To ensure that a `<script>` tag within a templ component is only rendered once per HTTP response (or context), use a [templ.OnceHandle](18-render-once.md).
 

docs/docs/03-syntax-and-usage/13-script-templates.md

@@ -94,6 +94,8 @@ to exit with unix error-code `1` if any templates needed to be modified.
 templ fmt -fail .
 ```
 
+If `prettierd`, `prettier` or `npx` is found in your `PATH`, `templ fmt` will use prettier to format `script` and `style` elements in files.
+
 ## Language Server for IDE integration
 
 `templ lsp` provides a Language Server Protocol (LSP) implementation to support IDE integrations.

docs/docs/09-developer-tools/01-cli.md

@@ -145,7 +145,6 @@ module.exports = {
 
 With the templ LSP installed and configured, you can use the following code snippet to format on save:
 
-
 ```lua
 vim.api.nvim_create_autocmd({ "BufWritePre" }, { pattern = { "*.templ" }, callback = vim.lsp.buf.format })
 ```
@@ -211,6 +210,12 @@ local templ_format = function()
 end
 ```
 
+:::note
+Formatting `script` and `style` elements in templ files is handed off to prettier.
+
+If you don't have `prettierd`, `prettier` or `npx` on your path, formatting will not be applied to those elements.
+:::
+
 ### Troubleshooting
 
 If you cannot run `:TSInstall templ`, ensure you have an up-to-date version of [tree-sitter](https://github.com/nvim-treesitter/nvim-treesitter). The [package for templ](https://github.com/vrischmann/tree-sitter-templ) was [added to the main tree-sitter repository](https://github.com/nvim-treesitter/nvim-treesitter/pull/5667) so you shouldn't need to install a separate plugin for it.