Apple Targets plugin

> [!WARNING]
> This is highly experimental and not part of any official Expo workflow.

An experimental Expo Config Plugin that generates native Apple Targets like Widgets or App Clips, and links them outside the /ios directory. You can open Xcode and develop the targets inside the virtual expo:targets folder and the changes will be saved outside of the ios directory. This pattern enables building things that fall outside of the scope of React Native while still obtaining all the benefits of Continuous Native Generation.

🚀 How to use

> This plugin requires at least CocoaPods 1.16.2 (ruby 3.2.0), Xcode 16 (macOS 15 Sequoia), and Expo SDK +53.

1. Run npx create-target in your Expo project to generate an Apple target.
2. Select a target to generate, I recommend starting with a widget (e.g. npx create-target widget). This will generate the required widget files in the root /targets directory, install @bacons/apple-targets, and add the Expo Config Plugin to your project.
3. If you already know your Apple Team ID, then set it under the ios.appleTeamId property in your app.json. You can find this in Xcode under the Signing & Capabilities tab and set it later if needed.
4. Run npx expo prebuild -p ios --clean to generate the Xcode project.
5. You can now open your project in Xcode (xed ios) and develop the widget inside the expo:targets/ folder.
6. When you're ready to build, select the target in Xcode and build it.

$3

The root /targets folder is magic, each sub-directory should have a expo-target.config.js file that defines the target settings. When you run npx expo prebuild --clean, the plugin will generate the Xcode project and link the target files to the project. The plugin will also generate an Info.plist file if one doesn't exist.

The Config Plugin will link the subfolder (e.g. targets/widget) to Xcode, and all files inside of it will be part of the target. This means you can develop the target inside the expo:targets folder and the changes will be saved outside of the generated ios directory.

The root Info.plist file in each target directory is not managed and can be freely modified.

Any files in a top-level target/{name}/assets directory will be linked as resources of the target. This rule was added to support Safari Extensions.

$3

If the expo-target.config file defines an entitlements: {} object, then a generated.entitlements will be added. Avoid using this file directly, and instead update the expo-target.config.js file. If the entitlements object is not defined, you can manually add any top-level .entitlements file to the target directory—re-running npx expo prebuild will link this file to the target as the entitlements file. Only one top-level .entitlements file is supported per target.

Some targets have special entitlements behavior:

- App Clips (clip) automatically set the required com.apple.developer.parent-application-identifiers to $(AppIdentifierPrefix)${config.ios.bundleIdentifier}
- Targets that can utilize App Groups will automatically mirror the ios.entitlements['com.apple.security.application-groups'] array from the app.json if it's defined. This can be overwritten by specifying an entitlements['com.apple.security.application-groups'] array in the expo-target.config.js file.

$3

Any changes you make outside of the expo:targets directory in Xcode are subject to being overwritten by the next npx expo prebuild --clean. Check to see if the settings you want to toggle are available in the Info.plist or the expo-target.config.js file.
If you modify the expo-target.config.js or your root app.json, you will need to re-run npx expo prebuild --clean to sync the changes.

You can use the custom Prebuild template --template ./node_modules/@bacons/apple-targets/prebuild-blank.tgz to create a build without React Native, this can make development a bit faster since there's less to compile. This is an advanced technique for development NOT PRODUCTION and is not intended to be used with third-party Config Plugins.

Target config

The target config can be a expo-target.config.js, or expo-target.config.json file.

This file can have the following properties:

``js
/* @type {import('@bacons/apple-targets/app.plugin').Config} /
module.exports = {
type: "widget",

// Name of the target/product. Defaults to the directory name.
name: "my_widget",

// Optional override for CFBundleDisplayName. Defaults to name if not provided.
displayName: "My Widget",

// Generates colorset files for the target.
colors: {
// or "$accent": "red",
$accent: { color: "red", darkColor: "blue" },
},
icon: "../assets/icon.png",
// Can also be a URL
frameworks: [
// Frameworks with or without the .frameworks extension, these will be added to the target.
"SwiftUI",
],
entitlements: {
// Serialized entitlements. Useful for configuring with environment variables.
},
// Generates xcassets for the target.
images: {
thing: "../assets/thing.png",
},

// The iOS version fot the target. Defaults to 18.0
deploymentTarget: "15.1",

// Optional bundle identifier for the target. Will default to a sanitized version of the root project bundle id + target name.
// If the specified bundle identifier is prefixed with a dot (.), the bundle identifier will be appended to the main app's bundle identifier.
bundleIdentifier: ".mywidget",

// Should the release build export the JS bundle and embed. Intended for App Clips and Share Extensions where you may want to use React Native.
exportJs: false,
};
`

You can also return a function that accepts the Expo Config and returns a target function for syncing entitlements and other values:

`js
/* @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} /
module.exports = (config) => ({
type: "widget",
colors: {
$accent: "steelblue",
},
entitlements: {
// Use the same app groups:
"com.apple.security.application-groups":
config.ios.entitlements["com.apple.security.application-groups"],
// Or generate an app group:
"com.apple.security.application-groups": [
group.${config.ios.bundleIdentifier}.widget,
],
},
});
`

> ESM and TypeScript are not supported in the target config. Stick to require for sharing variables across targets.

Colors

There are certain values that are shared across targets. We use a predefined convention to map these values across targets.

| Name | Build Setting | Purpose |
| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| $accent | ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME | Sets the global accent color, in widgets this is used for the tint color of buttons when editing the widget. |
| $widgetBackground | ASSETCATALOG_COMPILER_WIDGET_BACKGROUND_COLOR_NAME | Sets the background color of the widget. |

CocoaPods

Adding a file pods.rb in the root of the repo will enable you to modify the target settings for the project.

The ruby module evaluates with global access to the property podfile_properties.

For example, the following is useful for enabling React Native in an App Clip target:

`rb
require File.join(File.dirname(node --print "require.resolve('react-native/package.json')"), "scripts/react_native_pods")

exclude = []
use_expo_modules!(exclude: exclude)

if ENV['EXPO_USE_COMMUNITY_AUTOLINKING'] == '1'
config_command = ['node', '-e', "process.argv=['', '', 'config'];require('@react-native-community/cli').run()"];
else
config_command = [
'node',
'--no-warnings',
'--eval',
'require(require.resolve(\'expo-modules-autolinking\', { paths: [require.resolve(\'expo/package.json\')] }))(process.argv.slice(1))',
'react-native-config',
'--json',
'--platform',
'ios'
]
end

config = use_native_modules!(config_command)

use_frameworks! :linkage => podfile_properties['ios.useFrameworks'].to_sym if podfile_properties['ios.useFrameworks']
use_frameworks! :linkage => ENV['USE_FRAMEWORKS'].to_sym if ENV['USE_FRAMEWORKS']

use_react_native!(
:path => config[:reactNativePath],
:hermes_enabled => podfile_properties['expo.jsEngine'] == nil || podfile_properties['expo.jsEngine'] == 'hermes',
# An absolute path to your application root.
:app_path => "#{Pod::Config.instance.installation_root}/..",
:privacy_file_aggregation_enabled => podfile_properties['apple.privacyManifestAggregationEnabled'] != 'false',
)
`

This block executes at the end of the Podfile in a block like:

`rb
target "target_dir_name" do
target_file
end
`

The name of the target must match the name of the target directory.

_shared

Some files are required to be linked to both your target and the main target. To support this, you can add a top-level _shared directory. Any file in this directory will be linked to both the main target and the sub-target. You'll need to re-run prebuild every time you add, rename, or remove a file in this directory.

You can additionally add a _shared directory inside of the root targets/_shared directory. This will link files to all targets in your project.

exportJs

The exportJs option should be used when the target uses React Native (App Clip, Share extension). It works by linking the main target's Bundle React Native code and images build phase to the target. This will ensure that production builds (Release) bundle the main JS entry file with Metro, and embed the bundle/assets for offline use.

To detect which target is being built, you can read the bundle identifier using expo-application.

Examples

$3

> I wrote a blog about this one and used it in production. Learn more: Expo x Apple Widgets.

`js
/* @type {import('@bacons/apple-targets/app.plugin').Config} /
module.exports = {
type: "widget",
icon: "../../icons/widget.png",
colors: {
// This color is referenced in the Info.plist
$widgetBackground: "#DB739C",

$accent: "#F09458",

// Optional: Add colors that can be used in SwiftUI.
gradient1: {
light: "#E4975D",
dark: "#3E72A0",
},
},
// Optional: Add images that can be used in SwiftUI.
images: {
valleys: "../../valleys.png",
},
// Optional: Add entitlements to the target, this one can be used to share data between the widget and the app.
entitlements: {
"com.apple.security.application-groups": ["group.bacon.data"],
},
};
`

$3

!IMG_C2C825ACC8C7-1

These show up in the share sheet. The icon should be transparent as it will be masked by the system.

`js
/* @type {import('@bacons/apple-targets/app.plugin').Config} /
module.exports = {
type: "action",
displayName: "Inspect Element",
icon: "./assets/icon.png",
colors: {
TouchBarBezel: "#DB739C",
},
};
`

Add a JavaScript file to assets/index.js:

`js
class Action {
/**
* extensionName: "com.bacon.2095.axun"
@param {} arguments: {completionFunction: () => unknown; extensionName: string; }
*/
run({ extensionName, completionFunction }) {
// Here, you can run code that modifies the document and/or prepares
// things to pass to your action's native code.

// We will not modify anything, but will pass the body's background
// style to the native code.
completionFunction({
/ /
});
}

finalize() {
// Runs after the native action code has completed.
}
}

window.ExtensionPreprocessingJS = new Action();
`

Ensure NSExtensionJavaScriptPreprocessingFile: "index" in the Info.plist.

$3

Populate the Spotlight search results with your app's content.

`js
/* @type {import('@bacons/apple-targets/app.plugin').Config} /
module.exports = {
type: "spotlight",
};
`

$3

Ideally, this would be generated automatically based on a fully qualified Xcode project, but for now it's a manual process. The currently supported types are based on static analysis of the most commonly used targets in the iOS App Store. I haven't tested all of these and they may not work.

| Type | Description |
| ----------------------- | ---------------------------------- |
| action | Share Action |
| app-intent | App Intent Extension |
| widget | Widget / Live Activity |
| watch | Watch App (with companion iOS App) |
| watch-widget | Widget for Watch App |
| clip | App Clip |
| safari | Safari Extension |
| share | Share Extension |
| notification-content | Notification Content Extension |
| notification-service | Notification Service Extension |
| intent | Siri Intent Extension |
| intent-ui | Siri Intent UI Extension |
| spotlight | Spotlight Index Extension |
| bg-download | Background Download Extension |
| quicklook-thumbnail | Quick Look Thumbnail Extension |
| location-push | Location Push Service Extension |
| credentials-provider | Credentials Provider Extension |
| account-auth | Account Authentication Extension |
| device-activity-monitor | Device Activity Monitor Extension |

Code Signing

The codesigning is theoretically handled entirely by EAS Build. This plugin will add the requisite entitlements for target signing to work. I've only tested this end-to-end with my Pillar Valley Widget.

You can also manually sign all sub-targets if you want, I'll light a candle for you.

> I haven't gotten App Clip codesigning to be fully automated yet. PRs welcome.

Building Widgets

I've written a blog post about building widgets with this plugin: Expo x Apple Widgets.

If you experience issues building widgets, it might be because React Native is shipped uncompiled which makes the build complexity much higher. This often leads to issues with the Swift compiler and SwiftUI previews.

Some workarounds:

- Clear the SwiftUI previews cache: xcrun simctl --set previews delete all
- Prebuild without React Native: npx expo prebuild --template ./node_modules/@bacons/apple-targets/prebuild-blank.tgz --clean
- If the widget doesn't show on the home screen when building the app, use iOS 18. You can long press the app icon and select the widget display options to transform the app icon into the widget.

Sharing data between targets

To share values between the app and the target, you must use App Groups and NSUserDefaults. I've added a native module to make the React Native API a bit easier.

$3

Start by defining an App Group, a good default is group.. App Groups can be used across apps so you may want something more generic or less generic if you plan on having multiple extensions.

First, define your main App Group entitlement in your app.json:

`json
{
"expo": {
"ios": {
"entitlements": {
"com.apple.security.application-groups": ["group.bacon.data"]
}
},
"plugins": ["@bacons/apple-targets"]
}
}
`

Second, define the same App Group in your target's expo-target.config.js:

`js
/* @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} /
module.exports = (config) => ({
type: "widget",
entitlements: {
// Use the same app groups:
"com.apple.security.application-groups":
config.ios.entitlements["com.apple.security.application-groups"],
},
});
`

Now you can prebuild to generate the entitlements. You may need to create an EAS Build or open Xcode to sync the entitlements.

$3

To define shared data, we'll use a native module (ExtensionStorage) that interacts with NSUserDefaults.

Somewhere in your Expo app, you can set a value:

`js
import { ExtensionStorage } from "@bacons/apple-targets";

// Create a storage object with the App Group.
const storage = new ExtensionStorage(
// Your app group identifier. Should match the values in the app.json and expo-target.config.json.
"group.bacon.data"
);

// Then you can set data:
storage.set("myKey", "myValue");

// Finally, you can reload the widget:
ExtensionStorage.reloadWidget();
`

ExtensionStorage has the following API:

- set(key: string, value: string | number | Record | Array> | undefined): void - Sets a value in the shared storage for a given key. Setting undefined will remove the key.
- ExtensionStorage.reloadWidget(name?: string): void - A static method for reloading the widget. Behind the scenes, this calls WidgetCenter.shared.reloadAllTimelines(). If given a name, it will reload a specific widget using WidgetCenter.shared.reloadTimelines(ofKind: timeline).
- ExtensionStorage.reloadControls(name?: string): void - A static method for reloading the controls. Behind the scenes, this calls ControlCenter.shared.reloadAllControls(): void. If given a name, it will reload a specific widget using ControlCenter.shared.reloadControls(ofKind?: string): void.
- remove(key: string): void - A method for removing the key from the shared storage.
- get(key: string): string | null - A static method for getting the value from the shared storage.

$3

Assuming this is done using Swift code, you'll access data using NSUserDefaults directly. Here's an example of how you might access the data in a widget:

`swift
let defaults = UserDefaults(suiteName:
// Use the App Group from earlier.
"group.bacon.data"
)
// Access the value you set:
let index = defaults?.string(forKey: "myKey")
`

$3

For more advanced uses, I recommend the following resources:

- Updating widgets when the app is in the background: Keeping A Widget Up-to-Date.

Xcode parsing

This plugin makes use of my proprietary Xcode parsing library, @bacons/xcode. It's mostly typed, very untested, and possibly full of bugs––however, it's still 10x nicer than the alternative.

Control widgets

!Simulator Screenshot - iPhone 16 - 2025-01-26 at 15 57 44

Control widgets are a type of widget that appears in the control center, Siri suggestions, the lock screen, and Shortcuts.

Generally, you'll want to add control widgets to a widget target, but they can be added to any target really.

You can add multiple intents, they should be in the [target]/_shared/*.swift folder so they can be added to the main target as well as the widget target, this is required to make them work correctly.

The following is an example of a control widget that launches a universal link for my app.

`swift
// targets/widget/_shared/intents.swift

import AppIntents
import SwiftUI
import WidgetKit

// TODO: These must be added to the WidgetBundle manually. They need to be linked outside of the _shared folder.
// @main
// struct exportWidgets: WidgetBundle {
// var body: some Widget {
// widgetControl0()
// widgetControl1()
// }
// }

@available(iOS 18.0, *)
struct widgetControl0: ControlWidget {
// Unique ID for the control.
static let kind: String = "com.bacon.clipdemo.0"
var body: some ControlWidgetConfiguration {
StaticControlConfiguration(kind: Self.kind) {
ControlWidgetButton(action: OpenAppIntent0()) {
// You can also use a custom image but it must be an SF Symbol.
Label("App Settings", systemImage: "star")
}
}
// This is the configuration for the widget.
.displayName("Launch Settings")
.description("A control that launches the app settings.")
}
}

// This must be in both targets when openAppWhenRun = true. We can do that by adding it to the _shared folder.
// https://developer.apple.com/forums/thread/763851
@available(iOS 18.0, *)
struct OpenAppIntent0: ControlConfigurationIntent {
static let title: LocalizedStringResource = "Launch Settings"
static let description = IntentDescription(stringLiteral: "A control that launches the app settings.")
static let isDiscoverable = true
static let openAppWhenRun: Bool = true

@MainActor
func perform() async throws -> some IntentResult & OpensIntent {
// Here's the URL we want to launch. It can be any URL but it should be a universal link for your app.
return .result(opensIntent: OpenURLIntent(URL(string: "https://pillarvalley.expo.app/settings")!))
}
}
`

You should copy the intents into your main WidgetBundle struct.

Reloading Controls from Your App

Changes in your app’s state may affect control displays. You can request a reload of specific controls or all controls using

`js
ExtensionStorage.reloadControls();
`

Custom images can be used but they must be SF Symbols, you can use a tool like Create Custom Symbols to do this. Then simply add to the Assets.xcassets folder and reference it in the Label.

You can do a lot of things with Control Widgets like launching a custom UI instead of opening the app. This plugin should allow for most of these things to work.

App Clips

!IMG_6BC9D9534F1D-1

App Clips leverage the true power of Expo Router, enabling you to link a website and native app to just instantly open the native app on iOS. They're pretty hard to get working though.

Here are a few notes from my experience building https://pillarvalley.expo.app (open on iOS to test).

Build the app first, then the website. You can always instantly update the website if it's wrong. This includes the AASA, and metadata.

You may need this RN patch to get your project working, otherwise it'll crash when launched from Test Flight. Alternatively, you can add App Clip experiences in App Store Connect and it'll launch as expected.

After running prebuild, open the project in Xcode and navigate to the signing tab for each target, this'll ensure the first version of codesigning is absolutely correct. We'll need to adjust EAS Build to ensure it can do this too.

Ensure your App Clip does not have expo-updates installed, otherwise it'll fail to build with some cryptic error about React missing in the AppDelegate.

Ensure all the build numbers are the same across the CURRENT_PROJECT_VERSION and CFBundleVersion (Info.plist) otherwise the app will fail to build.

Ensure you add a public/.well-known/apple-app-site-association file to your website and deploy it to the web (eas deploy --prod). Here's an example.

The value will be .:

`
{
"appclips": {
"apps": ["QQ57RJ5UTD.com.evanbacon.pillarvalley.clip"]
}
}
`

Add the website URL to your App Clip entitlements (not the main entitlements). Here's an example with https://pillarvalley.expo.app:

`xml
com.apple.developer.associated-domains

appclips:pillarvalley.expo.app

`

If this isn't done, then your App Clip will only be able to be launched from the default App Store URL: https://appclip.apple.com/id?p=com.evanbacon.pillarvalley.clip (where your App Clip bundle ID will be the ID in the URL).

You should handle redirection from this default URL too with a app/+native-intent.ts file:

`ts
export function redirectSystemPath({ path }: { path: string }): string {
try {
// Handle App Clip default page redirection.
// If path matches https://appclip.apple.com/id?p=com.evanbacon.pillarvalley.clip (with any query parameters), then redirect to / path.
const url = new URL(path);
if (url.hostname === "appclip.apple.com") {
// Redirect to the root path and make the original URL available as a query parameter (optional).
return "/?ref=" + encodeURIComponent(path);
}
return path;
} catch {
return path;
}
}
`

You should use expo-linking to get URLs related to the App Clip as the upstream React Native Linking has some issues handling App Clips.

When you publish an App Clip, the binary will take about 5 minutes to show up in the App Store (after it's approved) but the App Clip will take more like 25 minutes to show up in your website.

You also need to add some meta tags to your website. These need to run fast so I recommend putting them in your app/+html.tsx file:

`js
name="apple-itunes-app"
content={
"app-id=1336398804, app-clip-bundle-id=com.evanbacon.pillarvalley.clip, app-clip-display=card"
}
/>
`

You should also add the og:image property using expo-router/head. Learn more. It seems like an absolute path to a png image that is 1200×630 in dimensions (based on this).

`js

{/ Required for app clips: /}
{/ https://developer.apple.com/documentation/appclip/supporting-invocations-from-your-website-and-the-messages-app /}


`

You also need a 1800x1200` image for the App Store Connect image preview, so make both of these images around the same time.

Launch App Clips from Test Flight to test deep linking. It doesn't seem like there's any reasonable way to test launching from your website in development. I got this to work once by setting up a local experience in my app's "Settings > Developer" screen, then installing the app, opening the website, deleting the app, then installing the App Clip without the app. You'll mostly need to go with God on this one.

You can generate codes using the CLI tool download here.