expo-icp-app-connect-helpers

This project provides helpers for invoking another application from the frontend and receiving result via deep link in Internet Computer (ICP) applications.

Installation

1npm install expo-icp-app-connect-helpers

Peer Dependencies

This package requires the following peer dependencies:

• canister-manager
• expo-icp-frontend-helpers

These dependencies are required for managing Internet Computer canisters and handling deep links in Expo applications. Make sure to install them in your project:

1npm install canister-manager expo-icp-frontend-helpers

Usage

Building App Connection URL

1import { buildAppConnectionURL } from 'expo-icp-app-connect-helpers';
2
3const url = buildAppConnectionURL({
4  dfxNetwork: 'local',
5  localIPAddress: '192.168.1.210',
6  targetCanisterId: 'rrkah-fqaaa-aaaaa-aaaaq-cai',
7  pathname: '/dashboard', // Optional, defaults to '/'
8});
9// Returns: URL object with pathname '/dashboard'

Building App Connection Parameters

1import { buildAppConnectionParams } from 'expo-icp-app-connect-helpers';
2
3const params = buildAppConnectionParams({
4  deepLink: 'exp://192.168.1.210:8081',
5  frontendCanisterId: 'rrkah-fqaaa-aaaaa-aaaaq-cai',
6  easDeepLinkType: undefined,
7  pathname: '/dashboard',
8});
9// Returns: { deepLinkType: 'expo-go', pathname: '/dashboard' }

Building Internet Identity URL

1import { buildInternetIdentityURL } from 'expo-icp-app-connect-helpers';
2
3const url = buildInternetIdentityURL({
4  dfxNetwork: 'local',
5  localIPAddress: '192.168.1.210',
6  targetCanisterId: 'rrkah-fqaaa-aaaaa-aaaaq-cai',
7  internetIdentityPort: 24943, // Optional
8});
9// Returns: URL object for Internet Identity

API Reference

buildAppConnectionURL

Builds a URL for connecting to an Internet Computer application.

Parameters

Parameter	Type	Required	Description
dfxNetwork	string	Yes	The DFX network to connect to (e.g., 'local', 'ic')
localIPAddress	string	Yes	The local IP address of the replica
replicaPort	number	No	Optional port number for the replica
canisterPort	number	No	Optional port number for the canister
internetIdentityPort	number	No	Optional port number for Internet Identity
targetCanisterId	string	Yes	The ID of the target canister to connect to
pathname	string	No	Optional pathname to append to the URL (defaults to '/')

Returns

URL - A URL object for connecting to the application

buildAppConnectionParams

Builds connection parameters for deep linking to an Internet Computer application.

Parameters

Parameter	Type	Required	Description
deepLink	string	Yes	The deep link URL to be processed
frontendCanisterId	string	Yes	The ID of the frontend canister
easDeepLinkType	string | undefined	No	Optional EAS deep link type for Expo builds
pathname	string	Yes	The pathname to be used in the deep link

Returns

DeepLinkConnectionParams - The connection parameters with deep link type and pathname

parseDeepLinkConnectionParams

Parses deep link connection parameters from a URL query string.

Parameters

Parameter	Type	Required	Description
paramsStr	string	Yes	The URL query string to parse
requiredKeys	(keyof P)[]	No	Additional required keys to validate beyond the default ones

Returns

P - The parsed parameters, where P extends Required

Example

1// Parse with default required keys (sessionId, deepLinkType, and pathname)
2const params = parseDeepLinkConnectionParams(
3  'sessionId=abc123&deepLinkType=expo-go&pathname=/app',
4);
5
6// Parse with additional required keys
7const params = parseDeepLinkConnectionParams<
8  Required<DeepLinkConnectionParams> & { customKey: string }
9>(
10  'sessionId=abc123&deepLinkType=development&pathname=/app&customKey=value',
11  'customKey',
12);

buildInternetIdentityURL

Builds a URL for connecting to Internet Identity.

Parameters

Parameter	Type	Required	Description
dfxNetwork	string	Yes	The DFX network to connect to (e.g., 'local', 'ic')
localIPAddress	string	Yes	The local IP address of the replica
replicaPort	number	No	Optional port number for the replica
canisterPort	number	No	Optional port number for the canister
internetIdentityPort	number	No	Optional port number for Internet Identity
targetCanisterId	string	Yes	The ID of the target canister to connect to

Returns

URL - A URL object for connecting to Internet Identity

Development

1# Install dependencies
2npm install
3
4# Run tests
5npm test
6
7# Run tests with coverage
8npm run test:coverage
9
10# Build the package
11npm run build

License

ISC