Skip to content

Commit 56178bb

Browse files
ijlee2ijlee2
authored
Added Overview and Quickstart (#254)
* feature: Added Overview and Quickstart * chore: Upstreamed changes * chore: Added changesets
1 parent 11e7033 commit 56178bb

10 files changed

Lines changed: 238 additions & 4 deletions

File tree

‎.changeset/mighty-kings-reply.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"docs-app-for-codemod-utils": minor
3+
---
4+
5+
Added Overview and Quickstart

‎.changeset/sparkly-badgers-tease.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@codemod-utils/cli": patch
3+
---
4+
5+
Updated README

‎README.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,25 @@
55
_Utilities for writing codemods_
66

77

8+
## What are codemods?
9+
10+
A codemod is a function that takes files as input and output. It reads the files of interest, makes some changes, then saves the result to your disk.
11+
12+
<div align="left">
13+
<img alt="" src="./docs/src/images/codemod.jpg" width="600" />
14+
</div>
15+
16+
One special case is the identity function. That is, not all codemods need to make a change. As a result, linters are a codemod. Tools that gather files, collect metrics, analyze package dependencies, or find vulnerabilities are also one.
17+
18+
In short, codemods are everywhere and you’ve likely used a few already.
19+
20+
821
## What is it?
922

1023
`@codemod-utils` provides a set of **tools and conventions** to help you write codemods. Use [`@codemod-utils/cli`](/packages/cli/README.md) to get started.
1124

1225
```sh
13-
npx @codemod-utils/cli <your-codemod-name>
26+
pnpx @codemod-utils/cli <your-codemod-name>
1427
```
1528

1629

‎docs/.vitepress/config.mts‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ export default defineConfig({
2020
return defaultCodeInline(tokens, idx, options, env, self);
2121
};
2222
},
23+
image: {
24+
lazyLoading: true,
25+
},
2326
lineNumbers: true,
2427
theme: {
2528
light: 'github-light-default',
@@ -33,7 +36,53 @@ export default defineConfig({
3336
'https://github.com/ijlee2/codemod-utils/edit/main/docs/src/:path',
3437
text: 'Edit this page on GitHub',
3538
},
36-
nav: [],
39+
nav: [
40+
{
41+
link: '/docs',
42+
text: 'Overview',
43+
},
44+
{
45+
items: [
46+
{
47+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/ast/javascript/CHANGELOG.md',
48+
text: '@codemod-utils/ast-javascript',
49+
},
50+
{
51+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/ast/template/CHANGELOG.md',
52+
text: '@codemod-utils/ast-template',
53+
},
54+
{
55+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/ast/template-tag/CHANGELOG.md',
56+
text: '@codemod-utils/ast-template-tag',
57+
},
58+
{
59+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/blueprints/CHANGELOG.md',
60+
text: '@codemod-utils/blueprints',
61+
},
62+
{
63+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/cli/CHANGELOG.md',
64+
text: '@codemod-utils/cli',
65+
},
66+
{
67+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/ember/CHANGELOG.md',
68+
text: '@codemod-utils/ember',
69+
},
70+
{
71+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/files/CHANGELOG.md',
72+
text: '@codemod-utils/files',
73+
},
74+
{
75+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/package-json/CHANGELOG.md',
76+
text: '@codemod-utils/package-json',
77+
},
78+
{
79+
link: 'https://github.com/ijlee2/codemod-utils/blob/main/packages/tests/CHANGELOG.md',
80+
text: '@codemod-utils/tests',
81+
},
82+
],
83+
text: 'Changelogs',
84+
},
85+
],
3786
outline: {
3887
level: [2, 3],
3988
},

‎docs/.vitepress/sidebar.mts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
11
import type { DefaultTheme } from 'vitepress/theme';
22

3-
export const sidebar: DefaultTheme.Sidebar = [];
3+
export const sidebar: DefaultTheme.Sidebar = [
4+
{
5+
collapsed: true,
6+
items: [
7+
{
8+
link: '/docs/quickstart',
9+
text: 'Quickstart',
10+
},
11+
],
12+
text: 'Getting Started',
13+
},
14+
];

‎docs/src/docs/index.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Overview
2+
3+
## What are codemods?
4+
5+
A codemod is a function that takes files as input and output. It reads the files of interest, makes some changes, then saves the result to your disk.
6+
7+
![](../images/codemod.jpg)
8+
9+
One special case is the identity function. That is, not all codemods need to make a change. As a result, linters are a codemod. Tools that gather files, collect metrics, analyze package dependencies, or find vulnerabilities are also one.
10+
11+
In short, codemods are everywhere and you’ve likely used a few already.
12+
13+
14+
## What is codemod-utils?
15+
16+
`@codemod-utils` provides a set of **tools and conventions** to help you write codemods. Use `@codemod-utils/cli` to get started.
17+
18+
```sh {:no-line-numbers}
19+
pnpx @codemod-utils/cli <your-codemod-name>
20+
```
21+
22+
23+
### Package overview
24+
25+
- [@codemod-utils/ast-javascript](https://github.com/ijlee2/codemod-utils/tree/main/packages/ast/javascript/README.md)
26+
- [@codemod-utils/ast-template](https://github.com/ijlee2/codemod-utils/tree/main/packages/ast/template/README.md)
27+
- [@codemod-utils/ast-template-tag](https://github.com/ijlee2/codemod-utils/tree/main/packages/ast/template-tag/README.md)
28+
- [@codemod-utils/blueprints](https://github.com/ijlee2/codemod-utils/tree/main/packages/blueprints/README.md)
29+
- [@codemod-utils/cli](https://github.com/ijlee2/codemod-utils/tree/main/packages/cli/README.md)
30+
- [@codemod-utils/ember](https://github.com/ijlee2/codemod-utils/tree/main/packages/ember/README.md)
31+
- [@codemod-utils/files](https://github.com/ijlee2/codemod-utils/tree/main/packages/files/README.md)
32+
- [@codemod-utils/package-json](https://github.com/ijlee2/codemod-utils/tree/main/packages/package-json/README.md)
33+
- [@codemod-utils/tests](https://github.com/ijlee2/codemod-utils/tree/main/packages/tests/README.md)
34+
35+
36+
## Made with @codemod-utils
37+
38+
1. [@ember-intl/lint](https://github.com/ember-intl/ember-intl/tree/main/packages/ember-intl-lint)
39+
1. [@ember-intl/vite](https://github.com/ember-intl/ember-intl/tree/main/packages/ember-intl-vite)
40+
1. [analyze-ember-project-dependencies](https://github.com/ijlee2/analyze-ember-project-dependencies)
41+
1. [blueprints-v2-addon](https://github.com/ijlee2/create-v2-addon-repo/tree/main/packages/blueprints-v2-addon)
42+
1. [codemod-generate-release-notes](https://github.com/Ajanth/codemod-generate-release-notes)
43+
1. [create-v2-addon-repo](https://github.com/ijlee2/create-v2-addon-repo/tree/main/packages/create-v2-addon-repo)
44+
1. [ember-codemod-add-component-signatures](https://github.com/ijlee2/ember-codemod-add-component-signatures)
45+
1. [ember-codemod-add-missing-tests](https://github.com/ijlee2/ember-codemod-add-missing-tests)
46+
1. [ember-codemod-add-template-tags](https://github.com/ijlee2/ember-codemod-add-template-tags)
47+
1. [ember-codemod-css-modules](https://github.com/simplepractice/ember-codemod-css-modules)
48+
1. [ember-codemod-ember-render-helpers-to-v1](https://github.com/buschtoens/ember-render-helpers/tree/main/packages/ember-codemod-ember-render-helpers-to-v1)
49+
1. [ember-codemod-pod-to-octane](https://github.com/ijlee2/ember-codemod-pod-to-octane)
50+
1. [ember-codemod-remove-ember-css-modules](https://github.com/ijlee2/embroider-css-modules/tree/main/packages/ember-codemod-remove-ember-css-modules)
51+
1. [ember-codemod-remove-global-styles](https://github.com/ijlee2/embroider-css-modules/tree/main/packages/ember-codemod-remove-global-styles)
52+
1. [ember-codemod-remove-inject-as-service](https://github.com/ijlee2/ember-codemod-remove-inject-as-service)
53+
1. [ember-codemod-rename-test-modules](https://github.com/ijlee2/ember-codemod-rename-test-modules)
54+
1. [ember-codemod-sort-invocations](https://github.com/ijlee2/ember-codemod-sort-invocations)
55+
1. [ember-codemod-v1-to-v2](https://github.com/ijlee2/ember-codemod-v1-to-v2)
56+
1. [prettier-plugin-ember-hbs-tag](https://github.com/ijlee2/prettier-plugin-ember-hbs-tag/)
57+
1. [type-css-modules](https://github.com/ijlee2/embroider-css-modules/tree/main/packages/type-css-modules)
58+
1. [update-workspace-root-version](https://github.com/ijlee2/update-workspace-root-version)

‎docs/src/docs/quickstart.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Quickstart
2+
3+
## 1. Run CLI {#1-run-cli}
4+
5+
Change the directory to a place where you like to keep projects. Run [`@codemod-utils/cli`](https://github.com/ijlee2/codemod-utils/blob/main/packages/cli/README.md) to scaffold your codemod.
6+
7+
```sh {:no-line-numbers}
8+
pnpx @codemod-utils/cli <your-codemod-name> [options]
9+
```
10+
11+
This will create a folder named `your-codemod-name`.
12+
13+
14+
### Add more utilities {#1-run-cli-add-more-utilities}
15+
16+
By default, `@codemod-utils/cli` only installs the core packages: [`@codemod-utils/files`](https://github.com/ijlee2/codemod-utils/blob/main/packages/files/README.md) and [`@codemod-utils/tests`](https://github.com/ijlee2/codemod-utils/blob/main/packages/tests/README.md). Every codemod will need them.
17+
18+
If you need more, pass `--addon` and list the package names.
19+
20+
```sh {:no-line-numbers}
21+
pnpx @codemod-utils/cli --addon blueprints package-json
22+
```
23+
24+
The options for `--addon` are:
25+
26+
- [`ast-javascript`](https://github.com/ijlee2/codemod-utils/tree/main/packages/ast/javascript/README.md)
27+
- [`ast-template`](https://github.com/ijlee2/codemod-utils/tree/main/packages/ast/template/README.md)
28+
- [`ast-template-tag`](https://github.com/ijlee2/codemod-utils/tree/main/packages/ast/template-tag/README.md)
29+
- [`blueprints`](https://github.com/ijlee2/codemod-utils/tree/main/packages/blueprints/README.md)
30+
- [`ember`](https://github.com/ijlee2/codemod-utils/tree/main/packages/ember/README.md)
31+
- [`package-json`](https://github.com/ijlee2/codemod-utils/tree/main/packages/package-json/README.md)
32+
33+
34+
### JavaScript only? {#1-run-cli-javascript-only}
35+
36+
By default, `@codemod-utils/cli` creates a TypeScript project to help you maintain and extend the codemod.
37+
38+
To create a JavaScript project, set `--typescript` to `false`.
39+
40+
```sh {:no-line-numbers}
41+
pnpx @codemod-utils/cli --typescript false
42+
```
43+
44+
45+
46+
## 2. Make the initial commit {#2-make-the-initial-commit}
47+
48+
Change to the codemod directory, then run these scripts in sequence:
49+
50+
```sh {:no-line-numbers}
51+
# Install dependencies
52+
pnpm install
53+
```
54+
55+
```sh {:no-line-numbers}
56+
# Commit changes
57+
git init
58+
git add .
59+
git commit -m "Initial commit"
60+
```
61+
62+
```sh {:no-line-numbers}
63+
# Push changes (to a new repo)
64+
git remote add origin git@github.com:<your-github-handle>/<your-repo-name>.git
65+
git branch -M main
66+
git push -u origin main
67+
```
68+
69+
70+
## 3. Start coding
71+
72+
> [!TIP]
73+
>
74+
> As you write code, you will want to lint and test files.
75+
>
76+
> ```sh {:no-line-numbers}
77+
> # Lint files
78+
> pnpm lint
79+
> pnpm lint:fix
80+
>
81+
> # Test files
82+
> pnpm test
83+
> ```
84+
>
85+
> Try running these scripts now. They should pass out of the box.
86+
87+
Not sure how to start? If this is your first time writing a codemod, we recommend going through the [main tutorial](https://github.com/ijlee2/codemod-utils/blob/main/tutorials/main-tutorial/00-introduction.md). See existing codemods in [Made with `@codemod-utils`](./#made-with-codemod-utils).

‎docs/src/images/codemod.jpg‎

51.2 KB
Loading

‎docs/src/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,8 @@ hero:
99
- link: /docs
1010
text: Docs
1111
theme: brand
12+
13+
- link: /docs/quickstart
14+
text: Quickstart
15+
theme: alt
1216
---

‎packages/cli/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,9 @@ npx @codemod-utils/cli --root <path/to/your/project>
8585

8686
<summary>Optional: Create a JavaScript project</summary>
8787

88-
By default, `@codemod-utils/cli` creates a TypeScript project to help you maintain and extend the codemod. To create a JavaScript project, set `--typescript` to `false`.
88+
By default, `@codemod-utils/cli` creates a TypeScript project to help you maintain and extend the codemod.
89+
90+
To create a JavaScript project, set `--typescript` to `false`.
8991

9092
```sh
9193
npx @codemod-utils/cli --typescript false

0 commit comments

Comments
 (0)