Apple Targets

Apple Extension Target Skills Reference

This directory contains comprehensive skill documents for all supported Apple extension and target types. Each skill document provides everything an AI agent needs to understand, implement, and troubleshoot a specific Apple extension type, including:

• Apple documentation links and WWDC session references
• Runtime behavior and lifecycle explanation
• Real-world use cases and implementation patterns
• Production-ready Swift code examples
• Platform availability and version requirements
• Common gotchas and debugging tips

Installing This Skill

Install this skill into your coding agent (Claude Code, Cursor, Codex, etc.) with npx skills:

npx skills add EvanBacon/expo-apple-targets/tree/main/skills/apple-targets

The CLI auto-detects which agents you have installed and copies SKILL.md (plus the supporting reference docs in this directory) into the agent's skills directory (e.g. .claude/skills/ or .agents/skills/). Once installed, the agent loads this guidance automatically whenever you ask it to build an Apple extension or target.

How to Use These Skills

For AI Agents:

1. When a user asks about a specific extension type (e.g., "How do I build a widget?" or "I need to add a share extension"), read the corresponding skill document to get complete implementation guidance.

2. When planning a feature that might require an extension (e.g., "Add home screen presence" → read widget.md), consult the skill document to understand requirements and constraints.

3. When debugging extension issues, refer to the "Gotchas" section of the relevant skill document — these capture common pitfalls from Apple Developer Forums and real-world experience.

4. When uncertain which extension type fits a use case, scan the "Use Cases" sections across related skills to find the best match.

Structure of Each Skill Document:

Every skill document follows the template defined in _template.md:

• Frontmatter: Title, one-line description, minimum OS version
• Apple Documentation: Official reference links
• WWDC History: Session links showing evolution of the feature
• What It Does: Step-by-step runtime behavior
• Use Cases: Real-world scenarios organized by industry/app type
• Key Classes: Table of essential framework types
• Implementation: Production-ready Swift code with inline comments
• Using with @bacons/apple-targets: Setup instructions for this plugin
• Platform Availability: OS version matrix
• Gotchas: Common mistakes, memory limits, and silent failure modes

Skills by Category

User Interface Extensions

Notifications

Siri & Intents

Networking & VPN

File Management

Communication & Telephony

Content & Media

Education & Screen Time

Authentication & Security

Location & Background Services

Smart Home & Matter

Printing

Search & Indexing

Collaboration & Conferencing

Apple Watch

Target Types vs. Extensions

Application Targets (not extensions):

• App Clip (clip) — uses product type com.apple.product-type.application.on-demand-install-capable
• watchOS App (watch) — uses product type com.apple.product-type.application

These are full applications with their own Info.plist, app icons, and lifecycle. They do not use NSExtensionPointIdentifier.

All other types are app extensions that use product type com.apple.product-type.app-extension and declare an extension point identifier in their Info.plist.

Quick Reference: Common Use Cases

Creating a New Extension with @bacons/apple-targets

Every skill document includes a "Using with @bacons/apple-targets" section with the three-step setup:

# 1. Run the CLI to scaffold the extension
bunx create-target <type>

# 2. Ensure the plugin is in app.json
{
  "expo": {
    "plugins": [["@bacons/apple-targets"]]
  }
}

# 3. Generate the native project
npx expo prebuild --clean

The <type> parameter corresponds to the extension type slug shown in each skill document's title (e.g., widget, share, clip, notification-service).

When to Run Prebuild

Because target source files live outside the /ios directory and are linked into the Xcode project (not copied), Swift code changes are automatically synchronized. You don't need to re-run prebuild when editing code.

• Run prebuild --clean when:

  • Initial setup after creating a new target
  • Changing expo-target.config.js (icon, colors, entitlements, bundle ID, frameworks)
  • Changing app.json plugin configuration
  • Adding or removing targets
  • Xcode project corruption or mysterious build failures

• Run prebuild (without --clean) when:

  • You need to regenerate the project but want to preserve manual Xcode modifications
  • Updating the plugin version with minor project changes

• No prebuild needed for:

  • Editing Swift code in targets/<name>/ directories — files are linked, changes appear immediately in Xcode
  • Adding/modifying Swift files within an existing target
  • Most day-to-day development work on target implementations

This architecture allows you to iterate on extension code without constantly regenerating the entire Xcode project, speeding up development and preserving manual project customizations.

Entitlements & Capabilities Guides

The entitlements/ directory contains guides for iOS entitlements and capabilities that apply across multiple extension types:

Common questions answered by entitlements guides:

• "How do I share data between my app and widget?" → Read app-groups.md
• "My extension can't access UserDefaults from the main app" → Read app-groups.md
• "How does EAS handle App Groups code signing?" → Read app-groups.md

Template for New Skills

If you need to write a new skill document, use _template.md as the starting point. It defines the required frontmatter, section structure, code example format, and quality checklist.

Additional Resources

• CLAUDE.md (project root): Development setup, build instructions, and architecture notes for the @bacons/apple-targets plugin itself
• Apple Developer Documentation: Every skill links to official Apple docs and WWDC sessions
• Expo Documentation: https://docs.expo.dev/config-plugins/introduction/
• Continuous Native Generation: https://docs.expo.dev/workflow/continuous-native-generation/