Developer Setup Guide

June 9, 2026 · View on GitHub

Prerequisites

Required

  • VS Code with Flutter/Dart extensions

Initial Setup

1. Clone the Repository

# Clone the repository
git clone <your-repo-url>
cd dotlottie_flutter

2. Install Dependencies

# Install Flutter dependencies for the plugin
flutter pub get

# Navigate to the example app
cd example

# Install example app dependencies
flutter pub get

Platform-Specific Setup

Android Setup

Prerequisites

  • Android Studio installed with Android SDK
  • Android emulator or physical device with USB debugging enabled

Steps

# From the example directory
cd example

# Check for connected devices/emulators
flutter devices

# If no devices found, start an Android emulator from Android Studio
# Or connect a physical Android device

# Run the app
flutter run

First-Time Android Setup

  1. Open Android Studio
  2. Go to Tools → Device Manager (or AVD Manager in older versions)
  3. Create an emulator if you don't have one
  4. Start the emulator
  5. Run flutter run from the terminal

iOS/macOS Setup (Mac Only)

Prerequisites

  • Xcode installed (from Mac App Store)
  • Xcode Command Line Tools installed
  • CocoaPods installed (only needed for the CocoaPods fallback path, see below)

Dependency management: Swift Package Manager

The Apple (iOS/macOS) native code is distributed as a Swift Package (ios/dotlottie_flutter/Package.swift and macos/dotlottie_flutter/Package.swift), which pulls the native renderer from LottieFiles/dotlottie-ios.

Swift Package Manager is opt-in in Flutter. Enable it once globally:

flutter config --enable-swift-package-manager

With it enabled, flutter run/flutter build resolve the Swift package automatically — no pod install step is required.

The plugin also ships updated .podspec files, so apps that have not enabled Swift Package Manager continue to build via CocoaPods (the fallback path documented below).

Install CocoaPods (only for the CocoaPods fallback path)

sudo gem install cocoapods

iOS Setup Steps

# From the example directory
cd example

# With Swift Package Manager enabled, just run:
flutter run -d ios

# CocoaPods fallback (only if Swift Package Manager is disabled):
#   cd ios && pod install && cd ..
#   flutter run -d ios

First-Time Xcode Setup

  1. Open the workspace in Xcode:
   cd example/ios
   open Runner.xcworkspace  # Important: open .xcworkspace, NOT .xcodeproj

  1. Configure signing:

    • In Xcode, select the Runner project in the left sidebar
    • Go to Signing & Capabilities tab
    • Select your development team (or add your Apple ID under Xcode → Settings → Accounts)

  2. Build and run:

    • Select a simulator or connected device from the dropdown
    • Click the Play button (▶) or press Cmd+R to build

  3. Return to terminal:

    • After the first successful Xcode build, you can use flutter run from the terminal

macOS Setup Steps

# From the example directory
cd example/macos

# Open in Xcode
open Runner.xcworkspace

# Follow the same signing steps as iOS
# Then run from terminal:
cd ..
flutter run -d macos

Common Issues & Solutions

iOS/macOS Issues

"No development team selected"

Solution:

  1. Open the project in Xcode
  2. Go to Runner → Signing & Capabilities
  3. Select your team or add your Apple ID in Xcode → Settings → Accounts

"CocoaPods not installed"

Solution:

sudo gem install cocoapods

"Pod install failed"

Solution:

cd example/ios
pod deintegrate
pod install

"The sandbox is not in sync with the Podfile.lock"

Solution:

cd example/ios
pod install --repo-update

Android Issues

"Android build fails with Gradle errors"

Solution:

cd example/android
./gradlew clean
cd ../..
flutter clean
flutter pub get
cd example
flutter pub get

"SDK location not found"

Solution:

  1. Create local.properties in example/android/:
   sdk.dir=/Users/YOUR_USERNAME/Library/Android/sdk
  1. Replace YOUR_USERNAME with your actual username

General Issues

"Plugin not found" or "MissingPluginException"

Solution:

  1. Make sure you're in the example directory when running
  2. Check that example/pubspec.yaml has:
   dependencies:
     dotlottie_flutter:
       path: ../
  1. Run:
   flutter clean
   flutter pub get
   cd example
   flutter clean
   flutter pub get

"Version solving failed" or dependency conflicts

Solution:

flutter clean
rm pubspec.lock
flutter pub get
cd example
rm pubspec.lock
flutter pub get

Verification

After setup, verify everything works:

# From the example directory
cd example

# Check Flutter setup
flutter doctor

# Check available devices
flutter devices

# Run the example app
flutter run

You should see output like:

Multiple devices found:
sdk gphone64 arm64 (mobile) • emulator-5554 • android-arm64 • Android 13 (API 33)
iPhone 15 Pro (mobile)      • ABC123...     • ios           • com.apple.CoreSimulator...

Quick Reference Commands

Clean Everything

# From project root
flutter clean
cd example
flutter clean
cd ..
flutter pub get
cd example
flutter pub get

Run on Specific Platform

flutter run -d android
flutter run -d ios
flutter run -d macos

View Logs

# Flutter logs (all platforms)
flutter logs

# Android-specific logs
adb logcat | grep -i dotlottie

List Available Devices

flutter devices

Next Steps

Once setup is complete:

  1. ✅ Run flutter doctor to verify your environment
  2. ✅ Run flutter devices to see available devices
  3. ✅ Run flutter run in the example directory
  4. ✅ Check the CONTRIBUTING.md for development guidelines

Getting Help

If you encounter issues not covered here: