## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.neynar.com/llms.txt)

Use this file to discover all available pages before exploring further.

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

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

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.

## Migration steps

1. **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
{
  "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
  }
}
```

2. **Update the old domain manifest**  
Add the `canonicalDomain` field to your manifest on the **old domain**, pointing to your new domain:

```json
{
  "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
  }
}
```

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`

3. **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
{
  "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
  }
}
```

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.

4. **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

5. **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:

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

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

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