pnpm-pods-autolink

Expo config plugin to automatically link pnpm workspace packages for iOS CocoaPods.

The Problem

When using pnpm workspaces with Expo and custom native modules, iOS builds fail because CocoaPods can't resolve pnpm's symlinks.

Symptoms

Silent crashes (most frustrating): Your app crashes with no clear error message - often in the React Native bridge or during app startup. The crash appears unrelated to your custom module. Removing the custom module from your code makes the crash go away, but there's no indication that the pod wasn't linked.

How to identify this:

• If your iOS build succeeds but the app crashes when using (or even just importing) a custom Expo module from a workspace package, the pod is likely not linked.
• Run expo run:ios and check the build output - if your custom module is missing from the list of compiled pods, it wasn't linked to the Podfile.

Common Error Messages

If you're seeing any of these errors, this plugin can help:

[!] Unable to find a podspec in `../modules/my-module/ios`

error: Build input file cannot be found: '/path/to/node_modules/.pnpm/...'

[!] No podspec found for `MyExpoModule` in `../my-module/ios`

ld: library not found for -lExpoModulesCore

These occur because:

• pnpm uses symlinks for workspace packages
• CocoaPods doesn't resolve symlinks properly
• Expo's autolinking can't find local modules in pnpm monorepos
• Custom Expo modules in workspace packages aren't linked to the Podfile

The Solution

This plugin automatically discovers workspace packages that have an ios/ directory with a .podspec file and adds them explicitly to the Podfile.

Installation

pnpm add pnpm-pods-autolink

Usage

Zero Config (Recommended)

Just add the plugin to your app.json:

{
  "expo": {
    "plugins": ["pnpm-pods-autolink"]
  }
}

The plugin will automatically:

1. Find your pnpm-workspace.yaml
2. Scan all workspace packages for ios/ directories
3. Extract pod names from .podspec files
4. Add them to the Podfile

With Options

{
  "expo": {
    "plugins": [
      [
        "pnpm-pods-autolink",
        {
          "exclude": ["some-package-to-skip"],
          "pods": [
            {
              "name": "ManualPod",
              "path": "../path/to/pod/ios"
            }
          ]
        }
      ]
    ]
  }
}

Options

| Option | Type | Description | |--------|------|-------------| | exclude | string[] | Package names to exclude from auto-discovery | | pods | PodConfig[] | Additional pods to link manually (overrides auto-discovered) | | disableAutoDiscovery | boolean | Set to true to only use manual pods |

How It Works

1. Finds the monorepo root by searching for pnpm-workspace.yaml
2. Parses the workspace patterns from the YAML file
3. For each matching package directory:
   • Checks if it has an ios/ directory
   • Looks for a .podspec file
   • Extracts the pod name from s.name in the podspec
4. Adds explicit pod paths to the Podfile after use_expo_modules!

Example Output

The plugin adds entries like this to your Podfile:

use_expo_modules!

  # pnpm workspace pods (auto-generated by pnpm-pods-autolink)
  pod 'ExpoAppleMusic', :path => '../expo-apple-music/ios'

Related Issues

This plugin solves issues commonly discussed in:

• Expo monorepo setups with pnpm
• Custom Expo modules not being found by CocoaPods
• React Native autolinking failing with pnpm symlinks
• pod install unable to find local podspecs in workspace packages

Requirements

• Expo SDK 50+
• pnpm workspace with pnpm-workspace.yaml
• Custom modules with ios/ directory containing a .podspec file

License

MIT