docs(guides): first codemod guide (#1342)

* docs: add first codemod guide

* adding navigation

* remove nld as optional

apps/docs/guides/first-codemod.mdx

@@ -0,0 +1,202 @@
+---
+title: "Making Your First Codemod"
+---
+
+In this tutorial, you'll learn how to build, publish, and run your first codemod. During this process you will learn different concepts such as:
+
+- [Building codemod packages with Codemod Studio](#building-codemods-with-codemod-studio)
+- [Configuring codemod packages using `.codemodrc.json`](#configuring-codemod-packages)
+- [Publishing codemods to Codemod Registry](#publishing-the-codemod-package)
+- [Running codemods using Codemod CLI](#running-codemods)
+
+To keep this tutorial practical, you will learn these concepts by creating a codemod that addresses string refs deprecation in React 19. However, these concepts will apply to many codemods you will build for various use cases moving forward.
+
+## Building codemods with Codemod Studio
+
+To get started, we will head to [Codemod Studio](https://codemod.com/studio). Codemod Studio uses tuned Codemod AI to build codemods using before/after code examples. You can learn more about Codemod Studio [here](/codemod-studio).
+
+To start building the codemod:
+
+<Steps>
+    <Step title="Add before/after code examples">
+        We will use the [before/after code examples in the React 19 migration guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-string-refs).
+
+        In this case, the following transformation should happen:
+
+        ```jsx Before
+        <div ref='refName' />;
+        ```
+
+        Should be transformed into:
+
+        ```jsx After
+        <div ref={(ref) => (this.refs.refName = ref)} />;
+        ```
+
+        We will add these before/after code examples to the before and after code panes in Codemod Studio:
+
+        <video
+        autoPlay
+        loop
+        className="w-full aspect-video"
+        src="/images/guides/building-codemods/add-before-after.mp4"
+        ></video>
+
+        <Tip>
+            You can add multiple before/after code snippets to cover edge cases. Please refer to [Codemod Studio's tips and best practices](/codemod-studio#tips-and-tricks-for-writing-better-tests-and-codemods) while adding more test cases.
+        </Tip>
+    </Step>
+    <Step title="Add natural language descriptions">
+        To improve codemod generation accuracy, you can provide more context about the transformation to Codemod AI by adding [natural language descriptions](/codemod-studio#natural-language-descriptions-in-examples).
+
+        <video
+        autoPlay
+        loop
+        className="w-full aspect-video"
+        src="/images/guides/building-codemods/nld.mp4"
+        ></video>
+    </Step>
+    <Step title="Build codemod with AI">
+        By clicking "Autogenerate with Codemod AI" Codemod Studio will begin building your codemod.
+
+        <video
+        autoPlay
+        loop
+        className="w-full aspect-video"
+        src="/images/guides/building-codemods/generating-codemod.mp4"
+        ></video>
+
+    </Step>
+    <Step title="Test codemod (and iterate)">
+        After the codemod is generated, it will automatically be pasted into the codemod editor on the right side. The `Output` panel will show the result of running the codemod over the `Before` snippet in real time.
+
+        This allows you to compare the actual output of the codemod to the `After` snippet. If Codemod Studio detects discrepancies between the `Output` and `After` snippet, the code example will be highlighted in red.
+
+        Fixing various issues:
+
+        <AccordionGroup>
+            <Accordion title="Codemod execution error" icon="alien-8bit">
+                If a codemod execution error occurs, you can troubleshoot the codemod by inspecting the execution steps in the `Debug`.
+
+                <video
+                autoPlay
+                loop
+                className="w-full aspect-video"
+                src="/images/guides/building-codemods/debug.mp4"
+                ></video>
+
+                You can then ask Codemod AI to iterate and fix the codemod using the LLM chatbot.
+            </Accordion>
+
+            <Accordion title="Inaccurate codemod output" icon="circle-xmark">
+                If the codemod output is incorrect, you can:
+                - ask Codemod AI to fix the inaccuracies using the LLM chatbot (or generating again)
+                - provide more context to Codemod AI using natural language descriptions (refer to step 2)
+            </Accordion>
+        </AccordionGroup>
+    </Step>
+    <Step title="Exporting codemod">
+        Once your codemod is working correctly, you can:
+        - export the codemod package locally
+        - publish it to your private registry
+
+        In this tutorial, we will export the codemod package locally as we will be publishing to the public Codemod Registry in the next steps.
+
+        To export the codemod package, you can click **Download and run locally**.
+
+        <img height="200" src="/images/guides/building-codemods/export.png" />
+    </Step>
+</Steps>
+
+## Configuring codemod packages
+
+Now that we have a local codemod package, we can configure the `.codemodrc.json` file. Doing so helps Codemod platform understand more information about your codemod package to allow for a better publishing and running experience to your codemod.
+
+To configure the `.codemodrc.json` file, you can:
+
+1. Open `.codemodrc.json` using your preferred editor.
+2. Customize configuration fields.
+
+    By default, the file will look something similar to this:
+
+    ```json .codemodrc.json
+    {
+        "$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json",
+        "name": "react-19-callback-ref-replace",
+        "version": "1.0.0",
+        "engine": "jscodeshift",
+        "private": false,
+        "arguments": [],
+        "meta": {}
+    }
+    ```
+
+    In this example, we will:
+    1. adjust the previous auto-generated `name` value
+    2. populate the `meta` and `applicability` fields.
+
+    This will allow our codemod to integrate better with Codemod Registry's search and filtering so that users can find this codemod easily.
+
+    ```json .codemodrc.json
+    {
+        "$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json",
+        "name": "react/19/replace-string-ref",
+        "version": "1.0.0",
+        "engine": "jscodeshift",
+        "private": false,
+        "arguments": [],
+        "meta": {
+            "git": "https://github.com/codemod-com/codemod/tree/main/packages/codemods/react/19/replace-string-ref",
+            "tags": ["react", "migration"]
+        },
+        "applicability": {
+            "from": [["react", "<=", "18"]]
+        }
+    }
+    ```
+
+    <Tip>
+        You can find a list of all supported `.codemodrc.json` fields [here](/building-codemods/package-requirements#codemodrc-json-reference).
+    </Tip>
+
+## Publishing the codemod package
+
+Now that our codemod package is ready, we can publish it to Codemod Registry. To do so, you can:
+
+1. navigate to the root directory of the codemod package
+2. logging in with `codemod login`
+3. running `codemod publish`
+
+<Tip>
+    To learn more about publishing codemods, refer to [this guide](/sharing/publishing-codemods).
+</Tip>
+
+Now, your codemod will be available for anyone to discover and run from Codemod Registry.
+
+<Info>
+    You can find the published codemod built in this example [here](https://go.codemod.com/react-replace-string-ref).
+</Info>
+
+## Running codemods
+
+Finally, we can run the published codemod using [Codemod CLI](/deploying-codemods/cli). To do so, you can:
+
+1. Navigate to your target project
+
+2. Run the codemod:
+
+```bash
+codemod [codemod-name]
+```
+
+In this example, we can run the codemod using:
+
+```bash
+codemod react/19/replace-string-ref
+```
+
+<Warning>By default, running the codemod will attempt to apply the transformation on all target files in the current directory. Make sure to run the codemod in the correct project directory.</Warning>
+
+<Tip>
+    To learn more about running codemods, refer to [this page](/deploying-codemods/cli#run).
+</Tip>

apps/docs/guides/introduction.mdx

@@ -2,6 +2,19 @@
 title: 'Introduction'
 ---
 
+## Building codemods
+
+<CardGroup cols={2}>
+  <Card
+    title="Making your first codemod"
+    icon="play"
+    href="/guides/first-codemod"
+    horizontal
+  >
+    Get started with building, publishing, and running your first codemod.
+  </Card>
+</CardGroup>
+
 ## Migrations
 
 <CardGroup cols={2}>

apps/docs/mint.json

@@ -113,7 +113,7 @@
       "pages": ["deploying-codemods/vsce"]
     },
     {
-      "group": "Guides",
+      "group": "Core Concepts",
       "pages": [
         {
           "group": "Building codemods",
@@ -150,6 +150,10 @@
       "group": "Guides & Examples",
       "pages": ["guides/introduction"]
     },
+    {
+      "group": "Building Codemods",
+      "pages": ["guides/first-codemod"]
+    },
     {
       "group": "Migrations",
       "pages": [