import {Note} from '../_component/note.server.js'
export const navExclude = true
export const info = {
  author: [
    {name: 'John Otander', github: 'johno', twitter: '4lpine'}
  ],
  published: new Date('2019-04-04'),
  modified: new Date('2021-11-01')
}

<Note type="legacy">
  **Note**: This is an old migration guide.
  See [§ Migrating from v1 to v2](/migrating/v2/).
  The below is kept as is for historical purposes.
</Note>

# Migrating from v0 to v1

Unfortunately, we’ve had to introduce a few breaking changes, so we’ve written a
migration guide.
In order to ensure as seamless of an upgrade as possible we plan on supporting
v0 for the next 12 months so there’s not a huge rush to update (though we’d
love for you to ASAP) 📆.

## ⚠️ Breaking changes

*   [🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `mdx` pragma](#pragma) 🚨
*   [MDXProvider now merges component contexts when nested](#mdxprovider)
*   [React support now requires `>= 16.8` in `@mdx-js/react`](#react)

## Pragma

For v1 you need to remove `@mdx-js/tag` and replace it with `@mdx-js/react`:

```sh
yarn remove @mdx-js/tag
yarn add @mdx-js/react
```

### What’s different?

The MDXTag implementation has been removed with a custom pragma implementation
inspired by
[Emotion](https://emotion.sh/docs/css-prop#jsx-pragma).
This ensures that transpiled JSX is more readable and that JSX blocks use the
same component as its markdown counterpart.
It also allows MDXProvider to provide global component scope like a `Youtube`
or `Twitter` component.

The pragma implementation will also cause JSX HTML elements to be rendered with
the component mapping passed to MDXProvider.
So, the following will result in two identically rendered `h1`s:

```js
# Hello, world!

<h1>Hello, world!</h1>
```

[See the blog post for further reading](/blog/custom-pragma/)

## MDXProvider

This shouldn’t affect most usecases, however if you’re nesting component
contexts and rely on them not being merged you will have to use the functional
form which allows you to customize the merge.
By ignoring outer context components and returning a new component mapping, you
will restore the old behavior:

```js
<MDXProvider components={components}>
  <MDXProvider components={outerComponents => newComponents}>
    {children}
  </MDXProvider>
</MDXProvider>
```

## React

Before upgrading to `@mdx-js/mdx@1`, update your website/application to
`react@16.8 react-dom@16.8` and ensure it works as expected.
Then upgrade to v1.
