Registry / devops / nginx-lint-plugin

nginx-lint-plugin

library0.10.5jsnpmunverified

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.

devops testing

npm install nginx-lint-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · NGINX-LINT-PLUGIN

nginx-lint-plugin

devopsjavascriptv0.10.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Config

✓ import type { Config } from 'nginx-lint-plugin'

✗ import { Config } from 'nginx-lint-plugin'

Config is a type-only export. Use `import type` to avoid runtime issues in transpiled code.

LintError

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

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

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

PluginSpec

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

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

PluginSpec is a type-only export.

PluginTestRunner

✓ import { PluginTestRunner } from 'nginx-lint-plugin/testing'

✗ import { PluginTestRunner } from 'nginx-lint-plugin'

PluginTestRunner is exported from a subpath export 'nginx-lint-plugin/testing', not the main entry.

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; }

Debug

Known issues

breakingparse_string_legacy and legacy parser/lexer code removed in v0.10.0

fix

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

affects: >=0.10.0

breakingparse_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.

affects: >=0.9.0

gotchaThe 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.

affects: <0.8.3

deprecatedCommonJS (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.

affects: >=0.8.0

gotchaThe '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.

affects: *

Errors

Common errors & fixes

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

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.

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

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: WIT file not found: node_modules/nginx-lint-plugin/wit

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.

Upgrade

Version history

0.10.5latest on npm

Audit

Dependencies

@bytecodealliance/jcorequiredRequired for compiling plugins to WebAssembly Component Model format

@bytecodealliance/componentize-jsrequiredUsed by jco to componentize JavaScript modules into WebAssembly components

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/walf443/nginx-lint ↗

packagehttps://www.npmjs.com/package/nginx-lint-plugin ↗