Nginx Config Formatter
Line-break and indent by { } and ; to tidy up conf hierarchy
Nginx config formatter: the brace trap and why formatting is not validation
The syntax structure of nginx config
Nginx config syntax is minimal, just a few rules:
| Element | Form |
|---|---|
| Simple directive | directive arg1 arg2; — ends with a semicolon |
| Block directive | directive { ... } — brace-wrapped, no semicolon needed after |
| Comment | # to end of line |
| Variable | $variable, such as $host $request_uri $1 (regex capture) |
| Include | include /etc/nginx/conf.d/*.conf; |
Formatting just indents by brace level and line-breaks by semicolon. It looks simple, but there are real pitfalls.
Pitfall one: braces in strings and regex
The formatter counts braces to determine nesting, but braces can appear inside quoted strings or regular expressions:
- A quantifier in a regex:
location ~ ^/api/v[0-9]{2}/ { ... }— the{2}is misjudged as the start of a block, shifting all subsequent indentation. - Braces in a config value:
add_header X-Thing "a{b}c";— the quoted braces must not count toward nesting. - Variables and placeholders: the
$uriintry_files $uri $uri/ /index.html;must be preserved verbatim.
A robust implementation must first skip quoted content and recognise the regex context. If indentation suddenly "gets deeper and deeper" after formatting, a brace inside some regex was almost certainly taken for a block. This tool skips braces inside strings and comments when counting.
Pitfall two: formatting is not validation
This is the most important discipline. Formatting only adjusts whitespace; it never finds configuration errors:
| Error type | Will formatting catch it? |
|---|---|
| Missing semicolon | No. It stays missing and nginx errors on start |
Misspelled directive (such as proxy_pas) | No. It stays misspelled |
| Unmatched braces | May show as odd indentation, but the tool need not error |
| Directive in an illegal scope | No. This needs understanding of nginx's config inheritance rules |
The correct move: after formatting, check syntax with nginx -t (requires an nginx environment), or reload it in a test instance to verify. Before changing config in production you must do this — an nginx reload is graceful, but if the config has a syntax error the new worker will not start while the old one keeps serving, so you believe the change took effect when it did not.
Readability conventions
| Suggestion | Reason |
|---|---|
| Comment before each server block with its domain or purpose | One site often has several servers; matching by listen and server_name is slow |
| Order location rules from specific to general | Nginx prefix matching follows longest-match-first, not written order; but writing specific rules first aids human reading |
| Extract shared config into include files | SSL parameters, log formats, and security headers repeat across servers; extracting them enables unified maintenance |
| Indent with 4 spaces | Nginx's official examples use 4 spaces; mixing tabs muddles diffs |
The second row touches a rule easy to get wrong: location priority is decided by modifier and match length, not by written order. Exact match = wins first, then the longest prefix match, then regex matches (first hit in written order). So putting / first does not make it win.
How to use the tool
Paste the nginx config, click format, and it re-line-breaks and indents by { } and ;; braces inside strings and comments are not miscounted. It suits tidying a compressed config copied from a server, diffing two environments, and unifying format before review.
Processing runs locally in your browser; the domains, backend addresses, and paths in the config are not uploaded. After editing, remember to run nginx -t before reloading.
FAQ
Will content inside quotes be split incorrectly?
No. Content within double or single quotes is preserved as a whole and will not be wrongly broken by ; or { inside it.
Does it support blocks like if / upstream?
Yes. Any block wrapped in { } is indented correctly, matching the official config hierarchy.