remark-lint "Could not find module" plugin failure in CI

By Kaveh Alemi·Latchkey

remark loads the presets and plugins named in .remarkrc from node_modules. If a preset like remark-preset-lint-recommended is not installed, remark fails to resolve it before linting any Markdown.

What this error means

remark exits with "Error: Could not find module remark-preset-lint-recommended" or "Cannot find package", even though .remarkrc lists it.

docs/guide.md
  1:1  error  Error: Cannot find package 'remark-preset-lint-recommended'
              imported from .remarkrc.js

x 1 error

Common causes

The preset or plugin is not a dependency

The .remarkrc references a package that is not in package.json, so CI never installs it.

Dependencies were not installed before remark ran

The workflow ran remark before npm ci, or in a directory without the installed node_modules.

How to fix it

Install the presets and run after npm ci

1. Add remark and every referenced preset/plugin to devDependencies.
2. Run npm ci before the remark step.
3. Invoke remark with npx so node_modules/.bin is on PATH.

- run: npm ci
- run: npx remark docs/ --frail

Declare plugins in a resolvable .remarkrc

List presets by installed package name so remark resolves them from node_modules.

{
  "plugins": [
    "remark-preset-lint-recommended",
    "remark-lint-list-item-indent"
  ]
}

How to prevent it

• Keep every referenced remark preset/plugin in devDependencies.
• Run npm ci before remark and call it via npx.
• Use --frail so lint warnings fail CI deterministically.

Frequently asked questions

Related guides

References

• GitHub Actions documentation