Links

When building Mini Apps, proper link handling is crucial for providing a consistent user experience across different clients. This guide outlines best practices for external navigation and URL interactions.

Core Principles

Use SDK Actions for Cross-Client Compatibility

Always use official SDK functions instead of static URLs. Static URLs can break cross-client compatibility and may leave users unable to complete actions in your Mini App.

Avoid using direct HTML links (<a href="">, <Link href="">) or static URLs in your Mini App. These approaches don’t work consistently across different clients and can create poor user experiences.

Opening External URLs

With MiniKit
Without MiniKit

Use useOpenUrl() to safely open external websites in the client’s in-app browser:

components/ExternalLinks.tsx

import { useOpenUrl } from '@coinbase/onchainkit/minikit';

export default function ExternalLinks() {
  const openUrl = useOpenUrl();

  return (
    <div className="external-links">
      <button onClick={() => openUrl('https://base.org')}>
        Visit Base.org
      </button>
      <button onClick={() => openUrl('https://twitter.com/base')}>
        Follow on Twitter
      </button>
      <button onClick={() => openUrl('https://discord.gg/basechain')}>
        Join Discord
      </button>
    </div>
  );
}

// Incorrect: Direct HTML link
// <a href="https://example.com">Visit Site</a>

Use sdk.actions.openUrl() to safely open external websites in the client’s in-app browser:

App.tsx

import { sdk } from '@farcaster/miniapp-sdk';

// Correct: Use SDK action
const openExternalSite = () => {
  sdk.actions.openUrl('https://example.com');
};

// Incorrect: Direct HTML link
// <a href="https://example.com">Visit Site</a>

Composing Casts

With MiniKit
Without MiniKit

Use useComposeCast() to open the native composer with prefilled content:

components/ShareCast.tsx

import { useComposeCast } from '@coinbase/onchainkit/minikit';

export default function ShareCast() {
  const { composeCast } = useComposeCast();

  return (
    <button
      onClick={() =>
        composeCast({
          text: 'Check out this Mini App!',
          embeds: [window.location.href]
        })
      }
    >
      Share This App
    </button>
  );
}

// Incorrect: Composer intent URLs
// window.open('https://farcaster.com/~/compose?text=...')

Use sdk.actions.composeCast() instead of composer intent URLs:

App.tsx

import { sdk } from '@farcaster/miniapp-sdk';

// Correct: Use SDK action
const shareContent = () => {
  sdk.actions.composeCast({
    text: 'Check out this Mini App!',
    embeds: ['https://yourminiapp.com']
  });
};

// Incorrect: Composer intent URLs
// window.open('https://farcaster.com/~/compose?text=...')

Viewing Casts

With MiniKit
Without MiniKit

Use useViewCast() to open a specific cast by its hash:

components/ViewCastButton.tsx

import { useViewCast } from '@coinbase/onchainkit/minikit';

export default function ViewCastButton() {
  const viewCast = useViewCast('0x1234567890abcdef1234567890abcdef12345678');

  return (
    <button onClick={viewCast}>
      View Cast
    </button>
  );
}

Use sdk.actions.viewCast() instead of cast intent URLs:

App.tsx

import { sdk } from '@farcaster/miniapp-sdk';

// Correct: Use SDK action
const viewCast = () => {
  sdk.actions.viewCast('https://farcaster.com/cast/1234567890');
};

Best Practices

1. Prioritize SDK Actions

Before implementing any navigation or linking functionality:

Check if an official SDK action exists for your use case
Use the SDK action instead of crafting custom URLs
Test across multiple clients to ensure compatibility

2. Handle Unsupported Features Gracefully

When using features that may not be supported in all clients:

App.tsx

import { sdk } from '@farcaster/miniapp-sdk';

const handleExternalLink = (url) => {
  try {
    sdk.actions.openUrl(url);
  } catch (error) {
    // Fallback behavior for unsupported clients
    console.log('External navigation not supported');
  }
};

3. Avoid Client-Specific URLs

Don’t hardcode URLs specific to particular clients (like Warpcast URLs). Instead, use SDK actions that work across all supported clients.

Common Patterns

NavigationComponent.tsx

import { sdk } from 'farcaster/miniapp-sdk';

const NavigationComponent = () => {
  const handleExternalLink = () => {
    sdk.actions.openUrl('https://docs.example.com');
  };

  const handleShare = () => {
    sdk.actions.composeCast({
      text: 'Just used this amazing Mini App!',
      embeds: [window.location.href]
    });
  };

  return (
    <div>
      <button onClick={handleExternalLink}>
        View Documentation
      </button>
      <button onClick={handleShare}>
        Share This App
      </button>
    </div>
  );
};

ConditionalNavigation.tsx

import { sdk } from 'farcaster/miniapp-sdk';

const ConditionalNavigation = () => {
  const context = sdk.context;
  
  const handleNavigation = () => {
    // Adapt behavior based on client capabilities
    if (context.client.clientFid) {
      sdk.actions.openUrl('https://app-specific-url.com');
    } else {
      // Fallback for other clients
      window.open('https://fallback-url.com', '_blank');
    }
  };

  return (
    <button onClick={handleNavigation}>
      Open External Resource
    </button>
  );
};

Migration Guide

If your Mini App currently uses static URLs or direct links, update them using these patterns:

Current Implementation	Recommended SDK Action
`<a href="https://external.com">`	`sdk.actions.openUrl('https://external.com')`
`window.open('https://farcaster.com/~/compose?text=...')`	`sdk.actions.composeCast({ text: '...', embeds: [...] })`
Farcaster-specific deeplinks	Use appropriate SDK action
Direct profile links	Use SDK actions for profile navigation when available

Future Considerations

While deeplinks are not currently supported, they are on the roadmap. When they become available, this documentation will be updated with specific implementation guidance. In the meantime, continue using SDK actions for the most reliable cross-client experience.

Introduction

Quickstart

Design Guidelines

Growth Playbook

Features

Troubleshooting

Technical Reference

Resources

Core Principles

Use SDK Actions for Cross-Client Compatibility

External Navigation

Opening External URLs

Composing Casts

Viewing Casts

Best Practices

1. Prioritize SDK Actions

2. Handle Unsupported Features Gracefully

3. Avoid Client-Specific URLs

Common Patterns

Navigation Buttons

Conditional Navigation

Migration Guide

Future Considerations

​Core Principles

​Use SDK Actions for Cross-Client Compatibility

​External Navigation

​Opening External URLs

​Composing Casts

​Viewing Casts

​Best Practices

​1. Prioritize SDK Actions

​2. Handle Unsupported Features Gracefully

​3. Avoid Client-Specific URLs

​Common Patterns

​Navigation Buttons

​Conditional Navigation

​Migration Guide

​Future Considerations

Core Principles

Use SDK Actions for Cross-Client Compatibility

External Navigation

Opening External URLs

Composing Casts

Viewing Casts

Best Practices

1. Prioritize SDK Actions

2. Handle Unsupported Features Gracefully

3. Avoid Client-Specific URLs

Common Patterns

Navigation Buttons

Conditional Navigation

Migration Guide

Future Considerations