nginx-lint-plugin

0.10.5 verified Fri May 01 auth: no javascript

TypeScript SDK for writing nginx-lint plugins, version 0.10.5. This package provides types, WIT definitions, and testing utilities for creating WebAssembly Component Model plugins that run in the nginx-lint CLI. Plugins are written in TypeScript (ESM-only), compiled via JCO to WebAssembly, and loaded at runtime. Key features include a PluginTestRunner for unit tests, parseConfig for simulating include contexts, and support for the rowan-based CST parser introduced in v0.9.0. Compared to direct nginx config parsing, this SDK offers a structured plugin API with versioned specifications and automatic integration with nginx-lint's linting pipeline. Release cadence is roughly monthly, with frequent dependency updates.

Common errors

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'nginx-lint-plugin/testing' ↓

cause Importing from 'nginx-lint-plugin/testing' in a CommonJS context or with a bundler that does not support exports field.

fix

Switch to ESM ("type": "module" in package.json) and use a bundler like esbuild that respects exports.

error TypeError: Cannot read properties of undefined (reading 'allDirectivesWithContext') ↓

cause Using the Config type incorrectly, e.g., trying to call methods on a non-object value.

fix

Ensure you are receiving the Config object from the plugin runtime, not from a direct import.

error Error: WIT file not found: node_modules/nginx-lint-plugin/wit ↓

cause Missing the 'wit' directory in older versions of the npm package (pre-v0.8.3).

fix

Upgrade nginx-lint-plugin to v0.8.3 or later.

Warnings

breaking parse_string_legacy and legacy parser/lexer code removed in v0.10.0 ↓

fix Use the rowan-based CST parser via parseConfig or PluginTestRunner instead.

breaking parse_string() behavior changed in v0.9.0 to use new CST parser ↓

fix If your plugin depends on the old AST structure, update to use the new CST API or pin to v0.8.x.

gotcha The npm package does not include the 'wit' directory in older versions; ensure you are using v0.8.3 or later ↓

fix Upgrade to >=0.8.3 or manually include the wit directory in your project.

deprecated CommonJS (require) is not supported. This package is ESM-only. ↓

fix Use ES module imports (import ... from 'nginx-lint-plugin') and set "type": "module" in package.json.

gotcha The 'testing' subpath export is only available if using Node.js with ESM; it may not resolve with certain bundlers. ↓

fix Ensure your bundler supports package.json exports field; or use Node.js test runner directly.

Install

npm install nginx-lint-plugin

yarn add nginx-lint-plugin

pnpm add nginx-lint-plugin

Imports

Config
wrong
```
import { Config } from 'nginx-lint-plugin'
```
correct
```
import type { Config } from 'nginx-lint-plugin'
```
Config is a type-only export. Use `import type` to avoid runtime issues in transpiled code.

LintError

wrong

const { LintError } = require('nginx-lint-plugin')

correct

import type { LintError } from 'nginx-lint-plugin'

This package is ESM-only since v0.8.0. CommonJS require() will not work.

PluginSpec

wrong

import { PluginSpec } from 'nginx-lint-plugin'

correct

import type { PluginSpec } from 'nginx-lint-plugin'

PluginSpec is a type-only export.

PluginTestRunner
wrong
```
import { PluginTestRunner } from 'nginx-lint-plugin'
```
correct
```
import { PluginTestRunner } from 'nginx-lint-plugin/testing'
```
PluginTestRunner is exported from a subpath export 'nginx-lint-plugin/testing', not the main entry.

Quickstart

Shows how to define a simple nginx-lint plugin with spec and check functions, using the TypeScript SDK.

// src/plugin.ts
import type { Config, LintError, PluginSpec } from 'nginx-lint-plugin';

export function spec(): PluginSpec {
  return {
    name: 'no-proxy-pass-http',
    category: 'best-practices',
    description: 'Disallow HTTP proxy_pass',
    apiVersion: '1.0',
    severity: 'warning',
  };
}

export function check(cfg: Config, path: string): LintError[] {
  const errors: LintError[] = [];
  for (const ctx of cfg.allDirectivesWithContext()) {
    const directive = ctx.directive;
    if (directive.is('proxy_pass') && !directive.hasBlock()) {
      errors.push({
        rule: 'no-proxy-pass-http',
        category: 'best-practices',
        message: 'proxy_pass should use https',
        severity: 'warning',
        line: directive.line(),
        column: directive.column(),
        fixes: [directive.replaceWith('proxy_pass https://upstream;')],
      });
    }
  }
  return errors;
}