Catalog
expo/expo-app-clip

expo

expo-app-clip

Add an iOS App Clip target to an Expo app. Use when the user mentions App Clip, AASA, apple-app-site-association, appclips, smart app banner, or wants to ship a lightweight iOS Clip invoked from a URL alongside their parent app.

NewUpdated Nov 15, 2026

Add an App Clip to an Expo App

Requirements. Adding the App Clip target is open source. Shipping one requires an Apple Developer Program membership and App Store review, and the AASA file must be served over HTTPS on your domain (any HTTPS host works; EAS Hosting is one option). Building via EAS Build or bunx testflight uses your EAS plan's build minutes. See https://expo.dev/pricing and https://developer.apple.com/app-clips/.

Adds an iOS App Clip target to an Expo project. The Clip lives in targets/clip/, ships alongside the parent app, and is invoked from a URL on the app's domain via an Apple App Site Association (AASA) file.

The parent app's bundle ID becomes com.<username>.<app-name> and the Clip's is automatically derived as <parent>.clip (e.g. com.bacon.may20.clip).

1. Set bundleIdentifier and appleTeamId

bun create target warns if these are missing. Add to app.json:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.<username>.<app-name>",
      "appleTeamId": "XX57RJ5UTD"
    }
  }
}

2. Add the App Clip target

bun create target clip

This installs @bacons/apple-targets, adds it to the plugins array in app.json, and writes:

  • targets/clip/expo-target.config.js — the target's config plugin
  • targets/clip/Info.plist — Clip Info.plist
  • targets/clip/AppDelegate.swift, Assets.xcassets, etc.

Pick a good icon or reuse the existing one defined in the app — check it with bunx expo config under the icon or ios.icon key.

3. Wire up associated domains

The parent app and the Clip each need the Associated Domains entitlement pointing at the domain that hosts the AASA file.

In app.json, add both applinks: (parent) and appclips: (Clip invocation) entries:

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:may20.expo.app",
        "appclips:may20.expo.app"
      ]
    }
  }
}

In targets/clip/expo-target.config.js, declare the Clip's entitlement:

/** @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} */
module.exports = (config) => ({
  type: "clip",
  icon: "https://github.com/expo.png",
  entitlements: {
    "com.apple.developer.associated-domains": ["appclips:may20.expo.app"],
  },
});

If you skip this, expo prebuild will print: Apple App Clip may require the associated domains entitlement but none were found.

4. Register bundle IDs and create the App Store entry

bunx setup-safari

This logs in to the Apple Developer account, registers com.bacon.may20, creates the App Store Connect entry, and prints:

  • A starter apple-app-site-association JSON
  • A <meta name="apple-itunes-app"> tag with the iTunes app id
  • Team ID, iTunes ID, and Bundle ID

5. Host the AASA file

App Clips are invoked when iOS fetches https://<your-domain>/.well-known/apple-app-site-association and finds a matching appclips entry.

mkdir -p public/.well-known
touch public/.well-known/apple-app-site-association

Paste the JSON setup-safari printed, but add an appclips block for the Clip's full app ID (<TeamID>.<ClipBundleID>). The output of setup-safari only covers the parent app:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["XX57RJ5UTD.com.bacon.may20"],
        "components": [{ "/": "*", "comment": "Matches all routes" }]
      }
    ]
  },
  "appclips": {
    "apps": ["XX57RJ5UTD.com.bacon.may20.clip"]
  },
  "activitycontinuation": {
    "apps": ["XX57RJ5UTD.com.bacon.may20"]
  },
  "webcredentials": {
    "apps": ["XX57RJ5UTD.com.bacon.may20"]
  }
}

Notes:

  • The file has no extension and no Content-Type requirements beyond being served as-is. Expo Router static export serves files in public/ verbatim.
  • The appclips block is what lets a URL on the domain launch the Clip.
  • webcredentials is used for sharing credentials between the website, parent app, and the App Clip.
  • activitycontinuation is optional and used for sharing the link between mobile and desktop. Must be used with Head from expo-router — see https://docs.expo.dev/router/advanced/apple-handoff/
  • Notation and route-disabling details: https://sosumi.ai/documentation/xcode/supporting-associated-domains

6. Add the Smart App Banner meta tag

Create src/app/+html.tsx (Expo Router's HTML shell) and add the tag from setup-safari. Create the versioned template if it doesn't exist:

bunx expo customize src/app/+html.tsx

Add the meta tag to the <head>:

import { ScrollViewStyleReset } from "expo-router/html";

export default function Root({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <meta name="apple-itunes-app" content="app-id=6771566491" />
        <ScrollViewStyleReset />
      </head>
      <body>{children}</body>
    </html>
  );
}

To make the website show the App Clip card instead of the install card, use:

<meta
  name="apple-itunes-app"
  content="app-id=6771566491, app-clip-bundle-id=com.bacon.may20.clip, app-clip-display=card"
/>

7. Deploy the website

The AASA file must be live before iOS will trust the association. Use EAS Hosting:

bunx expo export -p web
eas deploy --prod

This publishes the site (including /.well-known/apple-app-site-association) at https://<slug>.expo.app. Verify:

curl https://may20.expo.app/.well-known/apple-app-site-association

8. Mirror permissions

Inspect the parent app's permissions after prebuild:

npx expo config --type introspect

Look at the infoPlist object — mirror the permission keys in the App Clip's Info.plist so matching APIs can be used from the Clip.

Set deploymentTarget: "17.6" in the Clip's target config — App Clips have a higher minimum size limit in iOS 17.6.

If the app uses push notifications or location services, add to the App Clip's Info.plist to request the necessary permissions:

<key>NSAppClip</key>
<dict>
  <key>NSAppClipRequestEphemeralUserNotification</key>
  <false/>
  <key>NSAppClipRequestLocationConfirmation</key>
  <true/>
</dict>

9. Build and submit to TestFlight

bunx testflight

This will:

  1. Generate an eas.json if missing.
  2. Set up credentials for both targets (parent + Clip). Each gets its own provisioning profile but can share a single Distribution Certificate.
  3. Sync capabilities — note Enabled: Associated Domains for the Clip target.
  4. Build, upload, and schedule a TestFlight submission.

10. Configure App Clip metadata

Pull existing App Store metadata to local:

eas metadata:pull

Add apple.appClip to store.config.json. Up to 3 invocation URLs can launch the Clip from a web page:

{
  "configVersion": 0,
  "apple": {
    "appClip": {
      "defaultExperience": {
        "action": "PLAY",
        "releaseWithAppStoreVersion": true,
        "reviewDetail": {
          "invocationUrls": ["https://may20.expo.app/", null, null]
        },
        "info": {
          "en-US": {
            "subtitle": "Instantly native with Expo",
            "headerImage": "store/apple/app-clip/en-US/asc-app-clip.png"
          }
        }
      }
    }
  }
}

The headerImage must be a 1800x1200 PNG with no opacity.

Push back to the store:

eas metadata:push

Apple's recommended App Clip metadata guidelines: https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip

What you get

  • Parent app target: com.bacon.may20
  • App Clip target: com.bacon.may20.clip, lives in targets/clip/
  • AASA hosted at https://may20.expo.app/.well-known/apple-app-site-association
  • Smart App Banner meta tag on every web route
  • Every route linked to its native counterpart
  • TestFlight build of the parent app with the Clip embedded

Once Apple invokes the Clip from a URL on the domain, iOS opens targets/clip/'s entry point which loads the React Native app.

Native detection (optional)

To let JS detect when it's running inside an App Clip and present an install prompt for the full app, create a local Expo module (bunx create-expo-module --local) that exposes navigator.appClip.prompt().

See ./references/native-module.md for the Swift module, TypeScript interface, and usage.

References

  • ./references/native-module.md — Local Expo module to detect App Clip context and present the SKOverlay install prompt

Submitting Feedback

You can voluntarily report errors, misleading or outdated information in this skill, so Expo can improve it:

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-app-clip" --message "<actionable feedback>"

Use --category agent-cli for a problem with the agent CLI, and --category evals when an agent repeatedly fails at an Expo task. Run feedback --help for subjects and the data that the command sends. Each report goes to Expo with project and environment details. Show the user the message, and send it only if the user agrees. If you cannot ask the user, do not send it. Do not include secrets or personal data.

Files3
3 files · 3.7 KB

Select a file to preview

Overall Score

82/100

Grade

B

Good

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

82

Quality

85

Clarity

88

Completeness

76

Summary

This skill guides developers through adding an iOS App Clip target to an Expo project, covering bundle ID configuration, the App Clip target setup, associated domains, AASA file hosting, Smart App Banner integration, TestFlight submission, and App Clip metadata configuration. It includes a reference for building a native Expo module to detect and handle App Clip context.

Static Analysis Findings

1 finding

Patterns detected by deterministic static analysis before AI scoring. Hover over any finding code for detailed information and remediation guidance.

Network Access
SEC-060Outbound Network Request

Outbound network request (curl/wget/fetch)

SKILL.mdcurl https://

Detected Capabilities

file writedirectory creationshell command executionhttp request (curl verification)metadata file generationjson configuration

Trigger Keywords

Phrases that agents use to match this skill to user intent.

app clipadd app clipaasa fileassociated domainsapp clip manifestios app clipsmart app banner

Risk Signals

INFO

SEC-060: Outbound network request (curl to verify AASA file)

SKILL.md:122
INFO

HTTP domain references (developer.apple.com, expo.dev, sosumi.ai, github.com, may20.expo.app)

SKILL.md, multiple locations

Referenced Domains

External domains referenced in skill content, detected by static analysis.

developer.apple.comdocs.expo.devexpo.devgithub.commay20.expo.appsosumi.ai

Use Cases

  • Add iOS App Clip target to Expo app
  • Configure associated domains and AASA file
  • Set up App Clip for URL-based invocation
  • Submit App Clip to TestFlight and App Store
  • Detect App Clip context and show install prompt
  • Configure App Clip metadata and invocation URLs
  • Wire smart app banners for native integration

Quality Notes

  • Well-structured step-by-step guide with clear prerequisites and requirements
  • Includes full JSON examples and code snippets for all configuration steps
  • References external documentation (Apple Dev, Expo docs, sosumi.ai) appropriately
  • Covers both parent app and Clip target coordination clearly
  • Includes optional native module for App Clip detection with complete Swift and TypeScript implementations
  • Good edge case coverage: permission mirroring, deployment target considerations, metadata guidelines
  • Clear explanation of AASA file requirements and role in URL-based Clip invocation
  • Includes feedback mechanism for users to report issues
  • Minor: Could benefit from troubleshooting section for common issues like missing entitlements
  • All referenced domains are legitimate (Apple, Expo, GitHub)
Model: claude-haiku-4-5-20251001Analyzed: Nov 15, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

  1. v2.4

    Content updated

    ✦ AIFeedback submission guidance shifts from mandatory reporting requirements to voluntary submission with clarified categories and privacy protections.

    2026-11-15

    LATEST
  2. v2.3

    Content updated

    ✦ AIUpdates feedback command syntax: replaces positional argument with --message flag and adds character limit requirement and new reporting guidance.

    2026-11-13

    View This Version
  3. v2.2

    Content updated

    ✦ AIUpdates feedback submission command from submit-expo-feedback to @expo/agent-cli.

    2026-10-23

    View This Version
  4. v2.1

    Content updated

    ✦ AIRewrites feedback submission guidance for failure cases: replace expo-skill-feedback evaluation flow with direct report via --category evals.

    2026-10-22

    View This Version
  5. v2.0

    Contract changed: description

    ✦ AIActivation scope narrowed: removed OSS Framework classifier from skill description.

    triggering2026-10-03

    View This Version
  6. v1.1

    Content updated

    ✦ AIAdds feedback submission guidance at end of skill.

    2026-09-09

    View This Version
  7. v1.0

    2026-07-11

    View This VersionInitial version

Use expo/expo-app-clip in your dev environment

Command Palette

Search for a command to run...