> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nodejs/userland-migrations/llms.txt
> Use this file to discover all available pages before exploring further.

# Safety Best Practices

> Learn how to run Node.js codemods safely with version control, testing, and validation strategies

Codemods modify your source code automatically. Following these best practices ensures safe, reliable transformations.

<Warning>
  **CRITICAL: Always commit your changes before running codemods.** Codemods change source code. Uncommitted changes may be lost or corrupted. This is not optional.
</Warning>

## Pre-Flight Checklist

Before running any codemod:

<Steps>
  <Step title="Commit all changes">
    Ensure your working directory is clean with `git status`

    ```bash theme={null}
    git status
    # Should show: "nothing to commit, working tree clean"
    ```
  </Step>

  <Step title="Create a dedicated branch">
    Make changes on a separate branch for easy rollback

    ```bash theme={null}
    git checkout -b migration/util-is-to-native
    ```
  </Step>

  <Step title="Backup important work">
    For critical migrations, create a backup branch

    ```bash theme={null}
    git branch backup/before-codemod
    ```
  </Step>

  <Step title="Review the codemod documentation">
    Understand what the codemod will change

    ```bash theme={null}
    npx codemod @nodejs/<recipe> --help
    ```
  </Step>
</Steps>

## Running Codemods Safely

### Start with a Dry Run

Many codemods support dry-run mode to preview changes:

```bash theme={null}
# Preview without modifying files
npx codemod @nodejs/util-is --dry-run
```

<Note>
  Not all codemods support `--dry-run`. Check the codemod's documentation or try running with `--help`.
</Note>

### Test on a Small Scope First

Before running on your entire codebase:

```bash theme={null}
# Test on a single directory
cd src/utils
npx codemod @nodejs/util-is

# Review the changes
git diff

# If good, proceed with the rest
cd ../..
npx codemod @nodejs/util-is
```

### Review Changes Immediately

After running a codemod:

```bash theme={null}
# See what changed
git diff

# See which files were modified
git status

# Review changes file by file
git diff src/file1.js
git diff src/file2.js
```

<Tip>
  Use a visual diff tool like `git difftool` or your IDE's built-in diff viewer for easier review.
</Tip>

## Validation Strategy

### 1. Run Your Test Suite

Your existing tests are the first line of defense:

```bash theme={null}
# Run all tests
npm test

# Run specific test suites
npm test -- --grep "utility functions"
```

**What to check:**

* All tests pass
* No new warnings or errors
* Test coverage hasn't decreased
* Performance hasn't degraded

### 2. Check Linting and Type Checking

Ensure code quality standards are maintained:

```bash theme={null}
# Run linter
npm run lint

# Run TypeScript type checking
npm run typecheck
# or
tsc --noEmit
```

**Common issues after codemods:**

* Unused imports (codemod removed usage but not import)
* Type errors (API signature changes)
* Formatting issues (indentation, spacing)

<Note>
  Many codemods try to preserve formatting, but some manual cleanup may be needed. Run your formatter:

  ```bash theme={null}
  npm run format
  # or
  prettier --write .
  ```
</Note>

### 3. Manual Code Review

Spot-check transformed code:

**Focus areas:**

* **Edge cases**: Look for unusual patterns the codemod might mishandle
* **Complex expressions**: Nested calls, ternaries, template literals
* **Comments**: Ensure comments still make sense after transformation
* **Formatting**: Check indentation and readability

**Example review:**

```javascript theme={null}
// Before codemod
const isValid = util.isArray(data) && data.length > 0;

// After codemod - verify logic is preserved
const isValid = Array.isArray(data) && data.length > 0; // ✅ Correct

// Watch for complex cases
const check = condition ? util.isArray : util.isObject;
// Did the codemod handle this correctly? ⚠️ Needs review
```

### 4. Integration Testing

If you have integration or e2e tests:

```bash theme={null}
# Run integration tests
npm run test:integration

# Run e2e tests
npm run test:e2e
```

Integration tests catch issues that unit tests miss:

* API contract changes
* Behavior differences in edge cases
* Performance regressions

### 5. Build and Package

Ensure the project still builds:

```bash theme={null}
# Build the project
npm run build

# Check the build output
ls -la dist/

# Try packaging (if applicable)
npm pack
```

## Rollback Strategies

### Quick Rollback with Git

If something goes wrong:

```bash theme={null}
# Discard all changes (if not committed)
git checkout .

# Undo the last commit (if you committed)
git reset --hard HEAD~1

# Return to a specific commit
git reset --hard <commit-hash>

# Switch to your backup branch
git checkout backup/before-codemod
```

<Warning>
  `git reset --hard` permanently deletes uncommitted changes. Use with caution.
</Warning>

### Selective Rollback

Rollback specific files:

```bash theme={null}
# Restore a single file
git checkout HEAD -- src/problematic-file.js

# Restore multiple files
git checkout HEAD -- src/file1.js src/file2.js

# Restore entire directory
git checkout HEAD -- src/utils/
```

### Revert Merged Changes

If the codemod was already merged:

```bash theme={null}
# Create a revert commit
git revert <merge-commit-hash>

# Push the revert
git push origin main
```

## Advanced Safety Techniques

### Incremental Migration

For large codebases, migrate incrementally:

<Steps>
  <Step title="Phase 1: Core utilities">
    Run codemod on your utility library first

    ```bash theme={null}
    npx codemod @nodejs/util-is src/utils/
    ```
  </Step>

  <Step title="Phase 2: Individual modules">
    Migrate one module at a time

    ```bash theme={null}
    npx codemod @nodejs/util-is src/auth/
    git add src/auth && git commit -m "migrate: auth module"
    ```
  </Step>

  <Step title="Phase 3: Test and iterate">
    Run tests after each phase, fix issues before proceeding
  </Step>

  <Step title="Phase 4: Remaining code">
    Complete migration across the codebase
  </Step>
</Steps>

**Benefits:**

* Easier to isolate issues
* Smaller, reviewable commits
* Less risky than "big bang" migration
* Can pause and resume migration

### Automated Safety Checks

Add pre-commit hooks to catch issues:

```json theme={null}
// package.json
{
  "scripts": {
    "pre-commit": "npm run lint && npm test"
  }
}
```

Or use tools like [husky](https://github.com/typicode/husky):

```bash theme={null}
# .husky/pre-commit
npm run lint
npm test
```

### Snapshot Testing

For critical code, create snapshots before migration:

```javascript theme={null}
// Save current behavior
const before = {
  result1: myFunction(input1),
  result2: myFunction(input2),
  // ...
};

// After codemod, verify behavior is identical
const after = {
  result1: myFunction(input1),
  result2: myFunction(input2),
};

assert.deepEqual(before, after);
```

## Testing Codemods Locally

If you're developing or testing a codemod:

### From Source

```bash theme={null}
# Clone the repository
git clone https://github.com/nodejs/userland-migrations.git
cd userland-migrations

# Run codemod from local file
cd /path/to/your-project
npx codemod workflow run -w /path/to/userland-migrations/recipes/util-is/workflow.yaml
```

### Test Fixtures

Create test cases before running on real code:

```javascript theme={null}
// test-fixture.js
const util = require('util');

// Test various patterns
const test1 = util.isArray([]);
const test2 = util.isString('hello');
const test3 = util.isFunction(() => {});

// Test edge cases
const test4 = condition ? util.isArray : util.isObject;
const test5 = items.filter(util.isArray);
```

Run the codemod on the fixture and verify results:

```bash theme={null}
cp test-fixture.js test-fixture-backup.js
npx codemod @nodejs/util-is test-fixture.js
diff test-fixture.js test-fixture-backup.js
```

## Common Issues and Solutions

### Issue: Codemod Skipped Files

**Symptom:** Some files weren't transformed

**Cause:** The codemod didn't find matching patterns

**Solution:**

```bash theme={null}
# Check if imports exist
grep -r "require('util')" src/
grep -r "from 'util'" src/

# Check file extensions
find src/ -name "*.js" -o -name "*.ts"
```

### Issue: Syntax Errors After Codemod

**Symptom:** Code doesn't parse or run

**Cause:** Codemod generated invalid syntax

**Solution:**

```bash theme={null}
# Find syntax errors
npm run lint
# or
node --check src/**/*.js

# Review the problematic files
git diff src/broken-file.js

# Fix manually or rollback
git checkout src/broken-file.js
```

### Issue: Tests Failing

**Symptom:** Previously passing tests now fail

**Cause:** Behavior change or edge case not handled

**Solution:**

1. Review the failing test
2. Check if the transformation was correct
3. Update test if the change is intentional
4. Fix the code if the transformation was wrong

```bash theme={null}
# Run specific test
npm test -- --grep "the failing test"

# Debug with verbose output
DEBUG=* npm test
```

### Issue: Merge Conflicts

**Symptom:** Git conflicts when merging migration branch

**Cause:** Main branch changed during migration

**Solution:**

```bash theme={null}
# Update your migration branch
git checkout migration/util-is
git merge main

# Resolve conflicts
# Then re-run codemod on conflicted files if needed
npx codemod @nodejs/util-is src/conflicted-file.js

git add .
git commit -m "resolve: merge conflicts after codemod"
```

## Team Coordination

When running codemods on shared codebases:

### Communication

1. **Announce the migration** in your team channel
2. **Freeze PRs** temporarily to avoid conflicts
3. **Schedule migration** during low-activity periods
4. **Document the process** for team reference

### Pull Request Best Practices

**Good PR structure:**

```
Title: migrate(util-is): replace util.is* with native checks

Description:
- Ran @nodejs/util-is codemod
- Reviewed all changes manually
- All tests passing
- No behavior changes expected

Files changed: 47 files
Breaking changes: None

Testing:
- ✅ Unit tests passing
- ✅ Integration tests passing
- ✅ Linter passing
- ✅ TypeScript types valid

Checklist:
- [x] Committed before running codemod
- [x] Reviewed all diffs
- [x] Ran test suite
- [x] Checked for edge cases
- [x] Updated documentation if needed
```

**Commit strategy:**

```bash theme={null}
# Option 1: Single commit (small changes)
git add .
git commit -m "migrate(util-is): replace util.is* with native checks"

# Option 2: Separate commits (large changes)
git add src/utils/
git commit -m "migrate(util-is): transform utils module"

git add src/services/
git commit -m "migrate(util-is): transform services module"

git add .
git commit -m "migrate(util-is): cleanup unused imports"
```

### Code Review Tips

For reviewers:

* **Trust but verify**: Codemods are reliable but not perfect
* **Spot-check edge cases**: Don't review every line, focus on complex patterns
* **Run tests locally**: Don't rely solely on CI
* **Check the diff stats**: Unusual patterns might indicate issues

```bash theme={null}
# See change statistics
git diff --stat

# See detailed diff for specific file types
git diff -- '*.js' | less
```

## Production Deployment

Before deploying codemod changes to production:

<Steps>
  <Step title="Staging environment">
    Deploy to staging first

    ```bash theme={null}
    git push origin migration/util-is:staging
    ```
  </Step>

  <Step title="Smoke tests">
    Run critical path tests in staging
  </Step>

  <Step title="Monitor metrics">
    Check performance, error rates, logs
  </Step>

  <Step title="Gradual rollout">
    Use feature flags or canary deployments if possible
  </Step>

  <Step title="Production deployment">
    Deploy to production with rollback plan ready
  </Step>
</Steps>

<Warning>
  For critical production systems, consider deploying migrations during maintenance windows or low-traffic periods.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="How Codemods Work" href="/concepts/how-codemods-work">
    Understand the technical foundation of AST transformations
  </Card>

  <Card title="When to Use Codemods" href="/concepts/when-to-use">
    Learn when codemods are the right choice
  </Card>
</CardGroup>

## Additional Resources

* [Contributing Guide](/contributing/overview) - Development workflow and testing
* [Codemod CLI Reference](https://docs.codemod.com/cli/cli-reference) - Command options
* [Available Codemods](https://codemod.link/nodejs-official) - Browse the registry

<Tip>
  The Node.js Userland codemods are battle-tested and used across thousands of projects. Most issues you encounter will be edge cases specific to your codebase, not bugs in the codemod itself.
</Tip>