{"id":25989,"library":"nginx-lint-plugin","title":"nginx-lint-plugin","description":"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.","status":"active","version":"0.10.5","language":"javascript","source_language":"en","source_url":"https://github.com/walf443/nginx-lint","tags":["javascript","typescript"],"install":[{"cmd":"npm install nginx-lint-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add nginx-lint-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add nginx-lint-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for compiling plugins to WebAssembly Component Model format","package":"@bytecodealliance/jco","optional":false},{"reason":"Used by jco to componentize JavaScript modules into WebAssembly components","package":"@bytecodealliance/componentize-js","optional":false}],"imports":[{"note":"Config is a type-only export. Use `import type` to avoid runtime issues in transpiled code.","wrong":"import { Config } from 'nginx-lint-plugin'","symbol":"Config","correct":"import type { Config } from 'nginx-lint-plugin'"},{"note":"This package is ESM-only since v0.8.0. CommonJS require() will not work.","wrong":"const { LintError } = require('nginx-lint-plugin')","symbol":"LintError","correct":"import type { LintError } from 'nginx-lint-plugin'"},{"note":"PluginSpec is a type-only export.","wrong":"import { PluginSpec } from 'nginx-lint-plugin'","symbol":"PluginSpec","correct":"import type { PluginSpec } from 'nginx-lint-plugin'"},{"note":"PluginTestRunner is exported from a subpath export 'nginx-lint-plugin/testing', not the main entry.","wrong":"import { PluginTestRunner } from 'nginx-lint-plugin'","symbol":"PluginTestRunner","correct":"import { PluginTestRunner } from 'nginx-lint-plugin/testing'"}],"quickstart":{"code":"// src/plugin.ts\nimport type { Config, LintError, PluginSpec } from 'nginx-lint-plugin';\n\nexport function spec(): PluginSpec {\n  return {\n    name: 'no-proxy-pass-http',\n    category: 'best-practices',\n    description: 'Disallow HTTP proxy_pass',\n    apiVersion: '1.0',\n    severity: 'warning',\n  };\n}\n\nexport function check(cfg: Config, path: string): LintError[] {\n  const errors: LintError[] = [];\n  for (const ctx of cfg.allDirectivesWithContext()) {\n    const directive = ctx.directive;\n    if (directive.is('proxy_pass') && !directive.hasBlock()) {\n      errors.push({\n        rule: 'no-proxy-pass-http',\n        category: 'best-practices',\n        message: 'proxy_pass should use https',\n        severity: 'warning',\n        line: directive.line(),\n        column: directive.column(),\n        fixes: [directive.replaceWith('proxy_pass https://upstream;')],\n      });\n    }\n  }\n  return errors;\n}","lang":"typescript","description":"Shows how to define a simple nginx-lint plugin with spec and check functions, using the TypeScript SDK."},"warnings":[{"fix":"Use the rowan-based CST parser via parseConfig or PluginTestRunner instead.","message":"parse_string_legacy and legacy parser/lexer code removed in v0.10.0","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"If your plugin depends on the old AST structure, update to use the new CST API or pin to v0.8.x.","message":"parse_string() behavior changed in v0.9.0 to use new CST parser","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Upgrade to >=0.8.3 or manually include the wit directory in your project.","message":"The npm package does not include the 'wit' directory in older versions; ensure you are using v0.8.3 or later","severity":"gotcha","affected_versions":"<0.8.3"},{"fix":"Use ES module imports (import ... from 'nginx-lint-plugin') and set \"type\": \"module\" in package.json.","message":"CommonJS (require) is not supported. This package is ESM-only.","severity":"deprecated","affected_versions":">=0.8.0"},{"fix":"Ensure your bundler supports package.json exports field; or use Node.js test runner directly.","message":"The 'testing' subpath export is only available if using Node.js with ESM; it may not resolve with certain bundlers.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Switch to ESM (\"type\": \"module\" in package.json) and use a bundler like esbuild that respects exports.","cause":"Importing from 'nginx-lint-plugin/testing' in a CommonJS context or with a bundler that does not support exports field.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'nginx-lint-plugin/testing'"},{"fix":"Ensure you are receiving the Config object from the plugin runtime, not from a direct import.","cause":"Using the Config type incorrectly, e.g., trying to call methods on a non-object value.","error":"TypeError: Cannot read properties of undefined (reading 'allDirectivesWithContext')"},{"fix":"Upgrade nginx-lint-plugin to v0.8.3 or later.","cause":"Missing the 'wit' directory in older versions of the npm package (pre-v0.8.3).","error":"Error: WIT file not found: node_modules/nginx-lint-plugin/wit"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}