Getting Started

In this section, you’ll learn how to create an iOS project with Beagle

Topics covered

  • Creating an iOS project from scratch
  • Adding Beagle to your project (works with existing projects)
  • Configuring Beagle
  • Other customizations


  • MacOS with Xcode 11+ installed
  • Swift Package Manager (already installed with Xcode), Cocoapods or Carthage
  • iOS 10.0+
  • Swift 5.0+

Creating an iOS project from scratch

We’re using Xcode 11+ on this example, so if you don’t have it, please download it from AppStore.

Step 1: Open your Xcode and click on File -> New -> Project.

Step 2: Select a single view application known as just App and click on next.

Step 3: Name your project, select the interface as Storyboard, language Swift and go next.

Step 4: Inform where you want to place your project and confirm.

Adding Beagle to your project

You can install Beagle using SPM (Swift Package Manager), Cocoapods or Carthage. Just pick one and follow the instructions bellow:

Current Beagle’s version: badge

You only need Xcode here. More on Swift Package Manager:

Step 1: Click on File -> Swift Packages -> Add Package Dependency.

Step 2: Enter Beagle’s package repository url: and click on next.

Step 3: Confirm Beagle’s version, click on next and let Xcode resolve the package.

Step 4: On the final dialog, update Beagle’s Add to Target column with the target that should import Beagle.

SPM with existing Package.swift

Step 1: Add Beagle to dependencies choosing preferably the latest version available, like 1.8.0 for instance.

dependencies: [
  .package(name: "Beagle", url: "", from: "${beagle.version}"}}),

Step 2: Add Beagle as a dependency of your application target:

targets: [
  .target(name: "MyApp", dependencies: ["Beagle"], path: "Sources")

You’ll need Cocoapods installed and Terminal.

Step 1: Navigate to your project’s root folder and run the command pod init that will create a Podfile.

Step 2: Edit your Podfile, adding Beagle’s pod name, like the code below:

target 'MyApp' do
  pod 'Beagle'

Step 3: Run the command pod install and the dependencies will be resolved in a Workspace.

Step 4: Now, open the Workspace created for you. From now you’ll use only the Workspace.

To do this, you’ll need Carthage installed and a Terminal.

Step 1: Navigate to your project’s root folder and run touch Cartfile to create a Cartfile for us.

Step 2: Open the Cartfile and edit it with our repository link like this github "ZupIT/beagle" ~> ${beagle.version}, choosing preferably the Beagle’s latest version available.

Step 3: Now, check your Xcode version and follow the instructions below:

  • For Xcode 12+, you need Carthage v0.37+. Then you can run the command carthage udpate --use-xcframeworks. This command will create xcframeworks.

  • For Xcode below 12, just run Carthage update and it will create xcframeworks.

Step 4: Now, go to: your project’s root folder -> Carthage -> Build. Pick up Beagle.xcframework folder and drag into Xcode -> yourProject.xcodeproj -> Targets -> yourProject -> General -> Frameworks, Libraries, and Embedded Content.

Step 5: To run Beagle you will also need YogaKit. You can install it using SPM (Swift Package Manager).

  1. From the File menu, navigate through Swift Packages and select ‘Add Package Dependency';
  2. Enter package repository URL:;
  3. Confirm Beagle’s version and let Xcode resolve the package.

Configuring Beagle

After Beagle’s installation, you need to configure it to run on our application. For that, follow the instructions below:

Step 1: Create a BeagleConfig class:

This class contains part of Beagle’s initial configuration. You have to implement a config static function in it to apply these configurations.

import Beagle
import Foundation

class BeagleConfig {
    static func config() {}

Step 2: On this function, create a constant called dependencies that must be a BeagleDependencies.

You’ll attribute to this constant some project’s configurations. An example of this configuration is the base URL that will be combined with a relative URL to bring the JSON that will load your server-driven screen.

To configure it, use the example below:

import Beagle
import Foundation

class BeagleConfig {
    static func config() {
        let dependencies = BeagleDependencies()
        dependencies.urlBuilder = UrlBuilder(
            baseUrl: URL(string: "http://localhost")
        Beagle.dependencies = dependencies

Step 3: Now, you will configure the SceneDelegate class so it can be used to initialize your application with Beagle from a screen through BFF:

  1. Inside your SceneDelegate.swift in the function scene, call the BeagleConfig.config() function;

  2. Name the guard let that Xcode already created for you as windowScene;

  3. Initialize the variable window created outside the function scope, using windowScene;

  4. Make the window.rootViewController the screen from BFF that you want to display;

  5. Now, just call the makeKeyAndVisible() function from the variable window.

Your code should be like this:

import UIKit
import Beagle

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }
        window = UIWindow(windowScene: windowScene)
        window?.rootViewController = BeagleScreenViewController(.remote(.init(url: "/yourScreenRelativeURL")))


You can implement these layers using these tutorials:

Custom Network Layer

Custom Cache Manager

Custom Log System

If you want to skip these configurations, use Beagle’s support library: Beagle Scaffold, that contains default implementations of Network, Cache and Log layers.

However, you should remember that it is important to customize your Network layer for security matters.

Other Customizations

You can do other customizations, see them below:

  • Action: Create custom actions to be executed by your widgets as your users interact with your app;
  • Navigation Animation: Customize Beagle screen navigation animations.
  • Network Client: Customize the network client to configure the way Beagle will make requests.
  • Cache: Customize your cache layer to save server-driven screens as you wish.
  • Loading and error handling: Customize the error handling and loading of server-driven screens.
  • Deep Link handler: Configure Deep Link Handler to navigate from a server-driven screen to a native screen.
  • Image Downloader: Customize how images will be downloaded to be displayed by Beagle.
  • Design System: Customize your design system to build more beautiful screens to be displayed by Beagle.
  • Serializer and Deserializer: Customize how Beagle will serialize and deserialize it’s components (screens, components, actions, etc).
  • Log: Customize how logs generated by Beagle will be displayed.
  • Widget: Create more specific components to your project and use them to build your server-driven screens.
  • Operations: Create your operations to easily manipulate the context by your backend.
  • Analytics: Configure analytics to generate screen and actions reports.