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

# Domain Migration

> Guide to migrating your Farcaster Mini App to a new domain

While Mini Apps are designed to be associated with a stable domain, there are times when you may need to migrate your app to a new domain. This could be due to rebranding, domain expiration, or other business reasons.

The `canonicalDomain` field enables a smooth transition by allowing you to specify the new domain in your old manifest, ensuring clients can discover and redirect to your app's new location.

## How domain migration works

When a Mini App is accessed through its old domain, Farcaster clients check the manifest for a `canonicalDomain` field. If present, clients will:

1. Recognize that the app has moved to a new domain
2. Update their references to point to the new domain
3. Redirect users to the app at its new location

This ensures continuity for your users and preserves your app's presence in app stores and user installations.

### What happens to existing notification tokens

When Farcaster picks up the updated manifest with `canonicalDomain`, it automatically migrates all existing notification tokens from the old domain to the canonical domain. This means:

* Users who enabled notifications on your old domain **do not need to re-enable them**
* Notifications sent with a `targetUrl` on the new domain will be delivered to all existing subscribers
* If you use the same Neynar app (and therefore the same `webhookUrl`) on both domains, no additional Neynar configuration is needed — notifications will work seamlessly from the new domain once Farcaster processes the manifest update

<Warning>
  **Do not create a new Neynar app or change your `webhookUrl` during migration.**
  If you use a different `webhookUrl` on the new domain, new notification tokens
  will be stored in a separate Neynar app from the migrated ones, breaking
  notifications for existing users. Always reuse the same Neynar app and
  `webhookUrl` across both domains.
</Warning>

<Note>
  The automatic token migration happens on Farcaster's side when it processes your updated manifest. No database changes or API calls on your end are required.
</Note>

## Migration steps

<Steps>
  <Step title="Prepare your new domain">
    Set up your Mini App on the new domain with a complete manifest file at `/.well-known/farcaster.json`. This should include all your app configuration and an account association from the same FID to maintain ownership verification.

    ```json theme={"system"}
    {
      "accountAssociation": {
        "header": "...",
        "payload": "...",
        "signature": "..."
      },
      "miniapp": {
        "version": "1",
        "name": "Your App Name",
        "iconUrl": "https://new-domain.com/icon.png",
        "homeUrl": "https://new-domain.com",
        // ... other configuration
      }
    }
    ```
  </Step>

  <Step title="Update the old domain manifest">
    Add the `canonicalDomain` field to your manifest on the **old domain**, pointing to your new domain:

    ```json theme={"system"}
    {
      "accountAssociation": {
        "header": "...",
        "payload": "...",
        "signature": "..."
      },
      "miniapp": {
        "version": "1",
        "name": "Your App Name",
        "iconUrl": "https://old-domain.com/icon.png",
        "homeUrl": "https://old-domain.com",
        "canonicalDomain": "new-domain.com",
        // ... other configuration
      }
    }
    ```

    <Note>
      The `canonicalDomain` value must be a valid domain name without protocol, port, or path:

      * ✅ `app.new-domain.com`
      * ✅ `new-domain.com`
      * ❌ `https://new-domain.com`
      * ❌ `new-domain.com:3000`
      * ❌ `new-domain.com/app`
    </Note>
  </Step>

  <Step title="Add canonicalDomain to the new manifest">
    Include the `canonicalDomain` field in your new domain's manifest as well, pointing to itself. This ensures consistency and makes it clear which domain is canonical:

    ```json theme={"system"}
    {
      "accountAssociation": {
        "header": "...",
        "payload": "...",
        "signature": "..."
      },
      "miniapp": {
        "version": "1",
        "name": "Your App Name",
        "iconUrl": "https://new-domain.com/icon.png",
        "homeUrl": "https://new-domain.com",
        "canonicalDomain": "new-domain.com",
        // ... other configuration
      }
    }
    ```

    <Warning>
      Both manifests must be live simultaneously. Farcaster verifies the
      `canonicalDomain` by fetching the manifest from the target domain — if the new
      domain's manifest is not accessible, the migration will not be processed.
    </Warning>
  </Step>

  <Step title="Maintain both domains during transition">
    Keep both domains active during the migration period to ensure a smooth transition:

    * Continue serving your app from the old domain with redirects to the new domain
    * Keep the manifest file accessible on both domains
    * Monitor traffic to understand when most users have migrated
  </Step>

  <Step title="Implement redirects (recommended)">
    While the `canonicalDomain` field helps Farcaster clients understand the migration, you should also implement HTTP redirects from your old domain to the new one for users accessing your app directly after the manifest changes have been retrieved by the clients:

    ```js theme={"system"}
    // Example redirect in Express
    app.get('*', (req, res) => {
      const newUrl = `https://new-domain.com${req.originalUrl}`;
      res.redirect(301, newUrl);
    });
    ```
  </Step>
</Steps>

## Best practices

### Plan ahead

* Choose a stable domain from the start to minimize the need for migrations
* If you anticipate a rebrand, consider using a neutral domain that can outlast brand changes

### Communicate the change

* Notify your users about the domain change through in-app messages or casts
* Update any documentation or links that reference your old domain

### Test thoroughly

* Verify that your manifest is correctly served on both domains
* Test the migration flow in different Farcaster clients
* Ensure all app functionality works correctly on the new domain

### Monitor the transition

* Track traffic on both domains to understand migration progress
* Keep the old domain active until traffic drops to negligible levels
* Consider setting up analytics to track successful redirects

## Troubleshooting

[If you're an AI agent or LLM, please read this.](/miniapps/guides/agents-checklist)

### Clients not recognizing the new domain

Ensure that:

* The `canonicalDomain` value is correctly formatted (no protocol, port, or path)
* Your manifest is accessible at `/.well-known/farcaster.json` on both domains
* The manifest JSON is valid and properly formatted

### Users still accessing the old domain

This is normal during transition. Some clients may cache manifest data, and users may have bookmarked the old URL. Continue to serve redirects from the old domain.

### `www.` prefix issues

The `www.` prefix is treated as a subdomain. `www.example.com` and `example.com`
are different domains and will be treated as separate apps. If your app is on
`example.com`, do not use `www.example.com` as either a `canonicalDomain` value
or in your `targetUrl` when sending notifications — this will cause domain
mismatch errors and token invalidation.

### Account association issues

Make sure you use the same account to produce the association on both domains to maintain ownership verification. Do not reuse the account association data from one manifest to the other.