Codemod Package

This package provides a set of codemods for transforming codebases using @neo4j-ndl packages. Codemods are scripts used to automate code refactoring and migrations.

Table of Contents

• Usage
• Transforms
• Developing

Usage

To run a codemod, run the following command and follow the interactive prompts:

npx @neo4j-ndl/codemod

You can also specify the transform and target path directly:

npx @neo4j-ndl/codemod <transform> <path>

Options

| Option | Description | |--------|-------------| | --force, -f | Bypass Git safety checks and forcibly run codemods | | --dry, -d | Dry run (no changes are made to files) | | --print, -p | Print transformed files to your terminal | | --jscodeshift, -j | Pass options directly to jscodeshift | | --prefix <prefix> | Tailwind class prefix (default: n-). Used by base-v3-to-v4. |

Transforms

The following transforms are available:

react-v2-to-v3

Migrates @neo4j-ndl/react component usage from v2 to v3. Handles prop renames, component API changes, and import updates.

npx @neo4j-ndl/codemod react-v2-to-v3 ./src

react-v3-to-v4

Migrates @neo4j-ndl/react component usage from v3 to v4. Handles prop renames, component restructuring (e.g. Banner composite pattern, Button variants), icon renames, and JavaScript token object access patterns.

npx @neo4j-ndl/codemod react-v3-to-v4 ./src

base-v3-to-v4

Migrates CSS variables, Tailwind classes, and JavaScript token usage from @neo4j-ndl/base v3 to v4. This transform handles:

• CSS variable renames: --theme-palette-* → --theme-color-*, --font-weight-* → --weight-*, --font-size-*/--font-font-family-* → --typography-*, transition variables → motion variables
• Tailwind palette class removal: removes the palette- segment from color utility classes (e.g. n-text-palette-neutral-text-default → n-text-neutral-text-default)
• Spacing token migration: maps sequential token keys to pixel-value-based keys (e.g. token-3 → token-4, token-6 → token-16)
• Typography class renames: n-h1 → n-display, n-h2 → n-title-1, etc.
• JS token object access: tokens.theme.*.palette.* → tokens.theme.*.color.*, tokens.font.weight.* → tokens.weight.*, tokens.font['font-family'].* → tokens.typography.*.fontFamily, tokens.font.size.* → tokens.typography.*.fontSize

npx @neo4j-ndl/codemod base-v3-to-v4 ./src

If your project uses a custom Tailwind prefix (or no prefix), pass it with --prefix:

npx @neo4j-ndl/codemod base-v3-to-v4 ./src --prefix ""

This transform operates on all common web file types: .tsx, .ts, .jsx, .js, .css, .scss, .pcss, .html, .vue, .svelte.

Developing

To contribute to this project, follow these steps:

1. Install dependencies:

   pnpm install

2. Run the tests:

   pnpm test

3. Build the package:

   pnpm build

Adding a new transform

1. Create a new transform file in transforms/ (e.g. transforms/my-transform.ts)
2. Add it to TRANSFORMER_INQUIRER_CHOICES in utils/bin-utils.ts
3. Add test fixtures in transforms/test-fixtures/ and a test in transforms/tests/