You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Community Folder is the public directory of codemods hosted and published directly from this repository, [visible here](https://github.com/CodeshiftCommunity/CodeshiftCommunity/tree/main/community).
17
+
This directory can be compared to and treated the same as the Typescript type definition regisistry: [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped).
14
18
15
-
For example:
19
+
_Please see the [Contribution guide](contribution) for more information._
16
20
17
-
`yarn init:codemods react-cool-library 10.0.0`
21
+
Use this method if you want:
18
22
19
-
And for scoped packages:
23
+
- Your codemods to be open source
24
+
- Build tooling, dependency management and project setup to be handled for you
25
+
- The community to help maintain and contribute to your codemods
26
+
- Documentation to be automatically generated and available on the [Regisistry page](atlaskit__avatar)
It will create a package within the `/community` subdirectory, this is for you to implement your codemod.
30
+
- Your codemods target a closed source package/repository
31
+
- Your codemods are generic in that they do not target any particular package
32
+
- Your codemods should be close sourced or contain sensitive data
24
33
25
-
## File structure
34
+
## 2. Add codeshift to an existing package
26
35
27
-
The file structure of your codemod will look like this:
36
+
For existing npm packages (like react), you have the option to expose codemods directly from the package by simply creating a `codeshift.config.js` at either the root, `/src` or `/codemods` directory.
37
+
Given that the config and codemod files are then published and available on NPM, `codeshift-cli` will be able to find and run codemods using the `--package` flag.
28
38
29
-
```
30
-
community/[package-name]/[version]
31
-
/codeshift.config.js // main entrypoint containing configuration and references to your transforms
32
-
/transform.ts // main logic (should contain a transformer)
33
-
/transform.spec.ts // main tests
34
-
/motions // different operations that make up the codemod
35
-
/[motion-name].ts // motion
36
-
/[motion-name].spec.ts // motion tests
37
-
```
39
+
Use this method if you want:
38
40
39
-
**Example:**
41
+
- To get up and running with an existing package with very little overhead
42
+
- Control over where and how your codeshift package is hosted
43
+
- Control over tooling, dependencies and techstack
44
+
- To remove a previously created jscodeshift cli wrapper and instead use the generic codeshift-cli
40
45
41
-
```
42
-
community/react-cool-library/18.0.0
43
-
/codeshift.config.js
44
-
/transform.ts
45
-
/transform.spec.ts
46
-
/motions
47
-
/remove-ref-usage.ts
48
-
/remove-ref-usage.spec.ts
49
-
```
46
+
Do not use this method if:
50
47
51
-
## Configuration
48
+
- Your package is close sourced
49
+
- You want docs to be automatically generated and available on the [Regisistry page](atlaskit__avatar)
52
50
53
-
Each codemod package should be coupled with a `codeshift.config.js` file.
54
-
The config file is the entry-point of your codemod and is responsible for holding all of the relevant
55
-
metadata about it, as well as references to the transformer functions themselves.
51
+
## 3. Create a stand-alone codeshift package
56
52
57
-
They typically look like this:
53
+
Codeshift packages can be created as a stand-alone package.
58
54
59
-
```js
60
-
exportdefault {
61
-
maintainers: ['danieldelcore'],
62
-
transforms: {
63
-
'18.0.0':require.resolve('./18.0.0/transform'),
64
-
'19.0.0':require.resolve('./19.0.0/transform'),
65
-
},
66
-
};
67
-
```
55
+
_Please see the [External Packages guide](external-packages) for more information._
68
56
69
-
-`maintainers`: Github usernames of the people that maintain that codemod, they will be notified on PRs etc.
70
-
-`transforms`: A key value pair of transforms organized by semver-compatible versions
57
+
Use this method if you want:
71
58
72
-
## Versioning
59
+
- Control over where and how your codeshift package is hosted
60
+
- Control over tooling, dependencies and techstack
61
+
- The option to create completely generic codemods that don't target specific packages
73
62
74
-
You might wonder why we require that codemods are named by a semver version like `react-cool-library/18.0.0`.
75
-
We believe that codemods should aim to target specific package and versions of that package.
63
+
Do not use this method if:
76
64
77
-
This is done to:
78
-
79
-
- Make it obvious what the intended purpose and scope of a codemod is
80
-
- Make it obvious which package is being upgraded
81
-
- Make it easy to play codemods in sequence to allow migration from v4 -> v5 -> v6
82
-
83
-
But importantly, in terms of authoring, this also allows us to **retrospectivally patch published codemods**.
84
-
Patched codemods will then be automatically published when merged to the repo, ensuring that consumers are always running the latest version.
85
-
86
-
## Transformers
87
-
88
-
Transformers are the main entrypoint to your codemod, they are responsible for accepting a raw file, applying the appropriate modifications to it and finally outputting the resulting AST to the original file.
returnsource.toSource(options.printOptions); // Writes modified AST to file
107
-
}
108
-
```
109
-
110
-
## Motions
111
-
112
-
A motion (aka migration) is what we call specific actions performed within a codemod. For example, `updateBorderWidth` or `removeDeprecatedProps`.
113
-
They can be simply thought of a functions that are responsible for a single action within a codemod. It is not required but they are highly recommended as
114
-
a helpful design pattern to isolate more complicated parts of your codemod into discrete pieces.
115
-
116
-
**Example:**
117
-
118
-
```ts
119
-
function removeDeprecatedProps(j, source) {
120
-
// Some logic here
121
-
}
122
-
```
123
-
124
-
Motions can then be applied from the main transform, just like any other function.
It's very likely that consumers will run into all sorts of edge-cases when running your transform.
164
-
That's why it's important to start by writing some tests to assert it's behavior. Luckily, both [CodeshiftCommunity](./test-utils) & [jscodeshift](https://github.com/facebook/jscodeshift#unit-testing) provides testing utilities to help.
165
-
166
-
When creating a codemod, it's best to always try to write your tests first (TDD style).
167
-
Think about the start and end state and how you might be able to achieve that. Also, make sure to consider as many edge-cases as you possibly can.
168
-
169
-
For more information, please see the [testing docs](testing).
All codeshift packages must be coupled with a `codeshift.config.js` file.
8
+
This file acts as the entry-point of your codeshift package and is responsible for holding all of the relevant metadata, as well as paths to the transformer functions themselves.
These files should always be in the root directory of your package to ensure `codeshift-cli` has access to it.
28
+
It does so by pulling your package directly from NPM and searching the root directory, which by extension means you should always ensure that the config and the transform files are not ignored by npm.
29
+
30
+
Config files can be written in either JavaScript or TypeScript, depending on your preference.
31
+
32
+
To check if your config is valid, you can use [the validate command](cli#validate).
33
+
34
+
## Properties
35
+
36
+
### `maintainers`
37
+
38
+
Github usernames of the people that maintain the package, they will be notified on PRs etc.
39
+
40
+
### `description`
41
+
42
+
A description of the package and its intended usage
43
+
44
+
### `transforms`
45
+
46
+
A key value pair of transforms organized by semver-compatible versions.
47
+
48
+
For more information see [Guiding Principles](guiding-principles#codemods-should-target-a-version-of-package).
49
+
50
+
### `presets`
51
+
52
+
A key value pair of presets organized by kebab case identifiers.
53
+
54
+
Presets are intended to act as a way to share generic codemods, that are either completely generic or compliment the target package but are not version specific.
55
+
56
+
Some examples include: `sort-imports`, `format-props`, `remove-comments`, etc.
57
+
58
+
### `targets`
59
+
60
+
**Experimental**
61
+
62
+
Targets list the packages that the codemod package targets.
63
+
This is useful for codeshift packages that have codemods targeting multiple related packages at the same time, such as packages from a monorepo.
Copy file name to clipboardExpand all lines: website/docs/consuming.mdx
+15-13Lines changed: 15 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,47 +12,49 @@ For usage please refer to the [@codeshift/cli API reference](/docs/cli).
12
12
13
13
## How to run Community codemods
14
14
15
-
To apply a codemod from the [Community folder](https://github.com/CodeshiftCommunity/CodeshiftCommunity/tree/main/community)install and use the `@codemod/cli` via `npx`.
15
+
To run a codeshift package, install and use the `@codeshift/cli`.
16
16
17
-
For example, say we want to run transforms for `@mylib/button` and migrate from version 13 to the latest version 14.
17
+
-**npm:**`npm install -g @codeshift/cli` or
18
+
-**yarn:**`yarn global add @codeshift/cli`
18
19
19
-
In this case we could try:
20
+
For example, say we want to run transforms for `@mylib/button` and migrate from version 13 to the latest version 14, we could run the following:
2.`@codemod/cli` will then attempt to locate a codemod for the `@mylib/button` package matching version `14.0.0`
29
-
3. Download the matching transform from NPM
30
-
4. Run the transform against the path `project/path/to/src`
28
+
1.`@codeshift/cli` will then attempt to download a codeshift package for the `@mylib/button` package matching version `14.0.0`
29
+
1. Download the package from NPM
30
+
1. Locate the `codeshift.config.js`
31
+
1. Attempt to find a `transform` for `14.0.0`
32
+
1. Run the transform against the path `project/path/to/src`
31
33
32
34
## Run codemods in sequence
33
35
34
36
It's also possible to run a series of codemods, one after the other, to migrate your usage of `@mylib/button` across multiple major versions, from say v14, v15 and finally v16. Assuming codemods for those versions exist.
35
37
36
-
This is done my providing the `--sequence` (or `-s`) flag to `@codemod/cli`.
38
+
This is done my providing the `--sequence` (or `-s`) flag to `@codeshift/cli`.
By default `@codemod/cli` will use `babel` as the default parser and only transform files with a `.js` extensions.
57
+
By default `@codeshift/cli` will use `babel` as the default parser and only transform files with a `.js` extensions.
56
58
57
59
If your repo depends on flow or typescript, it's important to remember to specify `ts`, `tsx` or `flow` as the `--parser` and or `jsx, ts, tsx` as `--extensions` to make sure jscodeshift can interpret the files properly.
0 commit comments