npm / npm-to-yarn

npm-to-yarn

What changed in npm-to-yarn 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-19.

38 breaking6 deprecations11 new APIs and options11 behavior and defaults5 tooling1 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli on npm

npm-to-yarn 336 changes

Breaking changes 21

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

Deprecations 2

The caution admonition is deprecated; refactor it to :::warning or :::danger.
3.0.0upgrade guide
This compatibility option allows HTML comments in MDX; the notes recommend replacing them with MDX comments before turning it off.
3.0.0upgrade guide

New APIs and options 4

Deno support was added to npm-to-yarn.
3.1.0release notes
Docusaurus v3 supports ES Module configuration files, allowing Remark plugins to be imported directly.
3.0.0upgrade guide
Docusaurus v3 supports ESM and TypeScript config files.
3.0.0upgrade guide
This compatibility option allows the Docusaurus v2 admonition title syntax; the new directive label syntax uses square brackets.
3.0.0upgrade guide

Behavior and default changes 5

The default blog truncate marker now accepts both the HTML comment marker and the MDX comment marker.
3.0.0upgrade guide
Docusaurus switches config loading from import-fresh to jiti; existing config files should keep working, but subtle behavior changes could occur.
3.0.0upgrade guide
Use the .mdx extension for Markdown files containing JSX, imports, or exports; future versions will parse .md files as CommonMark.
3.0.0upgrade guide
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.0upgrade guide
The automatic JSX runtime means JSX files no longer need to import React when they do not use a React API.
3.0.0upgrade guide

Tooling 3

The demo site now shows Bun conversion.
3.1.0release notes
The official TypeScript configuration package replaces the external @tsconfig/docusaurus package for TypeScript users.
3.0.0upgrade guide
Runs a best-effort check that lists files with compilation errors under MDX v3.
3.0.0upgrade guide

Fixes and other changes 1

The warning admonition is officially supported and now has the correct color and icon; it renders yellow instead of the historical red.
3.0.0upgrade guide

npm-to-yarn 236 changes

Breaking changes 17

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

Deprecations 4

Use the authors field to provide author profile images instead of the deprecated authorFBID and authorTwitter fields.
2.0.0upgrade guide
This field is deprecated; pass the page count as the postsPerPage blog option in the classic preset.
2.0.0upgrade guide
The cname field is deprecated; create a CNAME file in the static folder for a custom domain.
2.0.0upgrade guide
The colors configuration field is deprecated; customize Infima CSS variables in a CSS file and import it through the classic preset.
2.0.0upgrade guide

New APIs and options 7

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

Behavior and default changes 6

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

Tooling 2

A migration CLI handles many parts of moving an existing Docusaurus 1 site to Docusaurus 2; remaining steps require manual migration.
2.0.0upgrade guide upgrade guide
Use yarn deploy for GitHub Pages instead of the yarn publish-gh-pages script.
2.0.0upgrade guide