expo-widgets

To enable native widgets, add @bittingz/expo-widgets to your plugins array in app.config.{js/ts} or app.json. You can configure iOS and Android separately. If you only support one platform, you can omit the other.

[
    "@bittingz/expo-widgets",
    {
        ios: {
            src: "./src/my/path/to/ios/widgets/folder",
            devTeamId: "your apple dev team ID",
            mode: "production",                        
            moduleDependencies: [],
            useLiveActivities: false,
            frequentUpdates: false,
            entitlements: {
                "any xcode entitlement the widget needs": "entitlement value"
            }
        },
        android: {
            src: "./src/my/path/to/android/widgets/folder",
            widgets: [
                {
                    "name": "MyWidgetProvider",
                    "resourceName": "@xml/my_widget_info"
                }
            ],
            distPlaceholder: "optional.placeholder"
        }                      
    }
],

When using expo-widgets in a monorepo structure (where the package resides in a parent directory relative to the Expo project), you must configure metro.config.js to prevent dependency conflicts and ensure the bundler can locate the package and its dependencies.

Key configuration steps:

1. Exclude parent node_modules: Use config.resolver.blockList to prevent Metro from bundling react or react-native from the parent node_modules folder, which avoids version mismatch errors.
2. Set nodeModulesPaths: Explicitly include both the local ./node_modules and the parent ../node_modules in config.resolver.nodeModulesPaths.
3. Map extraNodeModules: Use config.resolver.extraNodeModules to map the package name @bittingz/expo-widgets to the parent directory ...
4. Configure watchFolders: Add the parent directory to config.watchFolders so Metro tracks changes in the package source.

const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');

const config = getDefaultConfig(__dirname);

// Prevent incompatible react/react-native versions from parent folder
config.resolver.blockList = [
  ...Array.from(config.resolver.blockList ?? []),
  new RegExp(path.resolve('..', 'node_modules', 'react')),
  new RegExp(path.resolve('..', 'node_modules', 'react-native')),
];

// Ensure Metro looks in both local and parent node_modules
config.resolver.nodeModulesPaths = [
  path.resolve(__dirname, './node_modules'),
  path.resolve(__dirname, '../node_modules'),
];

// Map the package to the parent directory
config.resolver.extraNodeModules = {
  '@bittingz/expo-widgets': '..',
};

// Watch the parent directory for changes
config.watchFolders = [path.resolve(__dirname, '..')];

module.exports = config;

When configuring iOS widgets, provide the following properties:

• src: The directory containing your widget native code.
• deploymentTarget: The deployment target for the app (defaults to 16.2 to support live activities).
• useLiveActivities: Boolean to enable live activities (SSupportsLiveActivities).
• frequentUpdates: Boolean to enable frequent live activity updates (NSSupportsLiveActivitiesFrequentUpdates).
• devTeamId: Your Apple developer team ID.
• targetName: (Optional) The target/extension name.
• xcode: (Optional) An object to override Xcode project settings:
  • widgetBundleIdentifier: The bundle ID for the widget(s).
  • appGroupId: Optional app group ID override.
  • entitlements: Optional IOSEntitlements (a PlistObject).
  • configOverrides: A dictionary of attributeName: string to customize the Xcode configuration block.
  • appExtAPI: Boolean to control the Podfile APP_EXTENSION_API_ONLY setting.
• moduleDependencies: (Optional) A collection of relative file paths to files your module needs (e.g., shared models).
• widgetExtPlugins: (Optional) An array of ConfigPlugins to run after the widget extension is created.

type WithExpoIOSWidgetsProps = {
    src: string;
    deploymentTarget: string;
    useLiveActivities: boolean;
    frequentUpdates: boolean;
    devTeamId: string;
    targetName?: string;
    xcode?: {
        widgetBundleIdentifier?: string;
        appGroupId?: string;
        entitlements?: IOSEntitlements;
        configOverrides?: { [ attributeName: string ]: string };
        appExtAPI?: boolean;
    };
    moduleDependencies: string[];
    widgetExtPlugins: ConfigPlugin<any>[];
}

Use the withEntitlements config plugin to manage iOS widget entitlements, specifically for setting up App Groups and Push Notification environments. This plugin automatically creates a .entitlements file within your widget project directory.

To use this, you must provide options containing the mode ('development' or 'production') and optionally custom xcode.entitlements.

Requirements:

• You must provide an appGroupId either via options.xcode.appGroupId or by ensuring ios.bundleIdentifier is set in your Expo config (the plugin will attempt to generate one using the pattern group.${bundleIdentifier}.expowidgets).
• If ios.bundleIdentifier is missing and no appGroupId is provided, the plugin will throw an error.

// Example usage within an Expo Config Plugin context
withEntitlements(config, {
  mode: 'development',
  xcode: {
    appGroupId: 'group.com.your.app.id',
    entitlements: {
      // custom entitlements here
    }
  }
});