Skip to content
Slingshot

Overview

@lastshotlabs/slingshot-deep-links publishes the well-known files and browser fallback routes needed for iOS universal links and Android app links. It is a small infrastructure plugin: no entities, no auth coupling, and no hidden state beyond the compiled route config it publishes in plugin state.

When To Use It

Section titled “When To Use It”

Use this package when your app needs:

  • /.well-known/apple-app-site-association for iOS universal-link ownership
  • /.well-known/assetlinks.json for Android app-link ownership
  • browser fallback redirects such as /share/* to a canonical web route

Do not use it as a general redirect framework. Its job is limited to native deep-link ownership and fallback handling.

Minimum Setup

Section titled “Minimum Setup”

At least one of these config sections is required:

  • apple
  • android
  • fallbackRedirects

If you configure fallbackRedirects, you must also configure fallbackBaseUrl. The base URL must use https:// and must not have a trailing slash.

The plugin has no declared dependencies, so it can be registered anywhere in the plugin list.

What You Get

Section titled “What You Get”

The plugin wires three surfaces:

  • GET /.well-known/apple-app-site-association when Apple config is present
  • GET /.well-known/assetlinks.json when Android config is present
  • configured browser fallback GET routes for wildcard sources such as /share/*

It also:

  • precompiles the AASA and assetlinks payloads once at plugin construction time
  • marks the two well-known routes as public paths so auth middleware skips them automatically
  • warns during setupPost if another plugin already owns a colliding path

Common Customization

Section titled “Common Customization”

The main config decisions are:

  • apple: one app or an array of app targets, each with teamId, bundleId, and allowed paths
  • android: one package target with packageName and certificate fingerprints
  • fallbackRedirects: wildcard source-to-target mappings
  • fallbackBaseUrl: canonical HTTPS web origin used when native handling is unavailable

If you need to change behavior, start in:

  • src/config.ts for validation and normalization rules
  • src/routes.ts for well-known route registration and fallback redirects
  • src/fallback.ts for wildcard expansion logic

Gotchas

Section titled “Gotchas”
  • The config fails validation unless at least one of apple, android, or fallbackRedirects is provided.
  • Fallback source patterns must end in *, and target patterns cannot contain *.
  • The fallback routes issue 302 redirects. They are for browser fallback behavior, not permanent SEO canonicalization.
  • Path collisions are warnings, not silent overrides. If another plugin owns the same route, fix the app-level route plan rather than relying on registration order.

Key Files

Section titled “Key Files”
  • src/index.ts
  • src/config.ts
  • src/plugin.ts
  • src/routes.ts
  • src/fallback.ts
  • src/aasa.ts
  • src/assetlinks.ts