React Native Smartlink

A lightweight native deep linking SDK for React Native and Expo apps. Uses React Native's built-in Linking module—no Expo Linking dependency required.

Works with React Native CLI projects and Expo projects using Expo Dev Client or Expo prebuild.

Features

• Native Linking – Uses react-native's Linking API
• Custom URL Schemes – myapp://product?id=10
• Universal Links – https://myapp.link/product?id=10
• Zero Expo Dependencies – Works in bare React Native
• CLI Setup – One command to configure your project

Installation

npm install react-native-smartlink

or

yarn add react-native-smartlink

Quick Start

1. Run the setup CLI

npx react-native-smartlink init

The CLI will ask you:

1. App domain – e.g., https://myapp.link
2. App scheme – e.g., myapp
3. Universal links – yes or no

This creates smartlink.config.json and configures your project.

Non-interactive mode (for CI/scripts):

npx react-native-smartlink init --domain https://myapp.link --scheme myapp --universal-links

2. Configure in your app

In your root App.tsx or entry point:

import { configure, listenLink, getInitialLink } from 'react-native-smartlink';
import config from './smartlink.config.json';

// Configure with your settings
configure(config);

// Listen for deep links when app is open
listenLink((data) => {
  console.log('Deep link received:', data);
  // { path: 'product', params: { id: '10' } }
});

// Handle initial link (app launched from closed state)
getInitialLink().then((link) => {
  if (link) {
    console.log('App opened with:', link);
  }
});

3. Create deep links

import { createLink } from 'react-native-smartlink';

const url = createLink('product', { id: 10 });
// => "myapp://product?id=10"

Configuration

smartlink.config.json

Created by the CLI. Example:

{
  "domain": "https://myapp.link",
  "scheme": "myapp",
  "universalLinks": true
}

| Field | Description | |-------|-------------| | domain | Your app domain for universal links | | scheme | Custom URL scheme (e.g., myapp → myapp://) | | universalLinks | Enable HTTPS universal links |

API Reference

configure(config)

Set configuration at runtime. Call once at app startup.

import { configure } from 'react-native-smartlink';
import config from './smartlink.config.json';
configure(config);

createLink(path, params?)

Creates a deep link URL.

createLink('product', { id: 10 });
// => "myapp://product?id=10"

createLink('user/profile', { userId: '123' });
// => "myapp://user/profile?userId=123"

createLink('home');
// => "myapp://home"

listenLink(callback)

Listens for deep links when the app is already open. Returns an unsubscribe function.

const unsubscribe = listenLink((data) => {
  console.log(data); // { path: 'product', params: { id: '10' } }
});

// Later: unsubscribe();

getInitialLink()

Returns the deep link that launched the app (cold start). Resolves to null if the app wasn't opened via a deep link.

const link = await getInitialLink();
if (link) {
  console.log(link); // { path: 'product', params: { id: '10' } }
}

parseLink(url)

Parses a URL string into structured data.

parseLink('myapp://product?id=10');
// => { path: 'product', params: { id: '10' } }

getConfig()

Returns the current configuration.

const config = getConfig();
// => { domain: '...', scheme: '...', universalLinks: true }

Platform Setup

Android

The CLI automatically adds intent filters to AndroidManifest.xml for:

• Custom scheme: myapp://
• Universal links: https://myapp.link/*

If you need to add them manually, add this inside your main <activity>:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:scheme="myapp" android:host=""/>
  <data android:scheme="https" android:host="myapp.link" android:pathPrefix="/"/>
</intent-filter>

iOS

Custom URL Scheme

The CLI updates app.json with expo.scheme for Expo projects. For Expo prebuild, run:

npx expo prebuild

For bare React Native, add the URL scheme in Xcode:

1. Open the project in Xcode
2. Select your target → Info tab
3. Under URL Types, add a new entry
4. Set Identifier and URL Schemes to your scheme (e.g., myapp)

Universal Links

1. Create an apple-app-site-association file on your domain:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.yourapp.bundle",
        "paths": ["*"]
      }
    ]
  }
}

2. Serve it at https://myapp.link/.well-known/apple-app-site-association

3. In Xcode, add Associated Domains: applinks:myapp.link

4. For Expo: add to app.json:

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:myapp.link"]
    }
  }
}

Expo Projects

1. Run npx react-native-smartlink init
2. Run npx expo prebuild to regenerate native projects
3. Configure and use the SDK as shown above

Testing Deep Links

Android

adb shell am start -W -a android.intent.action.VIEW -d "myapp://product?id=10" com.yourapp

iOS Simulator

xcrun simctl openurl booted "myapp://product?id=10"

License

MIT