# Replace a transitive package with another package using pnpm

Sometimes a dependency brings in a package that is compatible enough to replace,
but is larger or less maintained than an alternative. With pnpm, you can replace
that transitive dependency without forking or patching its consumer.

For example, `mdx-bundler` depends on `gray-matter`, but `gray-matter` has been
unmaintained for years and uses an old version of `js-yaml`. If
[`@11ty/gray-matter`](https://e18e.dev/docs/replacements/gray-matter) has the
exact same API surface, tell pnpm to resolve that dependency edge to the
replacement package instead.

Add this to the root `pnpm-workspace.yaml`:

```yaml title="pnpm-workspace.yaml"
overrides:
  'mdx-bundler>gray-matter': 'npm:@11ty/gray-matter@3.0.0'
```

The `npm:` protocol creates an alias: code inside `mdx-bundler` still imports
`gray-matter`, while pnpm installs `@11ty/gray-matter` at that location. The
`mdx-bundler>` prefix keeps the change scoped to that package, so other users of
`gray-matter` in the dependency graph are unaffected.

Run `pnpm install` afterwards to update the lockfile. This is a dependency
resolution change, not a source patch, so it is easy to review and remove.

An override is still an integration decision: verify the replacement's module
format, types, and the API paths your dependency actually uses. The
[e18e gray-matter replacement page](https://e18e.dev/docs/replacements/gray-matter)
is a useful starting point for evaluating that swap.