Skip to main content

Ejecting

By default, Drift manages platform projects (Xcode, Android Studio) behind the scenes in ~/.drift/build/. Ejecting extracts the native project into your repository so you can customize it directly.

When to Eject​

Eject when you need to:

  • Modify the Xcode project or Gradle build configuration in ways no plugin covers
  • Edit native code Drift generates
  • Open the project in Xcode or Android Studio for debugging

To add a native SDK, permissions or platform hooks, use a plugin first: plugins change the generated project on every build, so you keep a managed project. If you only need to change your app name, bundle ID, or other values in drift.yaml, you do not need to eject.

Ejecting a Platform​

drift eject ios        # Eject iOS project
drift eject android # Eject Android project
drift eject all # Eject both platforms

This creates a platform/ directory in your project root:

myapp/
├── drift.yaml
├── main.go
└── platform/
├── ios/ # Real Xcode project
│ ├── Runner/
│ │ ├── Info.plist
│ │ ├── AppDelegate.swift
│ │ └── Assets.xcassets/ # App icon and launch images
│ ├── Runner.xcodeproj/
│ ├── bridge/ # Drift-managed, regenerated on build
│ └── driftw # Wrapper script for IDE builds
└── android/ # Real Android project
├── app/
│ ├── build.gradle
│ └── src/main/
│ ├── AndroidManifest.xml
│ ├── java/com/example/myapp/
│ │ ├── DriftApplication.kt # Registers channels and plugins at process start
│ │ └── MainActivity.kt
│ └── res/
│ ├── drawable/ # Launch screen background
│ ├── mipmap-*/ # App icon PNGs per density
│ ├── mipmap-anydpi-v26/ # Adaptive icon XML
│ └── values/ # Styles (launch theme)
├── settings.gradle
├── bridge/ # Drift-managed, regenerated on build
└── driftw # Wrapper script for IDE builds

After ejecting, you can open the project directly:

  • iOS: Open platform/ios/Runner.xcodeproj in Xcode 16+ (the ejected project uses the synchronized-group project format, which is unsupported in Xcode 15)
  • Android: Open platform/android/ in Android Studio

Check Eject Status​

drift status
Project: myapp (com.example.myapp)

Platforms:
ios: ejected → ./platform/ios/
android: managed → ~/.drift/build/myapp/android/<hash>/

What Changes After Ejecting​

AspectBefore ejectAfter eject
Build location~/.drift/build/./platform/<platform>/
Project filesGenerated fresh each buildUser-owned; only Drift's own files and plugin output change
drift.yamlUsed for all valuesplugins: still applies; other values only affect non-ejected platforms
IDE usageNot practicalFull Xcode/Android Studio support
Version controlNothing to commitCommit ./platform/ to repo

Values from drift.yaml (app name, bundle ID) are substituted at eject time. After ejecting, changes to drift.yaml will not affect the ejected platform. Edit the native project files directly instead.

App Icons

The app.icon and app.icon_background fields in drift.yaml are applied at eject time. To change icons after ejecting, replace the images directly in Runner/Assets.xcassets/ (iOS) or app/src/main/res/mipmap-*/ (Android).

Building After Ejecting​

Both drift build and drift run continue to work after ejecting. The only difference is that they build in ./platform/<platform>/ instead of ~/.drift/build/, and your customizations are preserved.

From the CLI​

drift run ios      # Compiles Go, builds in ./platform/ios/, runs on device/simulator
drift run android # Compiles Go, builds in ./platform/android/, runs on device/emulator

From Xcode​

Open platform/ios/Runner.xcodeproj and press Cmd+R. A build phase script calls drift compile automatically before the Swift build.

From Android Studio​

Open platform/android/ and press Run. A Gradle task calls drift compile automatically before the Android build.

File Ownership​

After ejecting, some files belong to you and some are managed by Drift. Drift never overwrites your files on build, except for the edits plugins make (see Plugins).

iOS:

PathOwner
Runner/ (Swift files, Info.plist)You
Runner/Assets.xcassets/You
Runner.xcodeproj/You
bridge/Drift (regenerated on build)
Runner/libdrift.aDrift (regenerated on build)
Runner/libdrift_skia.aDrift (updated when Drift version changes)
Drift/Plugins/, Runner/DriftPlugins.swift, Runner/DriftPluginRegistrant.swiftDrift (regenerated on build)

Android:

PathOwner
app/ (Kotlin, manifests, Gradle config)You
app/src/main/res/ (icons, drawables, styles)You
settings.gradle, gradle.properties, gradle/You
bridge/Drift (regenerated on build)
app/src/main/jniLibs/Drift (overwritten on build)
app/src/main/java/com/drift/runner/Drift (regenerated on build)
warning

Do not place custom native libraries in app/src/main/jniLibs/ as Drift overwrites this directory on each build. Use a separate directory and configure Gradle's jniLibs.srcDirs if you need additional native libraries.

Plugins​

Plugins in drift.yaml keep working after ejecting: each build applies them to the ejected project. Drift owns these files and rewrites them each build:

iOS (platform/ios)Android (platform/android)
Drift/Plugins/ (a local Swift package holding every plugin's Swift module)app/src/main/java/com/drift/runner/ (plugin host support and the generated registrant)
Runner/PluginResources/ (bundle resources and plugin configs)app/src/main/assets/drift/plugins/ (plugin configs)
Runner/DriftPlugins.swift, Runner/DriftPluginRegistrant.swift

Plugins also edit shared files: Info.plist, Runner.entitlements, AndroidManifest.xml, build.gradle, resource values. Drift records what it applied in .drift/plugins.lock.json in each platform project; commit it.

When you remove a plugin, Drift deletes the files it owned (unless you changed them), restores the template's LaunchScreen.storyboard if a plugin replaced it and you have not changed it since, and the next build warns with a list of the edits it made inside shared files, such as an Info.plist key or a manifest permission. Drift cannot tell those apart from your own edits, so you remove them, or keep them if you still want them. The build still succeeds; commit the updated lock, or each build from a checkout of the old one warns again.

When a plugin upgrade changes a Gradle dependency's version or a Gradle plugin's version, Drift updates the line it wrote in place. If you changed that line yourself, Drift leaves it and adds its own.

Drift never overwrites a file it did not write. If a plugin would replace one of your files, or a plugin file you edited, the build fails and names each file. That includes LaunchScreen.storyboard: a plugin such as splash replaces it only while it is the template's or what the plugin wrote, never your own launch screen. Move yours aside (or undo your change) to let the plugin write it, or remove the plugin. Like any plugin op that fails, this stops the build before Drift changes a file in the project.

If .drift/plugins.lock.json stops parsing (a merge conflict, say), resolve it, or delete it: Drift then treats plugin files as new, and refuses only those whose content differs from what the plugin writes.

If an ejected project lacks the wiring plugins need (calls into DriftPlugins, the Drift/Plugins package reference), the build fails and names the file and call to restore. Compare with a freshly ejected project.

iOS projects ejected before plugins could claim URLs fail to build with plugins until SceneDelegate.swift offers URLs and user activities to DriftPlugins.shared.openURL / continueUserActivity before DeepLinkHandler; the error names the calls, and a freshly ejected project shows them in place.

iOS projects ejected before plugins detached on scene disconnect lack sceneDidDisconnect in SceneDelegate.swift and the weak display link target in DriftViewController.swift. They still build, but plugins stay attached to a closed scene and the view controller is never released. Copy both from a freshly ejected project.

.gitignore Setup​

Add these entries to keep build artifacts out of version control:

# Drift build artifacts
platform/*/.drift.env
platform/ios/Runner/libdrift.a
platform/ios/Runner/libdrift_skia.a
platform/ios/Runner/.drift-skia-version
platform/android/app/src/main/jniLibs/
platform/*/bridge/

If your project already ignores platform/ (common in some frameworks), update the rule to only ignore build artifacts:

# Before (ignores everything)
platform/

# After (ignore only build artifacts)
platform/*/.drift.env
platform/ios/Runner/libdrift.a
platform/ios/Runner/libdrift_skia.a
platform/ios/Runner/.drift-skia-version
platform/android/app/src/main/jniLibs/
platform/*/bridge/

Re-ejecting​

If a platform is already ejected, drift eject will refuse to overwrite it:

Error: platform/ios/ already exists. Use --force to overwrite (creates backup).

Use --force to back up the existing directory and eject a fresh copy:

drift eject --force ios

The backup is saved as platform/ios.backup.<timestamp>/.

An ejected project keeps the template it was ejected from. Changes to the template since then reach it only through a re-eject or by hand:

  • Android projects ejected before Drift declared android.permission.VIBRATE lack it in AndroidManifest.xml, so platform.Haptics.Vibrate fails with a SecurityException (and impacts do when no view gives haptic feedback). Add <uses-permission android:name="android.permission.VIBRATE" />, as a freshly ejected project has.

Undoing Eject​

To return to managed mode, delete the platform directory:

rm -rf ./platform/ios      # Return iOS to managed mode
rm -rf ./platform/android # Return Android to managed mode
rm -rf ./platform # Return both to managed mode

After deletion, drift build and drift run will use ~/.drift/build/ again and regenerate everything from templates and drift.yaml.

Verify with drift status:

drift status
# ios: managed → ~/.drift/build/...
# android: managed → ~/.drift/build/...
caution

Deleting the platform directory discards all native customizations you made while ejected (Info.plist changes, added SDKs, Gradle configuration, etc.). Make sure any important changes are backed up or recorded before deleting.

If the ejected directory is tracked in git, also remove it from version control:

git rm -r ./platform/ios
git commit -m "Return iOS to managed mode"

Next Steps​