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.

react-graph-v1-to-v2

Migrates @neo4j-ndl/react-graph graph style rules from v1 to v2. This transform handles:

• Identifier/import renames: StyleRule → GraphStyleRule, StyleRuleSchema → GraphStyleRuleSchema, compileStyleRules → compileGraphStyleRules, CompiledStyleRules → CompiledGraphStyleRules (imports from @neo4j-ndl/react-graph and their references; aliased imports keep their local alias)
• Scalar style wrapping: scalar apply properties become { value } objects (e.g. color: '#f00' → color: { value: '#f00' }, same for size, width, icon)
• Range renames: nodeSizeRange → sizeRange, relWidthRange → widthRange
• Captions restructure: the apply.captions array becomes apply.captions.text, and captionAlign / captionSize are folded into captions.align / captions.size
• Rule-level rename: the rule-level disabled property becomes isDisabled

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

Style-rule object transforms only apply to object literals the codemod can statically recognize (objects with both match and apply keys). Rules built dynamically (variables, spreads, .map()) or stored as JSON cannot be reached; for those, recognized rules whose apply is not an inline object are annotated with a // TODO(ndl-codemod): verify v1->v2 style rule shape comment, and rules persisted as JSON/data can be migrated at runtime with migrateGraphStyleRulesToV2 from @neo4j-ndl/react-graph.

The new uniqueColors and metaData properties are additive and require no migration.

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/