diff --git a/README.md b/README.md index 2ea2ad73..debc12b5 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,8 @@ npx @codemod-utils/cli --name ## Tutorials -- [Main tutorial: `ember-codemod-rename-test-modules`](./tutorials/ember-codemod-rename-test-modules/00-introduction.md) -- Tutorial for blueprints: `blueprint-for-v2-addon` (coming soon) +- [Main tutorial](./tutorials/ember-codemod-rename-test-modules/00-introduction.md) +- [Tutorial for blueprints](./tutorials/blueprint-for-v2-addon/00-introduction.md) ## Codemods written with @codemod-utils diff --git a/packages/ast/javascript/README.md b/packages/ast/javascript/README.md index 2c97855d..3244ae98 100644 --- a/packages/ast/javascript/README.md +++ b/packages/ast/javascript/README.md @@ -133,7 +133,7 @@ Most importantly, write tests to document the inputs and outputs of your codemod ## Contributing -See the [Contributing](../../CONTRIBUTING.md) guide for details. +See the [Contributing](../../../CONTRIBUTING.md) guide for details. ## License diff --git a/packages/ast/template/README.md b/packages/ast/template/README.md index 66b76da2..28e3a694 100644 --- a/packages/ast/template/README.md +++ b/packages/ast/template/README.md @@ -128,7 +128,7 @@ Most importantly, write tests to document the inputs and outputs of your codemod ## Contributing -See the [Contributing](../../CONTRIBUTING.md) guide for details. +See the [Contributing](../../../CONTRIBUTING.md) guide for details. ## License diff --git a/tutorials/blueprint-for-v2-addon/00-introduction.md b/tutorials/blueprint-for-v2-addon/00-introduction.md new file mode 100644 index 00000000..dcbc440c --- /dev/null +++ b/tutorials/blueprint-for-v2-addon/00-introduction.md @@ -0,0 +1,32 @@ +# Introduction + +> [!IMPORTANT] +> Please complete the [main tutorial](../ember-codemod-rename-test-modules/00-introduction.md) first. + +> [!NOTE] +> This tutorial covers **blueprints**, files that you can use like a "stamp" to create or update certain files in a project. You will also learn how to transform a user's CLI options in the `create-options` step. + +We will partially implement `blueprint-for-v2-addon`, a codemod that helps [CLARK](https://www.clark.io/) write [v2 addons](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format/). It creates an addon and a test app similarly to [`@embroider/addon-blueprint`](https://github.com/embroider-build/addon-blueprint), with some exceptions: + +- We can easily standardize deviations, such as custom files, lint configurations, and dependencies. +- Upstream errors (from `ember-cli` and `@embroider/addon-blueprint`) have a little effect. +- Generating files is simpler and faster. + +```sh +# Average time for @embroider/addon-blueprint +❯ time EMBER_CLI_PNPM=true ember addon "@clark-ui/button" --addon-location "ui/button" --blueprint "@embroider/addon-blueprint" --pnpm --skip-npm --typescript + +1.87s user 1.18s system 126% cpu 2.409 total +``` + +```sh +# Average time for blueprint-for-v2-addon +❯ time pnpm generate-addon --addon-name "@clark-ui/button" --addon-location "ui/button" + +1.86s user 0.23s system 133% cpu 1.565 total +``` + + +## Table of contents + +1. [Create a project](./01-create-a-project.md) diff --git a/tutorials/blueprint-for-v2-addon/01-create-a-project.md b/tutorials/blueprint-for-v2-addon/01-create-a-project.md new file mode 100644 index 00000000..ea9da4be --- /dev/null +++ b/tutorials/blueprint-for-v2-addon/01-create-a-project.md @@ -0,0 +1,64 @@ +# Create a project + +Recall that `@codemod-utils/cli` automatically adds `@codemod-utils/files` and `@codemod-utils/tests`. We will instruct the CLI to also add [`@codemod-utils/blueprints`](../../packages/blueprints/README.md), so that we can write blueprints to create files. + +Goals: + +- Use `@codemod-utils/cli` to create a project +- Familiarize with the folder structure + + +## Use the CLI + +Change the directory to a place where you like to keep projects. Then, run these commands: + +```sh +# Create project +npx @codemod-utils/cli --name blueprint-for-v2-addon --addon blueprints + +# Install dependencies +cd blueprint-for-v2-addon +pnpm install +``` + + +## Folder structure + +Let's take a look at how `blueprint-for-v2-addon` is structured as a tree. For simplicity, the tree only shows what's important for the tutorial. + +```sh +blueprint-for-v2-addon +└── src + ├── blueprints + ├── steps + ├── types + ├── utils + │ └── blueprints.ts + └── index.ts +``` + +We see that the CLI has scaffolded `src/blueprints` and `src/utils`. + + +### blueprints + +The `blueprints` directory contains files that we want end-developers (our users) to have. + +For the most part, the folder structure and file names will match what end-developers will see in their project. At runtime, it is possible to change the file path (e.g. rename `__gitignore__` to `.gitignore`) or exclude the file (e.g. `tsconfig.json` for JavaScript projects). + + +### utils/blueprints.ts + +The file exports a variable called `blueprintsRoot`. When end-developers install our codemod, our blueprint files are saved _somewhere_ on their machine. `blueprintsRoot` represents this runtime location. + +In short, we can write and test our codemod as usual, without worrying about where the blueprint files will end up. + + +
+
+ Next: +
+
+ Previous: Introduction +
+
diff --git a/tutorials/ember-codemod-rename-test-modules/02-understand-the-folder-structure.md b/tutorials/ember-codemod-rename-test-modules/02-understand-the-folder-structure.md index 011518b2..02661722 100644 --- a/tutorials/ember-codemod-rename-test-modules/02-understand-the-folder-structure.md +++ b/tutorials/ember-codemod-rename-test-modules/02-understand-the-folder-structure.md @@ -12,7 +12,7 @@ Goals: ## Folder structure -Let's take a look how `ember-codemod-rename-test-modules` is structured as a tree. For simplicity, the tree only shows what's important for the tutorial. +Let's take a look at how `ember-codemod-rename-test-modules` is structured as a tree. For simplicity, the tree only shows what's important for the tutorial. ```sh ember-codemod-rename-test-modules