> ## 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.

# Node.js Userland Migrations

<div className="relative overflow-hidden dark:bg-[#0f1117] bg-white py-20">
  <div className="absolute inset-0 dark:bg-gradient-to-br dark:from-[#1a1d27] dark:via-[#0f1117] dark:to-[#0f1117] bg-gradient-to-br from-gray-50 via-white to-gray-50" />

  <div className="relative max-w-6xl mx-auto px-6">
    <div className="grid lg:grid-cols-12 gap-12 items-center">
      <div className="lg:col-span-7">
        <h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold dark:text-gray-100 text-gray-900 mb-6">
          Handle Breaking Changes Gracefully
        </h1>

        <p className="text-lg sm:text-xl dark:text-gray-400 text-gray-600 mb-8 max-w-2xl">
          A collection of automated migration recipes (codemods) for Node.js userland code. Update your codebase to adopt new features and handle deprecations with confidence.
        </p>

        <div className="flex flex-wrap gap-4">
          <a href="/quickstart" className="inline-flex items-center px-6 py-3 rounded-lg font-semibold text-white transition-colors no-underline" style={{backgroundColor: '#aebd57'}} onMouseOver={(e) => e.currentTarget.style.backgroundColor = '#9ba84d'} onMouseOut={(e) => e.currentTarget.style.backgroundColor = '#aebd57'}>
            Get Started

            <svg className="ml-2 w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 7l5 5m0 0l-5 5m5-5H6" />
            </svg>
          </a>

          <a href="/recipes/overview" className="inline-flex items-center px-6 py-3 rounded-lg font-semibold dark:text-gray-100 text-gray-900 dark:bg-white/10 bg-gray-100 dark:border-white/30 border-gray-300 border transition-colors dark:hover:bg-white/20 hover:bg-gray-200 no-underline">
            Explore Recipes
          </a>
        </div>
      </div>

      <div className="lg:col-span-5 hidden lg:block">
        <div className="dark:bg-[#1a1d27] bg-gray-50 rounded-2xl p-6 dark:border-[#27272a] border-gray-200 border shadow-xl">
          <div className="flex items-center gap-2 mb-4">
            <div className="w-3 h-3 rounded-full bg-red-500" />

            <div className="w-3 h-3 rounded-full bg-yellow-500" />

            <div className="w-3 h-3 rounded-full bg-green-500" />
          </div>

          <pre className="dark:text-gray-300 text-gray-700 text-sm overflow-x-auto">
            <code>
              {`$ npx codemod @nodejs/buffer-atob-btoa

                            ✓ Found 12 files to transform
                            ✓ Migrated buffer.atob() calls
                            ✓ Migrated buffer.btoa() calls
                            ✓ Removed legacy imports

                            Successfully migrated 12 files!`}
            </code>
          </pre>
        </div>
      </div>
    </div>
  </div>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <div className="text-center mb-12">
    <h2 className="text-2xl sm:text-3xl font-semibold dark:text-gray-100 text-gray-900 mb-4">
      Quick Start
    </h2>

    <p className="text-base dark:text-gray-400 text-gray-600 max-w-2xl mx-auto">
      Get up and running with codemods in just a few steps
    </p>
  </div>

  <Steps>
    <Step title="Commit your changes">
      Before running any codemod, commit your current work to version control. Codemods modify source code directly.

      ```bash theme={null}
      git add .
      git commit -m "Save work before migration"
      ```
    </Step>

    <Step title="Run a migration recipe">
      Choose a migration recipe from the catalog and run it with the Codemod CLI. Replace `<recipe>` with the name of the recipe you want to run.

      ```bash theme={null}
      npx codemod @nodejs/<recipe>
      ```

      <Accordion title="Example output">
        ```
        ✓ Found 8 files to transform
        ✓ Applied transformations
        ✓ Removed deprecated dependencies

        Successfully migrated 8 files!
        ```
      </Accordion>
    </Step>

    <Step title="Review and test">
      Review the changes made by the codemod, run your tests, and ensure everything works as expected.

      ```bash theme={null}
      git diff
      npm test
      ```
    </Step>

    <Step title="Commit the migration">
      Once you've verified the changes, commit them to your repository.

      ```bash theme={null}
      git add .
      git commit -m "Migrate to new Node.js API"
      ```
    </Step>
  </Steps>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <div className="text-center mb-12">
    <h2 className="text-2xl sm:text-3xl font-semibold dark:text-gray-100 text-gray-900 mb-4">
      Explore by Category
    </h2>

    <p className="text-base dark:text-gray-400 text-gray-600 max-w-2xl mx-auto">
      Find the right migration recipe for your use case
    </p>
  </div>

  <CardGroup cols={3}>
    <Card title="Buffer APIs" icon="database" href="/recipes/buffer-atob-btoa">
      Migrate legacy buffer.atob() and buffer.btoa() to modern alternatives
    </Card>

    <Card title="File System" icon="folder" href="/recipes/rmdir">
      Update deprecated fs.rmdir() calls to fs.rm() with recursive option
    </Card>

    <Card title="Crypto APIs" icon="lock" href="/recipes/crypto-fips-to-getFips">
      Migrate deprecated crypto.fips to crypto.getFips() and crypto.setFips()
    </Card>

    <Card title="Utilities" icon="wrench" href="/recipes/util-is">
      Replace deprecated util.is\* methods with modern alternatives
    </Card>

    <Card title="TypeScript" icon="code" href="/recipes/correct-ts-specifiers">
      Correct import specifiers for Node.js ESM compliance
    </Card>

    <Card title="Process APIs" icon="terminal" href="/recipes/process-main-module">
      Migrate process.mainModule to require.main
    </Card>
  </CardGroup>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <div className="text-center mb-12">
    <h2 className="text-2xl sm:text-3xl font-semibold dark:text-gray-100 text-gray-900 mb-4">
      Key Features
    </h2>

    <p className="text-base dark:text-gray-400 text-gray-600 max-w-2xl mx-auto">
      Why use Node.js Userland Migrations
    </p>
  </div>

  <div className="grid md:grid-cols-2 gap-6">
    <div className="dark:bg-[#1a1d27] bg-gray-50 rounded-xl p-6 dark:border-[#27272a] border-gray-200 border">
      <div className="w-12 h-12 rounded-lg dark:bg-[#242838] bg-gray-100 flex items-center justify-center mb-4" style={{color: '#aebd57'}}>
        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
        </svg>
      </div>

      <h3 className="text-lg font-semibold dark:text-gray-100 text-gray-900 mb-2">AST-Based Transformations</h3>

      <p className="dark:text-gray-400 text-gray-600">
        Powered by ast-grep and jssg API for accurate, safe code transformations that understand your code structure.
      </p>
    </div>

    <div className="dark:bg-[#1a1d27] bg-gray-50 rounded-xl p-6 dark:border-[#27272a] border-gray-200 border">
      <div className="w-12 h-12 rounded-lg dark:bg-[#242838] bg-gray-100 flex items-center justify-center mb-4" style={{color: '#aebd57'}}>
        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
        </svg>
      </div>

      <h3 className="text-lg font-semibold dark:text-gray-100 text-gray-900 mb-2">Automatic Dependency Management</h3>

      <p className="dark:text-gray-400 text-gray-600">
        Automatically removes deprecated packages from package.json when migrating to built-in Node.js APIs.
      </p>
    </div>

    <div className="dark:bg-[#1a1d27] bg-gray-50 rounded-xl p-6 dark:border-[#27272a] border-gray-200 border">
      <div className="w-12 h-12 rounded-lg dark:bg-[#242838] bg-gray-100 flex items-center justify-center mb-4" style={{color: '#aebd57'}}>
        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" />
        </svg>
      </div>

      <h3 className="text-lg font-semibold dark:text-gray-100 text-gray-900 mb-2">CommonJS & ESM Support</h3>

      <p className="dark:text-gray-400 text-gray-600">
        Works with both CommonJS (require) and ES modules (import), ensuring compatibility with your module system.
      </p>
    </div>

    <div className="dark:bg-[#1a1d27] bg-gray-50 rounded-xl p-6 dark:border-[#27272a] border-gray-200 border">
      <div className="w-12 h-12 rounded-lg dark:bg-[#242838] bg-gray-100 flex items-center justify-center mb-4" style={{color: '#aebd57'}}>
        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" />
        </svg>
      </div>

      <h3 className="text-lg font-semibold dark:text-gray-100 text-gray-900 mb-2">28 Migration Recipes</h3>

      <p className="dark:text-gray-400 text-gray-600">
        Comprehensive coverage of Node.js breaking changes across buffer, crypto, fs, util, and more.
      </p>
    </div>
  </div>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <div className="text-center mb-12">
    <h2 className="text-2xl sm:text-3xl font-semibold dark:text-gray-100 text-gray-900 mb-4">
      Resources
    </h2>
  </div>

  <CardGroup cols={2}>
    <Card title="Core Concepts" icon="book-open" href="/concepts/how-codemods-work">
      Learn how codemods work and when to use them
    </Card>

    <Card title="Developer Guide" icon="code" href="/contributing/overview">
      Contribute new recipes and help improve the project
    </Card>

    <Card title="API Reference" icon="brackets-curly" href="/api/overview">
      Explore the utilities for building custom codemods
    </Card>

    <Card title="GitHub Repository" icon="github" href="https://github.com/nodejs/userland-migrations">
      View the source code and contribute
    </Card>
  </CardGroup>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <div className="dark:bg-[#1a1d27] bg-gray-50 rounded-2xl p-8 sm:p-12 dark:border-[#27272a] border-gray-200 border text-center">
    <h2 className="text-2xl sm:text-3xl font-semibold dark:text-gray-100 text-gray-900 mb-4">
      Ready to Get Started?
    </h2>

    <p className="text-base dark:text-gray-400 text-gray-600 mb-6 max-w-2xl mx-auto">
      Run your first migration in minutes and keep your Node.js codebase up to date with the latest best practices.
    </p>

    <a href="/quickstart" className="inline-flex items-center px-6 py-3 rounded-lg font-semibold text-white transition-colors no-underline" style={{backgroundColor: '#aebd57'}} onMouseOver={(e) => e.currentTarget.style.backgroundColor = '#9ba84d'} onMouseOut={(e) => e.currentTarget.style.backgroundColor = '#aebd57'}>
      Get Started

      <svg className="ml-2 w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 7l5 5m0 0l-5 5m5-5H6" />
      </svg>
    </a>
  </div>
</div>