Add codemod documentation (#16067)
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
This commit is contained in:
Tim Neutkens
GitHub
parent
b8662d5766
commit
16345f631e
3 changed files with 158 additions and 167 deletions
149
docs/advanced-features/codemods.md
Normal file
149
docs/advanced-features/codemods.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
---
|
||||
description: Use codemods to update your codebase when upgrading Next.js to the latest version
|
||||
---
|
||||
|
||||
# Next.js Codemods
|
||||
|
||||
Next.js provides Codemod transformations to help upgrade your Next.js codebase when a feature is deprecated.
|
||||
|
||||
Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually go through every file.
|
||||
|
||||
## Usage
|
||||
|
||||
`npx @next/codemod <transform> <path>`
|
||||
|
||||
- `transform` - name of transform, see available transforms below.
|
||||
- `path` - files or directory to transform
|
||||
- `--dry` Do a dry-run, no code will be edited
|
||||
- `--print` Prints the changed output for comparison
|
||||
|
||||
## Next.js 9
|
||||
|
||||
### `name-default-component`
|
||||
|
||||
Transforms anonymous components into named components to make sure they work with [Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh).
|
||||
|
||||
For example
|
||||
|
||||
```jsx
|
||||
// my-component.js
|
||||
export default function () {
|
||||
return <div>Hello World</div>
|
||||
}
|
||||
```
|
||||
|
||||
Transforms into:
|
||||
|
||||
```jsx
|
||||
// my-component.js
|
||||
export default function MyComponent() {
|
||||
return <div>Hello World</div>
|
||||
}
|
||||
```
|
||||
|
||||
The component will have a camel cased name based on the name of the file, and it also works with arrow functions.
|
||||
|
||||
#### Usage
|
||||
|
||||
Go to your project
|
||||
|
||||
```
|
||||
cd path-to-your-project/
|
||||
```
|
||||
|
||||
Run the codemod:
|
||||
|
||||
```
|
||||
npx @next/codemod name-default-component
|
||||
```
|
||||
|
||||
### `withamp-to-config`
|
||||
|
||||
Transforms the `withAmp` HOC into Next.js 9 page configuration.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
// Before
|
||||
import { withAmp } from 'next/amp'
|
||||
|
||||
function Home() {
|
||||
return <h1>My AMP Page</h1>
|
||||
}
|
||||
|
||||
export default withAmp(Home)
|
||||
```
|
||||
|
||||
```js
|
||||
// After
|
||||
export default function Home() {
|
||||
return <h1>My AMP Page</h1>
|
||||
}
|
||||
|
||||
export const config = {
|
||||
amp: true,
|
||||
}
|
||||
```
|
||||
|
||||
#### Usage
|
||||
|
||||
Go to your project
|
||||
|
||||
```
|
||||
cd path-to-your-project/
|
||||
```
|
||||
|
||||
Run the codemod:
|
||||
|
||||
```
|
||||
npx @next/codemod withamp-to-config
|
||||
```
|
||||
|
||||
## Next.js 6
|
||||
|
||||
### `url-to-withrouter`
|
||||
|
||||
Transforms the deprecated automatically injected `url` property on top level pages to using `withRouter` and the `router` property it injects. Read more here: [err.sh/next.js/url-deprecated](https://err.sh/next.js/url-deprecated)
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
// From
|
||||
import React from 'react'
|
||||
export default class extends React.Component {
|
||||
render() {
|
||||
const { pathname } = this.props.url
|
||||
return <div>Current pathname: {pathname}</div>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```js
|
||||
// To
|
||||
import React from 'react'
|
||||
import { withRouter } from 'next/router'
|
||||
export default withRouter(
|
||||
class extends React.Component {
|
||||
render() {
|
||||
const { pathname } = this.props.router
|
||||
return <div>Current pathname: {pathname}</div>
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
This is just one case. All the cases that are transformed (and tested) can be found in the [`__testfixtures__` directory](./transforms/__testfixtures__/url-to-withrouter).
|
||||
|
||||
#### Usage
|
||||
|
||||
Go to your project
|
||||
|
||||
```
|
||||
cd path-to-your-project/
|
||||
```
|
||||
|
||||
Run the codemod:
|
||||
|
||||
```
|
||||
npx @next/codemod url-to-withrouter
|
||||
```
|
||||
|
|
@ -176,6 +176,10 @@
|
|||
{
|
||||
"title": "Debugging",
|
||||
"path": "/docs/advanced-features/debugging.md"
|
||||
},
|
||||
{
|
||||
"title": "Codemods",
|
||||
"path": "/docs/advanced-features/codemods.md"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
|
|
@ -1,171 +1,9 @@
|
|||
# Next.js Codemod
|
||||
# Next.js Codemods
|
||||
|
||||
This repository contains Codemod transformations to help upgrade Next.js codebases.
|
||||
Next.js provides Codemod transformations to help upgrade your Next.js codebase when a feature is deprecated.
|
||||
|
||||
## v9
|
||||
Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually go through every file.
|
||||
|
||||
### `name-default-component`
|
||||
## Documentation
|
||||
|
||||
Transforms anonymous components into named components to make sure they work with [Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh).
|
||||
|
||||
For example
|
||||
|
||||
```jsx
|
||||
// my-component.js
|
||||
export default function () {
|
||||
return <div>Hello World</div>
|
||||
}
|
||||
```
|
||||
|
||||
Transforms into:
|
||||
|
||||
```jsx
|
||||
// my-component.js
|
||||
export default function MyComponent() {
|
||||
return <div>Hello World</div>
|
||||
}
|
||||
```
|
||||
|
||||
The component will have a camel cased name based on the name of the file, and it also works with arrow functions.
|
||||
|
||||
#### Usage
|
||||
|
||||
Go to your project
|
||||
|
||||
```
|
||||
cd path-to-your-project/
|
||||
```
|
||||
|
||||
Download the codemod:
|
||||
|
||||
```
|
||||
curl -L https://github.com/zeit/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/name-default-component.js
|
||||
```
|
||||
|
||||
Run the transformation:
|
||||
|
||||
```
|
||||
npx jscodeshift -t ./name-default-component.js components/**/*.js
|
||||
```
|
||||
|
||||
TypeScript files can use this codemod too:
|
||||
|
||||
```
|
||||
npx jscodeshift -t ./name-default-component.js --parser=tsx components/**/*.tsx
|
||||
```
|
||||
|
||||
If you have components in multiple folders, change the path to `**/*.js` and add `--ignore-pattern="**/node_modules/**"`.
|
||||
|
||||
After the transformation is done the `name-default-component.js` file in the root of your project can be removed.
|
||||
|
||||
### `withamp-to-config`
|
||||
|
||||
Transforms the `withAmp` HOC into Next.js 9 page configuration.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
// Before
|
||||
import { withAmp } from 'next/amp'
|
||||
|
||||
function Home() {
|
||||
return <h1>My AMP Page</h1>
|
||||
}
|
||||
|
||||
export default withAmp(Home)
|
||||
```
|
||||
|
||||
```js
|
||||
// After
|
||||
export default function Home() {
|
||||
return <h1>My AMP Page</h1>
|
||||
}
|
||||
|
||||
export const config = {
|
||||
amp: true,
|
||||
}
|
||||
```
|
||||
|
||||
#### Usage
|
||||
|
||||
Go to your project
|
||||
|
||||
```
|
||||
cd path-to-your-project/
|
||||
```
|
||||
|
||||
Download the codemod:
|
||||
|
||||
```
|
||||
curl -L https://github.com/zeit/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/withamp-to-config.js
|
||||
```
|
||||
|
||||
Run the transformation:
|
||||
|
||||
```
|
||||
npx jscodeshift -t ./withamp-to-config.js pages/**/*.js
|
||||
```
|
||||
|
||||
After the transformation is done the `withamp-to-config.js` file in the root of your project can be removed.
|
||||
|
||||
## v6
|
||||
|
||||
### `url-to-withrouter`
|
||||
|
||||
Tranforms the deprecated automatically injected `url` property on top level pages to using `withRouter` and the `router` property it injects. Read more here: [err.sh/next.js/url-deprecated](https://err.sh/next.js/url-deprecated)
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
// From
|
||||
import React from 'react'
|
||||
export default class extends React.Component {
|
||||
render() {
|
||||
const { pathname } = this.props.url
|
||||
return <div>Current pathname: {pathname}</div>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```js
|
||||
// To
|
||||
import React from 'react'
|
||||
import { withRouter } from 'next/router'
|
||||
export default withRouter(
|
||||
class extends React.Component {
|
||||
render() {
|
||||
const { pathname } = this.props.router
|
||||
return <div>Current pathname: {pathname}</div>
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
This is just one case. All the cases that are transformed (and tested) can be found in the [`__testfixtures__` directory](./transforms/__testfixtures__/url-to-withrouter).
|
||||
|
||||
#### Usage
|
||||
|
||||
Go to your project
|
||||
|
||||
```
|
||||
cd path-to-your-project/
|
||||
```
|
||||
|
||||
Download the codemod:
|
||||
|
||||
```
|
||||
curl -L https://github.com/zeit/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/url-to-withrouter.js
|
||||
```
|
||||
|
||||
Run the transformation:
|
||||
|
||||
```
|
||||
npx jscodeshift -t ./url-to-withrouter.js pages/**/*.js
|
||||
```
|
||||
|
||||
After the transformation is done the `url-to-withrouter.js` file in the root of your project can be removed.
|
||||
|
||||
## Authors
|
||||
|
||||
- Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co)
|
||||
- Joe Haddad ([@timer150](https://twitter.com/timer150)) - [ZEIT](https://zeit.co)
|
||||
Visit [nextjs.org/docs/advanced-features/codemods](https://nextjs.org/docs/advanced-features/codemods) to view the documentation for this package.
|
||||
|
|
|
|||
Loading…
Reference in a new issue