Node.js Project Guardrails
Enforce Node.js-specific project standards including lockfile presence, TypeScript configuration, engine version pinning, and minimum Node.js version requirements for code and CI environments.
nodejs to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/nodejs@v1.0.0
Included Guardrails
This policy includes 5 guardrails that enforce standards for your devex build and ci.
lockfile-exists
Ensures a package lockfile exists (package-lock.json, yarn.lock, or pnpm-lock.yaml). Lockfiles are essential for reproducible builds and dependency integrity.
typescript-configured
Ensures TypeScript is configured via tsconfig.json. TypeScript provides type safety and improved developer experience.
engines-pinned
Ensures the engines.node field is set in package.json. Pinning the Node.js engine version prevents compatibility issues across environments.
min-node-version
Ensures the Node.js version detected in the project meets the minimum required version. Helps maintain security and compatibility standards.
min-node-version-cicd
Ensures the Node.js version used in CI/CD commands meets the minimum required version. Helps maintain security and compatibility standards for build environments.
How Guardrails Fit into Lunar
Lunar guardrails define your engineering standards as code. They evaluate data collected by integrations and produce pass/fail checks with actionable feedback.
Policies support gradual enforcement—from silent scoring to blocking PRs or deployments—letting you roll out standards at your own pace without disrupting existing workflows.
Learn How Lunar Works →Required Integrations
This policy evaluates data gathered by one or more of the following integration(s).
Make sure to enable them in your lunar-config.yml.
Configuration
Configure this policy in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
min_node_version
|
Optional |
18
|
Minimum required Node.js major version (e.g., "18", "20") |
min_node_version_cicd
|
Optional |
18
|
Minimum required Node.js major version for CI/CD commands (e.g., "18", "20") |
Documentation
View on GitHubNode.js Project Guardrails
Enforce Node.js-specific project standards including lockfile presence, TypeScript configuration, engine version pinning, and minimum Node.js version requirements.
Overview
This policy validates Node.js projects against best practices for package management and project structure. It ensures projects have lockfiles for reproducible builds, TypeScript for type safety, pinned engine versions, and meet minimum Node.js version requirements in both code and CI environments.
Policies
This plugin provides the following policies (use include to select a subset):
| Policy | Description |
|---|---|
lockfile-exists |
Validates a lockfile exists (package-lock.json, yarn.lock, or pnpm-lock.yaml) |
typescript-configured |
Validates tsconfig.json exists |
engines-pinned |
Ensures engines.node is set in package.json |
min-node-version |
Ensures minimum Node.js version |
min-node-version-cicd |
Ensures minimum Node.js version in CI/CD |
Required Data
This policy reads from the following Component JSON paths:
| Path | Type | Provided By |
|---|---|---|
.lang.nodejs |
object | nodejs collector |
.lang.nodejs.package_lock_exists |
boolean | nodejs collector |
.lang.nodejs.yarn_lock_exists |
boolean | nodejs collector |
.lang.nodejs.pnpm_lock_exists |
boolean | nodejs collector |
.lang.nodejs.tsconfig_exists |
boolean | nodejs collector |
.lang.nodejs.engines_node |
string | nodejs collector |
.lang.nodejs.version |
string | nodejs collector |
.lang.nodejs.cicd.cmds |
array | nodejs collector |
Note: Ensure the corresponding collector(s) are configured before enabling this policy.
Installation
Add to your lunar-config.yml:
policies:
- uses: github://earthly/lunar-lib/policies/nodejs@v1.0.0
on: [nodejs] # Or use tags like ["domain:frontend"]
enforcement: report-pr
# include: [lockfile-exists, typescript-configured] # Only run specific checks
with:
min_node_version: "18" # Minimum required Node.js major version (default: "18")
min_node_version_cicd: "18" # Minimum Node.js version for CI/CD commands (default: "18")
Examples
Passing Example
{
"lang": {
"nodejs": {
"version": "20.11.0",
"package_lock_exists": true,
"tsconfig_exists": true,
"engines_node": ">=18"
}
}
}
Failing Example
{
"lang": {
"nodejs": {
"version": "16.20.0",
"package_lock_exists": false,
"yarn_lock_exists": false,
"pnpm_lock_exists": false,
"tsconfig_exists": false
}
}
}
Failure messages:
"No lockfile found. Run 'npm install', 'yarn install', or 'pnpm install' to generate a lockfile and commit it to version control.""TypeScript is not configured. Add a tsconfig.json to enable type checking.""engines.node is not set in package.json.""Node.js version 16.20.0 is below minimum 18."
Remediation
When this policy fails, you can resolve it by:
- lockfile-exists: Run
npm install,yarn install, orpnpm installto generate a lockfile and commit it to version control. - typescript-configured: Run
npx tsc --initto generate a tsconfig.json and configure compiler options. - engines-pinned: Add
"engines": { "node": ">=18" }to package.json to communicate the required version. - min-node-version: Update your project's Node.js version and
.nvmrc,.node-version, orengines.node. - min-node-version-cicd: Update your CI/CD pipeline (GitHub Actions
node-versionor Docker base image).
Open Source
This policy is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore how individual guardrails work with specific integrations.
Ready to Automate Your Standards?
See how Lunar can turn your engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
Infrastructure conventions
Post-mortem action items
Security & compliance policies
Testing & quality requirements