tessl/npm-expo-linking

Create and open deep links universally across React Native, Expo, and web platforms

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

React Integration

Name: tessl/npm-expo-linking
Author: tessl

React hooks and event listeners for responding to URL changes and deep link events in your application components.

Capabilities

URL Event Listener

Add handlers for URL change events using React Native's Linking event system.

/**
 * Add a handler to Linking changes by listening to the 'url' event type and providing the handler.
 * It is recommended to use the useLinkingURL() hook instead.
 * @param type - The only valid type is 'url'
 * @param handler - A URLListener function that takes an event object of the type EventType
 * @returns An EmitterSubscription that has the remove method from EventSubscription
 */
function addEventListener(type: 'url', handler: URLListener): EmitterSubscription;

type URLListener = (event: EventType) => void;

interface EventType {
  /** The URL that triggered the event */
  url: string;
  /** Optional native event data (web only) */
  nativeEvent?: MessageEvent;
}

Usage Example:

import { addEventListener } from "expo-linking";
import { useEffect } from "react";

function MyComponent() {
  useEffect(() => {
    const subscription = addEventListener('url', (event) => {
      console.log('Received URL:', event.url);
      // Handle the incoming URL
      handleDeepLink(event.url);
    });

    // Cleanup subscription on unmount
    return () => subscription.remove();
  }, []);

  return <div>My Component</div>;
}

Linking URL Hook (Recommended)

React hook that returns the linking URL and listens for changes, providing immediate access to the initial URL.

/**
 * Returns the linking URL followed by any subsequent changes to the URL.
 * Always returns the initial URL immediately on reload.
 * @returns Returns the initial URL or null
 */
function useLinkingURL(): string | null;

Usage Example:

import { useLinkingURL } from "expo-linking";
import { useEffect } from "react";

function MyComponent() {
  const url = useLinkingURL();

  useEffect(() => {
    if (url) {
      console.log('Current URL:', url);
      // Handle URL change
      handleURLChange(url);
    }
  }, [url]);

  return (
    <div>
      {url ? `Current URL: ${url}` : "No URL"}
    </div>
  );
}

URL Hook (Deprecated)

Legacy React hook for URL changes. Use useLinkingURL() instead.

/**
 * Returns the initial URL followed by any subsequent changes to the URL.
 * @deprecated Use useLinkingURL hook instead
 * @returns Returns the initial URL or null
 */
function useURL(): string | null;

Migration Example:

// Old (deprecated)
import { useURL } from "expo-linking";
const url = useURL();

// New (recommended)
import { useLinkingURL } from "expo-linking";
const url = useLinkingURL();

Complete React Integration Example

Here's a comprehensive example showing how to handle deep links in a React component:

import { useLinkingURL, parse } from "expo-linking";
import { useEffect, useState } from "react";

interface DeepLinkData {
  screen?: string;
  params?: Record<string, string>;
}

function AppDeepLinkHandler() {
  const url = useLinkingURL();
  const [deepLinkData, setDeepLinkData] = useState<DeepLinkData | null>(null);

  useEffect(() => {
    if (url) {
      const parsed = parse(url);
      
      if (parsed.path) {
        const [screen, ...pathParams] = parsed.path.split('/');
        
        setDeepLinkData({
          screen,
          params: {
            ...parsed.queryParams,
            ...(pathParams.length > 0 && { id: pathParams[0] })
          }
        });
      }
    }
  }, [url]);

  useEffect(() => {
    if (deepLinkData) {
      // Navigate based on deep link data
      switch (deepLinkData.screen) {
        case 'profile':
          navigateToProfile(deepLinkData.params?.id);
          break;
        case 'settings':
          navigateToSettings(deepLinkData.params?.tab);
          break;
        default:
          console.log('Unknown deep link screen:', deepLinkData.screen);
      }
    }
  }, [deepLinkData]);

  return (
    <div>
      {url && <p>Handling deep link: {url}</p>}
      {deepLinkData && (
        <pre>{JSON.stringify(deepLinkData, null, 2)}</pre>
      )}
    </div>
  );
}

Manual Event Handling

For more advanced use cases where you need fine-grained control over event handling:

import { addEventListener } from "expo-linking";
import { useEffect, useRef } from "react";

function AdvancedLinkHandler() {
  const handlerRef = useRef<((event: EventType) => void) | null>(null);

  useEffect(() => {
    handlerRef.current = (event) => {
      console.log('URL event received:', event);
      
      // Custom handling logic
      if (event.url.includes('/emergency/')) {
        handleEmergencyLink(event.url);
      } else {
        handleRegularLink(event.url);
      }
    };

    const subscription = addEventListener('url', (event) => {
      handlerRef.current?.(event);
    });

    return () => subscription.remove();
  }, []);

  return <div>Advanced Link Handler</div>;
}