@astrojs/mdx imports satteri but does not declare it (pnpm ERR_MODULE_NOT_FOUND)

[grant]

Astro Info

Astro                    v7.0.6
Node                     v22+
System                   macOS / Linux
Package Manager          pnpm
Output                   static
Adapter                  none
Integrations             @astrojs/mdx

If this issue only occurs in one browser, which browser is a problem?

N/A (build / Node module resolution)

Describe the Bug

@astrojs/mdx statically imports satteri in its Sätteri MDX entrypoints, for example:

https://github.com/withastro/astro/blob/@astrojs/mdx@7.0.3/packages/integrations/mdx/src/satteri/index.ts

import {
	mdxToJs,
	// ...
} from 'satteri';

But packages/integrations/mdx/package.json does not list satteri in dependencies. It only declares optional peer @astrojs/markdown-satteri (which itself depends on satteri), and historically kept satteri in devDependencies only.

With pnpm's isolated node_modules and a normal Astro + MDX project (integrations: [mdx()] + an .mdx page):

1. There is no satteri symlink beside @astrojs/mdx
2. astro build often still succeeds by walking up to node_modules/.pnpm/node_modules/satteri
3. When that link is missing, astro build fails while compiling MDX:

[ERROR] [vite] ✗ Build failed
Cannot find package 'satteri' imported from
.../node_modules/@astrojs/mdx/dist/satteri/index.js
  at .../@astrojs/mdx/dist/vite-plugin-mdx.js

Reproduced on @astrojs/mdx@7.0.3. main still omits satteri from @astrojs/mdx dependencies.

Related: #17072 addressed optional Sätteri loading for the Container API path, but does not declare satteri for the default Sätteri MDX processor path used when @astrojs/markdown-satteri is present (pulled in by astro itself on Astro 7).

What's the expected result?

astro build on an MDX page should succeed under pnpm without relying on an accidental .pnpm/node_modules/satteri link. satteri should be a declared dependency of @astrojs/mdx so pnpm links it into @astrojs/mdx's isolated node_modules.

Link to Minimal Reproducible Example

https://github.com/grant/astro-mdx-satteri-undeclared-dep-repro

Minimal Astro project with:

• astro.config.mjs → integrations: [mdx()]
• src/pages/post.mdx → MDX page compiled during astro build

pnpm install
pnpm repro

pnpm repro runs a real astro build twice:

1. With .pnpm/node_modules/satteri present → build succeeds
2. After temporarily removing that link → astro build fails with Cannot find package 'satteri' from @astrojs/mdx/dist/satteri/index.js

Manual steps are also in the README.

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Yes — satteri is not declared in @astrojs/mdx's dependencies despite static from 'satteri' imports in src/satteri/*.ts; in an isolated pnpm node_modules layout, Node cannot resolve the bare specifier.
• Exploration: Yes — View branch
• Unit Test: No — the existing mdx-satteri.test.ts tests pass (the monorepo hoists satteri), and a unit test can't meaningfully simulate pnpm's strict isolation.
• Priority: P4: important. This is a build-breaking error for pnpm users when the accidental hoisted link is absent (e.g. Vercel monorepo deploys). It violates Node's module resolution contract by importing an undeclared dependency.

@astrojs/mdx has four source files under src/satteri/ that use bare from 'satteri' imports (index.ts, hast-astro-metadata.ts, jsx-utils.ts, hast-images-to-component.ts). These are reached at runtime via a dynamic import('./satteri/index.js') in vite-plugin-mdx.ts whenever the active markdown processor is Sätteri (the default in Astro 7). However, satteri was only listed as a devDependency — never as a runtime dependency — so pnpm doesn't create a symlink for it inside @astrojs/mdx's isolated node_modules.

I found a potential fix for this issue. The fix moves satteri from devDependencies to dependencies in packages/integrations/mdx/package.json, ensuring pnpm always links it into @astrojs/mdx's node_modules so the bare import resolves correctly. All existing MDX tests (including mdx-satteri.test.ts) continue to pass.

Try this fix

You can test this fix right now without waiting for a release:

pnpm add https://pkg.pr.new/@astrojs/mdx@42ecd2d

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Reproduction

Confirmed that @astrojs/mdx statically imports satteri in production source code but does not declare it as a dependency:

• Files with from 'satteri' imports:

  • packages/integrations/mdx/src/satteri/index.ts (line 18) — imports mdxToJs, HastNode, HastPluginDefinition, MdastPluginDefinition, MdxCompileOptions
  • packages/integrations/mdx/src/satteri/hast-astro-metadata.ts (line 9)
  • packages/integrations/mdx/src/satteri/jsx-utils.ts (line 1)
  • packages/integrations/mdx/src/satteri/hast-images-to-component.ts (line 6)

• package.json before fix:

  • dependencies.satteri: not present
  • peerDependencies.satteri: not present
  • devDependencies.satteri: ^0.9.1 (only used for tests in the monorepo)

Isolated resolution test (simulating strict pnpm node_modules) confirmed ERR_MODULE_NOT_FOUND when satteri is not in @astrojs/mdx's own node_modules.

Root Cause

The original commit 5bfde1ad9a ("feat(mdx): add satteri MDX pipeline") added satteri only to devDependencies and as an optional peer via @astrojs/markdown-satteri. The bare from 'satteri' imports in src/satteri/*.ts are production code reached via vite-plugin-mdx.ts line ~105 when isSatteriProcessor() returns true. In npm/yarn flat layouts or in the monorepo, satteri resolves through hoisting. In pnpm's strict isolated node_modules, there is no link from @astrojs/mdx to satteri, causing ERR_MODULE_NOT_FOUND.

Fix

Moved satteri: "^0.9.1" from devDependencies to dependencies in packages/integrations/mdx/package.json. This is the minimal correct fix — the package has unconditional static imports of satteri in its production source, so it must declare the dependency.

Verification

• pnpm -C packages/integrations/mdx build — builds successfully
• mdx-satteri.test.ts — all 5 tests pass
• mdx-page.test.ts — all 10 tests pass
• Isolated resolution test confirms satteri resolves from @astrojs/mdx when present in its node_modules

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[ematipico]

I would appreciate if you created a reproduction via Astro usage, not a script that doesn't use Astro at all.

[grant]

OK, I can create a full repro with Astro usage, although I think the explanation from myself and astrobot for the 1 line dep fix is very clear.

[grant]

Updated — thanks for the note.

The reproduction is now a minimal Astro + MDX project that fails during a real astro build (not a bare Node import):

https://github.com/grant/astro-mdx-satteri-undeclared-dep-repro

• astro.config.mjs with integrations: [mdx()]
• src/pages/post.mdx
• pnpm repro runs astro build, then removes the accidental .pnpm/node_modules/satteri link and runs astro build again → ERR_MODULE_NOT_FOUND for satteri from @astrojs/mdx/dist/vite-plugin-mdx.js

Issue description updated accordingly. Fix PR: #17372