# What changed in npm-to-yarn

> 72 changes in npm-to-yarn 2 to 3 from its official release notes, upgrade guides and advisories: 38 breaking, 6 deprecations, 11 new APIs and options. Each one cited. Sources checked 2026-10-19. HTML: https://unstale.sh/npm/npm-to-yarn/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## npm-to-yarn 3

### Breaking changes

- The MDX parser now follows CommonMark emphasis rules more strictly, changing how emphasis markers next to spaces or punctuation are parsed. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docs-related theme components were significantly refactored, so existing swizzled component customizations may break. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- The official TypeScript config package replaces @tsconfig/docusaurus; extend @docusaurus/tsconfig in tsconfig.json. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- The node-emoji upgrade adds many emojis and removes old shortcode names that are no longer valid on GitHub. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- The blog RSS feed is limited to its last 20 entries by default; set limit to false for an unlimited feed. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- This dependency is no longer necessary in Docusaurus v3 and can be removed if nothing else uses it. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- MDX no longer transforms indented text into code blocks; use regular fenced code block syntax instead. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus v3 parses directives; unhandled directives are ignored instead of being rendered in their original form. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- This compatibility option allows the Docusaurus v2 explicit heading ID syntax, which is otherwise invalid MDX; the notes recommend keeping it enabled for now. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- MDX v3 compiles Markdown more strictly, so some content that compiled under Docusaurus v2 may fail or render differently. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Custom mappings are sandboxed: native Markdown mappings apply to Markdown syntax, and lower-cased custom element names are no longer substituted. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus v3 requires Node.js 18.0 or later; Node.js 16 is no longer supported. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus v3 requires React 18.0 or later. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Use rehype-katex 7 with Docusaurus v3 and MDX v3; other versions are not guaranteed to work. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Use remark-math 6 with Docusaurus v3 and MDX v3; other versions are not guaranteed to work. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Official Unified, Remark, and Rehype packages are ES Modules only, so CommonJS require() no longer works for them. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Fewer languages are included by default, so configure additional languages to keep highlighting them. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Import themes from the themes export of prism-react-renderer instead of importing theme paths directly. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus v3 uses TypeScript 5.1 or later. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus v3 requires TypeScript 5.1 or newer. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Versioned sidebar entries no longer support the versioned prefix; remove it from sidebar paths. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)

### Deprecations

- The caution admonition is deprecated; refactor it to :::warning or :::danger. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- This compatibility option allows HTML comments in MDX; the notes recommend replacing them with MDX comments before turning it off. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)

### New APIs and options

- Deno support was added to npm-to-yarn. (3.1.0) — [release notes](https://github.com/bgub/npm-to-yarn/releases/tag/v3.1.0)
- Docusaurus v3 supports ES Module configuration files, allowing Remark plugins to be imported directly. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus v3 supports ESM and TypeScript config files. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- This compatibility option allows the Docusaurus v2 admonition title syntax; the new directive label syntax uses square brackets. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)

### Behavior and default changes

- The default blog truncate marker now accepts both the HTML comment marker and the MDX comment marker. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus switches config loading from import-fresh to jiti; existing config files should keep working, but subtle behavior changes could occur. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Use the .mdx extension for Markdown files containing JSX, imports, or exports; future versions will parse .md files as CommonMark. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Docusaurus support for React 18 features such as Suspense, React.lazy(), and startTransition is experimental and may have different runtime behavior in the future. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- The automatic JSX runtime means JSX files no longer need to import React when they do not use a React API. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)

### Tooling

- The demo site now shows Bun conversion. (3.1.0) — [release notes](https://github.com/bgub/npm-to-yarn/releases/tag/v3.1.0)
- The official TypeScript configuration package replaces the external @tsconfig/docusaurus package for TypeScript users. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)
- Runs a best-effort check that lists files with compilation errors under MDX v3. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)

### Fixes and other changes

- The warning admonition is officially supported and now has the correct color and icon; it renders yellow instead of the historical red. (3.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v3)

## npm-to-yarn 2

### Breaking changes

- Build artifacts now go in `website/build` rather than `website/build/<PROJECT_NAME>`, so deployment configuration must read from the updated directory. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Nested sidebar categories are supported; migrate the old `subcategory` type to `category` and use `items` in place of `ids`. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- GitHub Pages no longer generates the `CNAME` file; create it at `/static/CNAME` to use a custom domain. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- The field is available as `docsPluginOptions.sidebarCollapsible`, and sidebar collapsing is enabled by default. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- CLI commands are now invoked as `docusaurus <command>` instead of using `docusaurus-command` command names. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Use the scoped package name @docusaurus/core in place of docusaurus for Docusaurus 2. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Add this preset dependency to provide the default doc site functionalities and bundle essential plugins. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- The Docusaurus 2 site structure uses docusaurus.config.js in place of the Docusaurus 1 siteConfig.js. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2), [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Pass `editUrl` as a docs option to the classic preset, and point it to the Docusaurus project rather than the docs directory. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Pages must apply the theme layout around each page, with metadata passed as props. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Markdown syntax now uses MDX; tags must be valid JSX, including explicitly closed tags such as `<img/>` and `<br/>`. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual), [upgrade guide](https://docusaurus.io/docs/migration/v2/translated-sites)
- Docusaurus 2 generates a single-page application and loads React in the browser, unlike Docusaurus 1. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2)
- Move Docusaurus 1 `pages/en` files to `src/pages`. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- MDX style attributes must use JSX style objects, such as `style={{background: 'black'}}`, rather than string values. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/versioned-sites)
- Use the <Translate> component with id and description props instead of the v1 <translate> component. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/translated-sites)
- Use this hook to get the `siteConfig` object in pages instead of receiving it as props. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Versioned sidebar references use `version-${version}/${id}` rather than `version-${version}-${original_id}`. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/versioned-sites)

### Deprecations

- Use the `authors` field to provide author profile images instead of the deprecated `authorFBID` and `authorTwitter` fields. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- This field is deprecated; pass the page count as the `postsPerPage` blog option in the classic preset. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- The `cname` field is deprecated; create a `CNAME` file in the `static` folder for a custom domain. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- The `colors` configuration field is deprecated; customize Infima CSS variables in a CSS file and import it through the classic preset. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)

### New APIs and options

- Add --mdx to convert Markdown to MDX automatically during migration; the migration is still a work in progress. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/automated)
- Add --page to migrate pages automatically; the migration is still a work in progress. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/automated)
- Code translations are added to i18n/[locale]/code.json in Chrome i18n JSON format. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/translated-sites)
- Configure the classic preset in `docusaurus.config.js` to bundle essential plugins such as blog, docs, and pages. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Docs can declare `slug: installation.html` in front matter to keep the `.html` extension as the canonical URL. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Configure theme-managed site metadata, assets, navbar, footer, and search settings through `themeConfig`. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Localized content is generally found under website/i18n/[locale], with each plugin managing translations in its own i18n subfolder. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/translated-sites)

### Behavior and default changes

- The blog RSS feed is now served at `/blog/rss.xml` instead of `/blog/feed.xml`; redirects may preserve existing subscriptions. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Clean URLs are now used by default; `/installation` is canonical rather than `/installation.html`. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)
- Migration does not change the /docs folder location, and Docusaurus 2 lets you place it anywhere. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2)
- Each documentation version is an independent snapshot, so populate missing versioned documents and sidebars instead of relying on fallback functionality. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/versioned-sites)
- Versioned document front matter keeps the original id instead of prefixing it with the version; the version is applied internally. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/versioned-sites)
- Docusaurus 2 can be used to build websites beyond documentation sites, including blogs and product landing pages. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2)

### Tooling

- A migration CLI handles many parts of moving an existing Docusaurus 1 site to Docusaurus 2; remaining steps require manual migration. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2), [upgrade guide](https://docusaurus.io/docs/migration/v2/automated)
- Use `yarn deploy` for GitHub Pages instead of the `yarn publish-gh-pages` script. (2.0.0) — [upgrade guide](https://docusaurus.io/docs/migration/v2/manual)