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.xcodeprojin 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
| Aspect | Before eject | After eject |
|---|---|---|
| Build location | ~/.drift/build/ | ./platform/<platform>/ |
| Project files | Generated fresh each build | User-owned; only Drift's own files and plugin output change |
drift.yaml | Used for all values | plugins: still applies; other values only affect non-ejected platforms |
| IDE usage | Not practical | Full Xcode/Android Studio support |
| Version control | Nothing to commit | Commit ./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.
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:
| Path | Owner |
|---|---|
Runner/ (Swift files, Info.plist) | You |
Runner/Assets.xcassets/ | You |
Runner.xcodeproj/ | You |
bridge/ | Drift (regenerated on build) |
Runner/libdrift.a | Drift (regenerated on build) |
Runner/libdrift_skia.a | Drift (updated when Drift version changes) |
Drift/Plugins/, Runner/DriftPlugins.swift, Runner/DriftPluginRegistrant.swift | Drift (regenerated on build) |
Android:
| Path | Owner |
|---|---|
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) |
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.VIBRATElack it inAndroidManifest.xml, soplatform.Haptics.Vibratefails with aSecurityException(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/...
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
- Plugins - Native SDKs and hooks without ejecting
- Platform Services - Access native platform capabilities
- iOS on Linux with xtool - Build iOS apps without a Mac