Leveraging (abusing?) external formatters in Zed

Zed has a neat feature where you can use an external formatter to format your code:

1
{
2
  "formatter": {
3
    "external": {
4
      "command": "prettier",
5
      "arguments": ["--stdin-filepath", "{buffer_path}"]
6
    }
7
  }
8
}

You can even specify multiple formatters in an array:

1
{
2
  "formatter": [
3
    { "language_server": { "name": "rust-analyzer" } },
4
    {
5
      "external": {
6
        "command": "sed",
7
        "arguments": ["-e", "s/ *$//"]
8
      }
9
    }
10
  ]
11
}

However, this doesn’t work like I would expect it to.

From the Zed documentation:

quote

Here rust-analyzer will be used first to format the code, followed by a call of sed. If any of the formatters fails, the subsequent ones will still be executed.

This also means that if the first formatter succeeds, the second formatter will still be executed. So the last formatter specified always wins. This makes sense for use cases where you want to modify the output of a previous formatter.

But I’d like to specify multiple formatters where the additional formatters are used as fallbacks.

I use Biome to format/lint a lot of my TypeScript projects. Biome’s language support is pretty limited compared to Prettier’s, especially when you take into account all of the plugins available for Prettier.

So I want to use Prettier to format files that Biome doesn’t support.

Wait, can’t you do this by specifying Biome last in the list of formatters? Biome will run last and overwrite anything Prettier changed, so it “wins” for any files it supports, right?
1
{
2
  "formatter": [
3
    {
4
      "external": {
5
        "command": "prettier",
6
        "arguments": ["--stdin-filepath", "{buffer_path}"]
7
      }
8
    },
9
    { "language_server": { "name": "biome" } }
10
  ]
11
}

You’re right, but this has some limitations:

Running multiple formatters can lead to unexpected results (there are situations where changes the first formatter make could affect the second formatter)
Running multiple formatters is slower
What if I want to change the arguments passed to the formatter based on some condition?

We could probably come up with more reasons to want to do something custom.

A “formatter” is just some executable

This is where we can start having some fun. At a basic level, a formatter is some executable that takes the contents of the current file on stdin and writes the formatted contents to stdout.

Which means specifying a script as our formatter is perfectly valid:

1
{
2
  "external": {
3
    "command": "format-wrapper.bash"
4
  }
5
}

tip

This assumes format-wrapper.bash is in your PATH. You can specify an absolute path if needed.

Let’s write a simple formatter:

1
#!/usr/bin/env bash
2

3
input="$(< /dev/stdin)"
4

5
echo "// this is from our formatter!"
6
echo "${input}"

tip

If the process exits with a non-zero status, Zed will show a warning that the formatter failed and will not apply any changes to the buffer.

Then imagine we run Zed’s formatting command on a file like this:

1
console.log("hello world")

We would get this:

1
// this is from our formatter!
2
console.log("hello world")

Well, obviously this didn’t do any actual formatting, and if we ran it again, it would append another comment, but you get the idea.

Let’s make our formatter a little better. You may have noticed from above that Zed provides a special {buffer_path} argument. This is generally used by the formatter to determine the kind of file it’s working with based on the extension.

info

Remember, formatters in this context work with whatever they get on stdin. They don’t read the file’s contents directly or write to it directly. The passed in file path doesn’t even need to exist!

1
{
2
  "external": {
3
    "command": "format-wrapper.bash",
4
    "arguments": ["{buffer_path}"]
5
  }
6
}

1
#!/usr/bin/env bash
2

3
input="$(< /dev/stdin)"
4

5
buffer_path="${1}"
6

7
echo -n "${input}" | prettier --stdin-filepath "${buffer_path}"
8
# prettier writes the formatted output to stdout which will replace the buffer contents

We basically just recreated what Zed was already doing in the example at the start of this post, but now we’re in a script so we can do whatever we want!

That’s pretty much it, but read on if you’re curious about how I solved my particular problem.

My custom formatter

Specifically, this is what I want to do:

Use Biome
if the above fails, use Prettier with the project’s configuration
if the above fails, use Prettier with my “global” configuration
- I have a ~/.prettierrc.mjs file that I use for formatting one-off files.
  e.g. prettier --config ~/.prettierrc.mjs --write <some-file>

This is what I came up with:

1
#!/usr/bin/env bash
2

3
buffer_path="${1}"
4
prettier_config="${2}" # the path to the prettier config which will be used by global prettier
5

6
input="$(< /dev/stdin)"
7

8
errors="" # a string to collect errors from each formatter
9

10
# This function is called after each formatter runs
11
# If the formatter failed, the error will be collected and the script will continue
12
# If the formatter succeeded, we print the output to stdout and exit
13
handle_output() {
14
  local status="${1}"
15
  local output="${2}"
16
  local identifier="${3}"
17

18
  # if the output is empty, it's likely a formatter failed, printed nothing, but didn't exit with a non-zero status
19
  # regardless of the reason it's empty, we don't want to continue or else we'd replace the current buffer with nothing
20
  if [[ "${status}" -gt 0 || -z "${output}" ]]; then
21
    [[ -z "${output}" ]] && output="format-wrapper: something went wrong, output is empty"
22
    errors="${errors}\n${identifier}: [exit status ${status}] ${output}\n--------"
23
    return "${status}"
24
  fi
25

26
  echo "${output}"
27
  exit 0
28
}
29

30
# Biome
31
if [[ -f biome.json || -f biome.jsonc ]]; then
32
  biome_project_cmd="$(pwd)"/node_modules/.bin/biome
33
  if [[ -f "${biome_project_cmd}" ]]; then
34
    output="$(echo -n "${input}" | "${biome_project_cmd}" check --stdin-file-path="${buffer_path}" --write 2>&1)"
35
    handle_output $? "${output}" "biome (${biome_project_cmd})"
36
  fi
37
fi
38

39
# Project Prettier
40
# if we don't give --find-config-path an argument, it won't check the cwd
41
prettier_project_config="$(prettier --find-config-path ' ' 2> /dev/null)"
42
# if prettier doesn't find a config, the string will be empty
43
# prettier will look outside the cwd for a config, so the project config must exist within the cwd if we're going to use it (i.e. don't use the config if it starts with '../')
44
if [[ -n "${prettier_project_config}" && ! "${prettier_project_config}" =~ ^\.\.\/ ]]; then
45
  prettier_project_cmd="$(pwd)"/node_modules/.bin/prettier
46
  if [[ -f "${prettier_project_cmd}" ]]; then
47
    output="$(echo -n "${input}" | "${prettier_project_cmd}" --stdin-filepath "${buffer_path}" 2>&1)"
48
    handle_output $? "${output}" "prettier (${prettier_project_cmd})"
49
  fi
50
fi
51

52
# Global Prettier
53
output="$(echo -n "${input}" | prettier --stdin-filepath "${buffer_path}" --config "${prettier_config}" 2>&1)"
54
handle_output $? "${output}" "prettier ($(type -p prettier))"
55

56
# if we got here, none of the formatters succeeded
57
echo -n -e "\n--------${errors}" >&2
58
exit 1

A lot of the complexity here is due to the fact that we want to capture any errors that occur and display them in the Zed log should all of the formatters fail.

The relevant part of my Zed config looks like this:

1
{
2
  "formatter": {
3
    "external": {
4
      "command": "format-wrapper.bash",
5
      "arguments": ["{buffer_path}", "/Users/adam/.prettierrc.mjs"]
6
    }
7
  },
8
  "languages": {
9
    "Rust": { "formatter": "language_server" },
10
    "Dockerfile": { "formatter": "language_server" },
11
    "Prisma": { "formatter": "language_server" },
12
    "SQL": { "formatter": "language_server" }
13
  }
14
}

Note that I have my formatter set as the top-level formatter, which means by default every file will be formatted using my script. Obviously this won’t work for all files, so I set the formatter back to language_server for specific languages.

You could certainly flip this and set the top-level formatter to language_server or auto and use your custom formatter only for specific languages. Whatever seems easier to you.

A TypeScript version

note

This section was added at a later date (June 29, 2025).

Unsurprisingly, I quickly ran into limitations with my bash script. Like any shell script that’s more than a handful of lines, you’re better off writing it in, well, not shell.

Specifically, I wanted to be able to define a “group” of formatters, where the output of each formatter is passed as input to the next formatter in the group. This is different from the above approach, where the output of the first successful formatter is used.

To be clear, I still want the original “fallback” behavior. That is, if any formatter in the group fails, the whole group fails and it will move onto the next formatter.

So I decided to implement this, and took the opportunity to rewrite the script in TypeScript with Bun as the runtime.

1
#!/usr/bin/env bun
2

3
import path from "node:path"
4
import process from "node:process"
5
import { $ } from "bun"
6

7
const [bufferPath = "", prettierConfigPath = ""] = process.argv.slice(2)
8
const stdin = await Bun.stdin.text()
9
const cwd = process.cwd()
10

11
type FormatterResult = {
12
  identifier: string
13
  stdout: string
14
  stderr: string
15
  exitCode: number
16
}
17
type Formatter = (input: string) => FormatterResult | Promise<FormatterResult>
18
type FormatterGroup = Formatter | Formatter[]
19

20
function getFormatterErrorString(result: FormatterResult): string | undefined {
21
  // if the output is empty, it's likely a formatter failed, printed nothing, but didn't exit with a non-zero status
22
  // regardless of the reason it's empty, we don't want to continue or else we'd replace the current buffer with nothing
23
  if (result.exitCode === 0 && result.stdout.trim().length > 0) return
24
  return `\n${result.identifier}: [exit status ${result.exitCode}] ${result.stderr || "format-wrapper: something went wrong, output is empty"}\n--------`
25
}
26

27
/**
28
 * Runs each {@link FormatterGroup} in order. If a `FormatterGroup` succeeds, no further `FormatterGroup`s are run and the result is written to stdout (and ultimately to the Zed buffer).
29
 *
30
 * In other words, subsequent `FormatterGroup`s are used as fallbacks.
31
 *
32
 * If the `FormatterGroup` is an array, _all_ of the `Formatter`s in the array must succeed for the `FormatterGroup` to succeed.
33
 * - The output of each `Formatter` is used as the input for the next `Formatter` in the array.
34
 * - This allows you to chain multiple formatters together and use the combined results.
35
 *
36
 * @param formatterGroups One or more {@link FormatterGroup}, which is either a single {@link Formatter} or an array of {@link Formatter}
37
 * @returns void
38
 */
39
// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: it's fine
40
async function useFormatters(...formatterGroups: FormatterGroup[]) {
41
  let errors = ""
42

43
  for (const formatterGroup of formatterGroups) {
44
    if (Array.isArray(formatterGroup)) {
45
      let currentInput = stdin
46
      let allSucceeded = true
47
      let finalResult: FormatterResult | undefined
48

49
      for (const formatter of formatterGroup) {
50
        // biome-ignore lint/nursery/noAwaitInLoop: we need to wait for each formatter
51
        const result = await formatter(currentInput)
52
        const errorString = getFormatterErrorString(result)
53
        if (errorString) {
54
          errors += errorString
55
          allSucceeded = false
56
          break
57
        }
58

59
        // use output as input for next formatter
60
        currentInput = result.stdout
61
        finalResult = result
62
      }
63

64
      if (allSucceeded && finalResult) {
65
        process.stdout.write(`${finalResult.stdout}\n`)
66
        return
67
      }
68
    } else {
69
      const result = await formatterGroup(stdin)
70
      const errorString = getFormatterErrorString(result)
71
      if (errorString) {
72
        errors += errorString
73
        continue
74
      }
75

76
      process.stdout.write(`${result.stdout}\n`)
77
      return
78
    }
79
  }
80

81
  // if we got here, none of the formatters succeeded
82
  if (errors) process.stderr.write(`\n--------${errors}`)
83
  process.exitCode = 1
84
}
85

86
async function runFormatterCmd(cmd: string, input: string) {
87
  const { stdout, stderr, exitCode } = await $`echo ${input} | ${{ raw: cmd }}`.quiet().nothrow()
88
  return { stdout: stdout.toString().trim(), stderr: stderr.toString().trim(), exitCode }
89
}
90

91
const biome: Formatter = async (input) => {
92
  const biomeProjectCmd = `${cwd}/node_modules/.bin/biome`
93
  const identifier = `biome (${biomeProjectCmd})`
94
  const result: FormatterResult = {
95
    identifier,
96
    stdout: "",
97
    stderr: "",
98
    exitCode: 1,
99
  }
100

101
  const biomeBinaryExists = await Bun.file(biomeProjectCmd).exists()
102
  if (!biomeBinaryExists) {
103
    result.stderr = "skipped, biome binary not found"
104
    return result
105
  }
106

107
  const biomeConfigJsonExists = await Bun.file(`${cwd}/biome.json`).exists()
108
  const biomeConfigJsoncExists = await Bun.file(`${cwd}/biome.jsonc`).exists()
109
  if (!(biomeConfigJsonExists || biomeConfigJsoncExists)) {
110
    result.stderr = "skipped, no biome config found"
111
    return result
112
  }
113

114
  const { stdout, stderr, exitCode } = await runFormatterCmd(
115
    `"${biomeProjectCmd}" format --stdin-file-path="${bufferPath}" --write`,
116
    input,
117
  )
118

119
  result.stdout = stdout
120
  result.stderr = stderr
121
  result.exitCode = exitCode
122
  return result
123
}
124

125
const projectPrettier: Formatter = async (input) => {
126
  const prettierProjectCmd = `${cwd}/node_modules/.bin/prettier`
127
  const identifier = `prettier (${prettierProjectCmd})`
128
  const result: FormatterResult = {
129
    identifier,
130
    stdout: "",
131
    stderr: "",
132
    exitCode: 1,
133
  }
134

135
  const prettierBinaryExists = await Bun.file(prettierProjectCmd).exists()
136
  if (!prettierBinaryExists) {
137
    result.stderr = "skipped, prettier binary not found"
138
    return result
139
  }
140

141
  // if we don't give --find-config-path an argument, it won't check the cwd
142
  const prettierProjectConfig = (await $`prettier --find-config-path ' '`.quiet().nothrow().text()).trim()
143
  // if prettier doesn't find a config, the string will be empty
144
  if (!prettierProjectConfig) {
145
    result.stderr = "skipped, no prettier config found"
146
    return result
147
  }
148

149
  // prettier will look outside the cwd for a config, so the project config must exist within the cwd if we're going to use it (i.e. don't use the config if it starts with '../')
150
  if (prettierProjectConfig.startsWith("../")) {
151
    result.stderr = `skipped, the resolved config is outside the cwd (${prettierProjectConfig})`
152
    return result
153
  }
154

155
  const { stdout, stderr, exitCode } = await runFormatterCmd(
156
    `"${prettierProjectCmd}" --stdin-filepath "${bufferPath}"`,
157
    input,
158
  )
159

160
  result.stdout = stdout
161
  result.stderr = stderr
162
  result.exitCode = exitCode
163
  return result
164
}
165

166
const prettier: Formatter = async (input) => {
167
  const prettierCmd = Bun.which("prettier")
168
  const identifier = `prettier (${prettierCmd})`
169

170
  const { stdout, stderr, exitCode } = await runFormatterCmd(
171
    `"${prettierCmd}" --stdin-filepath "${bufferPath}" --config "${prettierConfigPath}"`,
172
    input,
173
  )
174

175
  return {
176
    identifier,
177
    stdout,
178
    stderr,
179
    exitCode,
180
  }
181
}
182

183
const fileExtension = path.extname(bufferPath)
184

185
if (fileExtension === ".astro") await useFormatters([projectPrettier, biome], prettier)
186
else await useFormatters(biome, projectPrettier, prettier)