Prettier for NGINX

1.0.3 verified Sat Apr 25 auth: no javascript

prettier-plugin-nginx is a Prettier plugin that formats NGINX configuration files (.nginx, .nginxconf). Version 1.0.3 ships TypeScript types and targets modern Prettier (v2+). It is written in TypeScript and depends only on Prettier. Differentiators: opinionated formatting with configurable alignment, parameter wrapping, and continuation indentation; supports standard NGINX directives but not extensions like lua-nginx-module. Release cadence is low; last release was 2024.

Common errors

error Error: Cannot find module 'prettier-plugin-nginx' ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install --save-dev prettier-plugin-nginx

error [error] Invalid parser option: 'nginx' ↓

cause Prettier version <2.0 or plugin not loaded properly.

fix

Ensure Prettier >=2.0 and pass plugin via plugins array.

error TypeError: prettier.format is not a function ↓

cause Using wrong import (default vs named) for Prettier.

fix

Use import prettier from 'prettier' (ESM) or const prettier = require('prettier') (CJS).

Warnings

gotcha Plugin does not support lua-nginx-module or other multi-language extensions; embedded code will break. ↓

fix Avoid using with configs containing Lua blocks, or handle those manually.

gotcha Plugin only formats .nginx and .nginxconf files by default; other extensions require explicit parser override. ↓

fix Set parser to 'nginx' in Prettier options or rename files.

breaking v1.0.0 introduced named exports for configuration options; previous versions used plugin-local options only. ↓

fix Upgrade to v1.0.0+ and use named exports like `alignUniversally` if needed.

Install

npm install prettier-plugin-nginx

yarn add prettier-plugin-nginx

pnpm add prettier-plugin-nginx

Imports

default
wrong
```
const prettier = require('prettier-plugin-nginx')
```
correct
```
import prettier from 'prettier-plugin-nginx'
```
Plugin is used via Prettier API, not direct default import. Use Prettier's resolver.

Pugins

wrong

const options = { plugins: [require('prettier-plugin-nginx')] }

correct

import * as prettier from 'prettier'; const options = { plugins: ['prettier-plugin-nginx'] }

Pass the plugin name string to Prettier options; Prettier resolves it.

alignUniversally

wrong

const alignUniversally = require('prettier-plugin-nginx').alignUniversally

correct

import { alignUniversally } from 'prettier-plugin-nginx'

Named exports for options available since v1. Prettier imports these via plugin options.

Quickstart

Formats an NGINX config string using Prettier with the plugin, enabling directive alignment and parameter wrapping.

import prettier from 'prettier';
import nginxPlugin from 'prettier-plugin-nginx';

const code = `server {
    listen 80;
    server_name example.com;
    location / { proxy_pass http://proxy; } }`;

prettier.format(code, {
  parser: 'nginx',
  plugins: [nginxPlugin],
  alignDirectives: true,
  wrapParameters: true
}).then(result => console.log(result));