@machinemetrics/mm-react-components 0.2.0 → 0.2.3-1

package/scripts/chakra-to-shadcn-migrator/README.md

@@ -0,0 +1,107 @@
+# chakra-to-shadcn-migrator
+
+A lightweight command-line helper that generates a step-by-step plan for migrating a React codebase from Chakra UI to a Shadcn-based component library. It can optionally apply safe, mechanical edits (dependency updates and import rewrites) whenever explicit mappings are provided.
+
+## Features
+
+- Prints a deterministic migration checklist that covers dependency changes, provider updates, and per-file component swaps.
+- Detects Chakra imports across the project and maps them to their Shadcn counterparts based on a configuration file.
+- Optional `--apply` flag will rewrite imports and package dependencies when all referenced Chakra components have a mapping.
+- Built to be reusable across applications – provide a new mapping config to reuse the workflow.
+
+## Installation
+
+Until the package is published, you can run it directly from the repository:
+
+```bash
+node ../chakra-to-shadcn-migrator/bin/chakra-to-shadcn.js --project . --config chakra-to-shadcn.config.json
+```
+
+Or add an npm script to your project (see the knowledge-client example below).
+
+## Usage
+
+```bash
+chakra-to-shadcn --project <path-to-project> --config <config-file> [options]
+```
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `-p, --project` | Root directory of the application you want to migrate. Defaults to the current working directory. |
+| `-c, --config` | Path to a `chakra-to-shadcn.config.json` file. If omitted, the tool will look for one in the project root. |
+| `--apply` | Apply safe automated edits (dependency updates + import rewrites). Without this flag the tool only prints the migration plan. |
+| `--source` | Comma separated list of directories/glob patterns to scan for Chakra imports (defaults to `src`). |
+| `--include-tests` | Include `__tests__`, `*.test.*`, `*.spec.*`, and `*.stories.*` files when scanning. |
+
+## Configuration format
+
+Place a `chakra-to-shadcn.config.json` file in your project (or supply one via `--config`). The file describes:
+
+- Packages to remove and add in `package.json`.
+- Human-readable provider instructions.
+- Module/Component mappings that tell the tool how to rewrite imports.
+- Post-migration reminders.
+
+```json
+{
+  "dependenciesToRemove": ["@chakra-ui/react", "@chakra-ui/icons"],
+  "dependenciesToAdd": {"@machinemetrics/ui-shadcn": "latest"},
+  "moduleMappings": {
+    "@chakra-ui/react": {
+      "default": { "module": "@machinemetrics/ui-shadcn" },
+      "specifiers": {
+        "Button": { "module": "@machinemetrics/ui-shadcn", "import": "Button" },
+        "Card": { "module": "@machinemetrics/ui-shadcn/card", "import": "Card" }
+      }
+    }
+  },
+  "providerInstructions": [
+    "Replace ChakraProvider with the UiProvider from @machinemetrics/ui-shadcn/providers in src/index.tsx."
+  ],
+  "postSteps": [
+    "Run npm install",
+    "Remove Chakra-specific theme utilities"
+  ]
+}
+```
+
+The `moduleMappings` section lists each Chakra package you wish to replace. For each import specifier the tool either:
+
+- Finds an explicit mapping under `specifiers`, or
+- Falls back to the `default` mapping.
+
+If a Chakra component has no mapping, the tool flags it as a manual follow-up instead of modifying the file.
+
+## Example: knowledge-client
+
+The `knowledge-client/app` project contains a `chakra-to-shadcn.config.json` tailored to its component usage. Add the following npm script to run the migration helper:
+
+```json
+{
+  "scripts": {
+    "migrate:chakra-to-shadcn": "node ../chakra-to-shadcn-migrator/bin/chakra-to-shadcn.js --project . --config chakra-to-shadcn.config.json"
+  }
+}
+```
+
+From inside `knowledge-client/app` run:
+
+```bash
+npm run migrate:chakra-to-shadcn
+```
+
+Run with `--apply` when you are ready for the tool to make the safe edits.
+
+## Suggested workflow
+
+1. Run the tool in dry-run mode to generate the migration plan.
+2. Fix any manual follow-ups noted in the report or extend the configuration with more component mappings.
+3. Re-run with `--apply` to let the tool update dependencies and rewrite the mapped imports.
+4. Replace the Chakra provider/theme setup, copy any required Shadcn utility files, and execute the post-steps listed in the plan.
+5. Execute your usual test suite to verify the migration.
+
+## License
+
+MIT