> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate a Ponder app to Portal

> Move an existing Ponder app to the Portal-backed package and validate the migration.

Replace the stock package instead of installing both packages side by side.

<Steps>
  <Step title="Replace the dependency">
    ```bash theme={"system"}
    npm uninstall ponder
    npm install --save-exact @subsquid/ponder@latest
    ```

    This resolves npm's current `latest` tag and saves that exact fork version. Commit the lockfile with the migration.
  </Step>

  <Step title="Update package imports">
    Import package APIs from `@subsquid/ponder` in `ponder.config.ts`, `ponder.schema.ts`, and API files:

    ```ts theme={"system"}
    import { createConfig, factory } from "@subsquid/ponder";
    import { onchainTable } from "@subsquid/ponder";
    import { client, graphql } from "@subsquid/ponder";
    ```

    Keep Ponder virtual-module imports unchanged:

    ```ts theme={"system"}
    import { ponder } from "ponder:registry";
    import { db } from "ponder:api";
    import schema from "ponder:schema";
    ```
  </Step>

  <Step title="Add a Portal dataset per chain">
    Add a `portal` dataset URL beside each chain's existing `rpc` URL:

    ```ts theme={"system"}
    chains: {
      mainnet: {
        id: 1,
        rpc: process.env.PONDER_RPC_URL_1,
        portal: "https://portal.sqd.dev/datasets/ethereum-mainnet",
      },
    }
    ```

    Keep the RPC configured for realtime indexing, chain setup, and contract reads.
  </Step>

  <Step title="Validate a bounded range">
    Set a bounded `startBlock` and `endBlock`, then run the migrated app:

    ```bash theme={"system"}
    npm run dev
    ```

    Compare the resulting rows or application-level aggregates with the stock RPC path before widening the range. The repository's [migration guide](https://github.com/subsquid-labs/portal-ponder/blob/main/MIGRATION.md) includes compatibility checks and tooling that compares the two paths row by row.
  </Step>
</Steps>

## Roll back

To return to stock Ponder, replace `@subsquid/ponder` with `ponder`, restore package imports, and remove the `portal` fields. Your handlers, schema, and virtual-module imports do not need to change.

Check [Benchmarks and validation](/en/sdk/alternative-clients/ponder/benchmarks-and-validation) for the currently tested versions, sources, and datasets. Because the integration tracks active Ponder development, repeat the bounded comparison when upgrading either package line.