@rajeev02/deeplink 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# @rajeev02/deeplink
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@rajeev02/deeplink)
|
|
4
|
+
[](https://github.com/Rajeev02/rajeev-sdk/blob/main/LICENSE)
|
|
5
|
+
|
|
6
|
+
**Universal deep linking** with pattern matching, param extraction, UTM attribution, and deferred deep links — includes 19 pre-built super-app routes.
|
|
7
|
+
|
|
8
|
+
Part of [Rajeev SDK](https://github.com/Rajeev02/rajeev-sdk) — cross-platform infrastructure libraries for building apps that work everywhere.
|
|
9
|
+
|
|
10
|
+
## Why use this?
|
|
11
|
+
|
|
12
|
+
- **Route matching** — URL pattern matching with `:param` extraction, query string parsing
|
|
13
|
+
- **19 pre-built routes** — Common super-app screens (product, cart, checkout, order tracking, profile, chat, etc.)
|
|
14
|
+
- **UTM attribution** — Automatic UTM parameter extraction and analytics callback
|
|
15
|
+
- **Deferred deep links** — Handle links that arrive before the app is ready (cold start)
|
|
16
|
+
- **Universal + App links** — Generate both `myapp://` scheme links and `https://` universal links
|
|
17
|
+
- **Pure TypeScript** — No native link handling dependency. Plug into React Navigation or any router.
|
|
18
|
+
|
|
19
|
+
## ⚠️ Important: Native Deep Link Setup Required
|
|
20
|
+
|
|
21
|
+
This library provides the **URL routing and matching engine** — it parses incoming URLs, matches them to registered routes, and extracts parameters. But to actually **receive** deep links in your app, you need native configuration:
|
|
22
|
+
|
|
23
|
+
**Custom URL Scheme (`myapp://`):**
|
|
24
|
+
|
|
25
|
+
- **iOS:** Register your URL scheme in Xcode → Info → URL Types
|
|
26
|
+
- **Android:** Add intent filters for your scheme in `AndroidManifest.xml`
|
|
27
|
+
|
|
28
|
+
**Universal Links / App Links (`https://yourdomain.com/...`):**
|
|
29
|
+
|
|
30
|
+
- **iOS:** Add Associated Domains capability (`applinks:yourdomain.com`) and host an `apple-app-site-association` file on your domain
|
|
31
|
+
- **Android:** Host a `.well-known/assetlinks.json` file on your domain + add intent filters
|
|
32
|
+
|
|
33
|
+
**React Native integration:**
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
import { Linking } from "react-native";
|
|
37
|
+
import { DeepLinkRouter } from "@rajeev02/deeplink";
|
|
38
|
+
|
|
39
|
+
// Feed incoming URLs to the router
|
|
40
|
+
Linking.addEventListener("url", ({ url }) => router.handle(url));
|
|
41
|
+
|
|
42
|
+
// Handle cold start
|
|
43
|
+
const initialUrl = await Linking.getInitialURL();
|
|
44
|
+
if (initialUrl) router.handle(initialUrl);
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Platform Support
|
|
48
|
+
|
|
49
|
+
| Platform | Engine | Status |
|
|
50
|
+
| ---------- | ---------- | ------ |
|
|
51
|
+
| iOS 16+ | TypeScript | ✅ |
|
|
52
|
+
| Android 7+ | TypeScript | ✅ |
|
|
53
|
+
| Web | TypeScript | ✅ |
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm install @rajeev02/deeplink
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Peer Dependencies
|
|
62
|
+
|
|
63
|
+
- `react` >= 18.3.0
|
|
64
|
+
- `react-native` >= 0.84.0 _(optional)_
|
|
65
|
+
|
|
66
|
+
## Quick Start
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
import { DeepLinkRouter, getCommonRoutes } from "@rajeev02/deeplink";
|
|
70
|
+
|
|
71
|
+
// Create router with 19 pre-built routes
|
|
72
|
+
const router = new DeepLinkRouter({
|
|
73
|
+
scheme: "myapp://",
|
|
74
|
+
domains: ["myapp.com", "myapp.page.link"],
|
|
75
|
+
routes: getCommonRoutes(),
|
|
76
|
+
onNoMatch: (url) => console.warn("No route for:", url),
|
|
77
|
+
onAttribution: (data) => analytics.track("deeplink", data),
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
// Mark app ready (processes any deferred links from cold start)
|
|
81
|
+
router.setReady();
|
|
82
|
+
|
|
83
|
+
// Handle incoming URL
|
|
84
|
+
const match = router.handle("myapp://product/123?utm_source=email");
|
|
85
|
+
if (match) {
|
|
86
|
+
console.log(match.route.screen); // → "ProductScreen"
|
|
87
|
+
console.log(match.params.id); // → "123"
|
|
88
|
+
console.log(match.query); // → { utm_source: "email" }
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// Generate links
|
|
92
|
+
const appLink = router.generate("/product/:id", { id: "456" });
|
|
93
|
+
// → "myapp://product/456"
|
|
94
|
+
|
|
95
|
+
const webLink = router.generateUniversalLink("/product/:id", { id: "456" });
|
|
96
|
+
// → "https://myapp.com/product/456"
|
|
97
|
+
|
|
98
|
+
// Add custom routes
|
|
99
|
+
router.addRoute({
|
|
100
|
+
pattern: "/store/:storeId/menu",
|
|
101
|
+
screen: "StoreMenuScreen",
|
|
102
|
+
authRequired: false,
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Pre-Built Routes
|
|
107
|
+
|
|
108
|
+
`getCommonRoutes()` returns 19 routes for common super-app screens:
|
|
109
|
+
|
|
110
|
+
| Pattern | Screen | Auth |
|
|
111
|
+
| ------------------------ | ------------------- | ---- |
|
|
112
|
+
| `/home` | HomeScreen | No |
|
|
113
|
+
| `/product/:id` | ProductScreen | No |
|
|
114
|
+
| `/category/:id` | CategoryScreen | No |
|
|
115
|
+
| `/search` | SearchScreen | No |
|
|
116
|
+
| `/cart` | CartScreen | Yes |
|
|
117
|
+
| `/checkout` | CheckoutScreen | Yes |
|
|
118
|
+
| `/order/:orderId` | OrderDetailScreen | Yes |
|
|
119
|
+
| `/order/:orderId/track` | OrderTrackScreen | Yes |
|
|
120
|
+
| `/payment/:txnId/status` | PaymentStatusScreen | Yes |
|
|
121
|
+
| `/profile` | ProfileScreen | Yes |
|
|
122
|
+
| `/profile/edit` | EditProfileScreen | Yes |
|
|
123
|
+
| `/settings` | SettingsScreen | Yes |
|
|
124
|
+
| `/chat/:roomId` | ChatScreen | Yes |
|
|
125
|
+
| `/offer/:offerId` | OfferScreen | No |
|
|
126
|
+
| `/refer` | ReferralScreen | Yes |
|
|
127
|
+
| `/scan` | ScanScreen | Yes |
|
|
128
|
+
| `/pay/:vpa` | PayScreen | Yes |
|
|
129
|
+
| `/kyc` | KycScreen | Yes |
|
|
130
|
+
| `/support` | SupportScreen | No |
|
|
131
|
+
|
|
132
|
+
## API Reference
|
|
133
|
+
|
|
134
|
+
### `DeepLinkRouter`
|
|
135
|
+
|
|
136
|
+
| Method | Returns | Description |
|
|
137
|
+
| ----------------------------------------- | -------------------------- | ------------------------- |
|
|
138
|
+
| `handle(url)` | `DeepLinkMatch \| null` | Match URL, extract params |
|
|
139
|
+
| `generate(pattern, params?)` | `string` | Generate app-scheme link |
|
|
140
|
+
| `generateUniversalLink(pattern, params?)` | `string` | Generate HTTPS link |
|
|
141
|
+
| `setReady()` | `void` | Process deferred links |
|
|
142
|
+
| `getDeferredLink()` | `DeferredDeepLink \| null` | Get cold-start link |
|
|
143
|
+
| `addRoute(route)` | `void` | Register a route |
|
|
144
|
+
| `getRoutes()` | `DeepLinkRoute[]` | List all routes |
|
|
145
|
+
|
|
146
|
+
## Full Documentation
|
|
147
|
+
|
|
148
|
+
📖 [Complete API docs with types and configuration](https://github.com/Rajeev02/rajeev-sdk/blob/main/docs/usage/DEEPLINK.md)
|
|
149
|
+
|
|
150
|
+
## License
|
|
151
|
+
|
|
152
|
+
MIT © 2026 [Rajeev Kumar Joshi](https://rajeev02.github.io)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rajeev02/deeplink",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Universal deep linking — app links, universal links, deferred deep links, route matching, attribution",
|
|
5
5
|
"main": "lib/index.js",
|
|
6
6
|
"author": "Rajeev Kumar Joshi <rajeevjoshi91@gmail.com> (https://rajeev02.github.io)",
|