soulteary/nginx-formatter repository overview

⁠Nginx Formatter

ENGLISH⁠ | 中文文档⁠

Nginx configuration formatter ~10MB size, support CLI, WebUI, x86, ARM, Linux, macOS.

⁠Download

Download the binaries for your system and architecture from the releases page⁠.

If you use docker, you can use the following command (DockerHub⁠):

docker pull soulteary/nginx-formatter:latest
docker pull soulteary/nginx-formatter:v2.2.0

⁠Homebrew

On macOS / Linux you can install it via Homebrew⁠:

brew tap soulteary/tap
brew install soulteary/tap/nginx-formatter

After installation the nginx-formatter command is available globally, so you can run it directly (without the ./ prefix used below):

nginx-formatter serve

To upgrade or uninstall later:

brew upgrade soulteary/tap/nginx-formatter
brew uninstall nginx-formatter

⁠Usage

Since v2.2.0 the CLI uses semantic subcommands (format / serve / version) with modern --long/-short flags. The old single-dash long flags (-input, -output, -indent, -char, -web, -port) remain fully supported for backward compatibility, so existing scripts and Docker commands keep working.

Use default parameters to format all configuration files in the current directory:

./nginx-formatter format

⁠Common Usage (CLI & WebUI)

Use different indentation symbols (you can use spaces, tabs, space, tab, \s, \t) and indentation amounts:

./nginx-formatter format -n 4 -c space

⁠CLI Usage

Format the configuration file in the specified directory:

./nginx-formatter format -i ./your-dir-path

Format a directory and save it in a new directory:

./nginx-formatter format -i ./your-dir-path -o ./your-output-dir

Format a single file: when --input points to a file, only that file is formatted (any file extension is accepted, not just .conf). The --output value has three meanings in single-file mode:

• empty: overwrite the input file in place
• an existing directory: write to <output-dir>/<original-file-name>
• otherwise: treat it as a target file path, creating the parent directory if needed

# overwrite in place
./nginx-formatter format -i ./nginx.conf

# write into an existing directory
./nginx-formatter format -i ./nginx.conf -o ./dist

# write to a specific file path
./nginx-formatter format -i ./nginx.conf -o ./dist/nginx.formatted.conf

⁠WebUI Usage

Start the web interface:

./nginx-formatter serve

specified the port:

./nginx-formatter serve -p 8123

--indent and --char set the default indentation the WebUI applies when formatting:

./nginx-formatter serve -p 8123 -n 4 -c space

⁠Version

Print the version:

./nginx-formatter version

⁠Backward compatibility (legacy flags)

Old-style single-dash long flags still work exactly as before:

# Format a directory (legacy)
./nginx-formatter -input=./your-dir-path -output=./your-output-dir -indent=4 -char=" "

# Format a single file (legacy)
./nginx-formatter -input=./nginx.conf

# Start the WebUI (legacy)
./nginx-formatter -web -port=8123

⁠Docker Usage

There is no difference between using parameters in Docker and the above, for example, we start a Web UI formatting tool service in Docker:

# new subcommand style
docker run --rm -it -p 8080:8080 soulteary/nginx-formatter:latest serve

# legacy style still works
docker run --rm -it -p 8080:8080 soulteary/nginx-formatter:latest -web

If you want to format the configuration of the current directory, you can use the program in Docker with a command similar to the following:

# new subcommand style
docker run --rm -it -v `pwd`:/app soulteary/nginx-formatter:latest format -i /app

# legacy style still works
docker run --rm -it -v `pwd`:/app soulteary/nginx-formatter:latest -input=/app

⁠Full parameters supported

Run nginx-formatter --help to see the available commands, or nginx-formatter <command> --help for a command's flags and examples:

Usage:
  nginx-formatter [flags]
  nginx-formatter [command]

Available Commands:
  format      Format Nginx configuration files in a directory or a single file
  serve       Start the browser-based WebUI
  version     Print the version number

Flags:
  -h, --help      help for nginx-formatter
  -v, --version   version for nginx-formatter

format flags:

  -c, --char string     Indent char (space/tab/\s/\t) (default " ")
  -n, --indent int      Indent size (default 2)
  -i, --input string    Input directory or file (default: current directory)
  -o, --output string   Output directory or file path

serve flags:

  -c, --char string   Default indent char the WebUI applies (space/tab/\s/\t) (default " ")
  -n, --indent int    Default indent size the WebUI applies (default 2)
  -p, --port int      WebUI port (default 8080)

⁠Contributing

Contributions are welcome! Please read the Contributing Guide⁠ to get started, and follow the Code of Conduct⁠.

⁠Credits

Formatter Components

• Slomkowski Created a beautifier for nginx config files with Python under [Apache-2.0 license], 24/06/2016
  • https://github.com/1connect/nginx-config-formatter⁠ (https://github.com/slomkowski/nginx-config-formatter⁠)
• Yosef Ported the JavaScript beautifier under [Apache-2.0 license], 24/08/2016
  • https://github.com/vasilevich/nginxbeautifier⁠
• soulteary Modify the JavaScript version for golang execution, under [Apache-2.0 license], 18/04/2023:
  • simplify the program, fix bugs, improve running speed, and allow running in golang
  • https://github.com/soulteary/nginx-formatter⁠
• soulteary Rewrote the formatter with a native Go AST-based nginx parser (dropping the JavaScript runtime), under [Apache-2.0 license], since v2.0.0:
  • https://github.com/soulteary/nginx-formatter⁠

Web Components

• Fiber is an Express inspired web framework written in Go (Golang), under [MIT license].
  • https://github.com/gofiber/fiber⁠
• Code Mirror, in-browser code editor, under [MIT license].
  • https://github.com/codemirror/codemirror5⁠