A Skip app project is one that is created with skip init or skip create. At its essence, it is a standard Swift Package Manager project ↗, with a top-level Package.swift and directories for Sources/ and Tests/.

Skip augments this structure by adding shared Skip.env metadata and Darwin/ and Android/ sub-folders that house the build systems for their respective platforms along with platform-specific metadata and deployment information.

A Skip project can be built locally with swift build and tested with swift test. In addition, Skip-specific commands like skip export can be used to build the platform-specific binaries (.ipa for iOS and .apk for Android) for distribution through the various app stores.

There are four standard examples that can be perused that illustrate the structure of a conventional Skip project:

1. HelloSkip: A basic example of a transpiled Skip Lite app project.
2. HowdySkip: A basic example of a compiled Skip Fuse app project.
3. AhoySkipper: A multi-module Skip Fuse app project.
4. HiyaSkip: An example of a Skip app project that uses a compiled (Skip Fuse) UI module bridging to a transpiled (Skip Lite) model layer module.

Consider an “Ahoy Skipper” Skip Fuse app with two modules and test cases that can be generated with the following skip init command (or the equivalent skip create interactive command):

skip init --native-app --bridged --module-tests --show-tree --appid=ahoy.skipper ahoy-skipper AhoySkipper SkipperModel

An abridged view of the filesystem layout of the app will look like this:

This file is the manifest for the Swift Package Manager (SwiftPM). It defines the project’s name, products (libraries or executables), dependencies, and targets. In a Skip project, it also declares the skipstone plugin, which handles the translation of the iOS project into an equivalent Android project.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Package.swift ↗
• Reference: Swift Package Manager - Package.swift Manifest ↗

This file is an Xcode Workspace, a container used to group multiple Xcode projects and Swift packages together. In Skip, it allows you to manage the primary Darwin app project alongside the shared Swift modules in a single interface, ensuring that shared code changes are immediately reflected in the app build.

The generated Project.xcworkspace will contain only the Darwin/ProjectName.xcodeproj, but additional projects and frameworks can be added to it, as described in the Contribution Guide.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Project.xcworkspace/contents.xcworkspacedata ↗
• Reference: Xcode Help - Workspace Concepts ↗

This is a shared configuration environment file for Skip projects. It contains key-value pairs for project-wide metadata, such as the PRODUCT_NAME, MARKETING_VERSION, and PRODUCT_BUNDLE_IDENTIFIER. These variables are used by both the Xcode build process and the Gradle build process to ensure consistency between the iOS and Android binaries. It is included by both the Darwin/ProjectName.xcconfig and Android/settings.gradle.kts files.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Skip.env ↗
• See also: Configuration Metadata

The shared app entry point, which launches and configures the app and holds the primary ContentView.swift and contains app lifecycle callbacks. This will be the common app logic that is invoked from the Darwin Main.swift and Android Main.kt.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Sources/AhoySkipper/AhoySkipperApp.swift ↗

This file is a SwiftUI View file representing the main user interface of the application. In a Skip project, the SwiftUI code in this file will be translated into Jetpack Compose for Android, allowing a single declarative UI definition to drive both platforms.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Sources/AhoySkipper/ContentView.swift ↗
• Reference: SwiftUI Views ↗

This is a YAML Configuration file specific to Skip. It controls module-level settings, such as Skip mode, bridging configurations, and Android-specific dependencies.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Sources/AhoySkipper/Skip/skip.yml ↗

This is an Asset Catalog located within a specific Swift module. It holds resources like images, data, and localized strings that are scoped to that module. Skip ensures these assets are processed and made available to both the iOS bundle and the Android res directory.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Sources/AhoySkipper/Resources/Module.xcassets ↗
• Reference: Apple Developer - Asset Catalogs ↗

This is a String Catalog file used for managing translations. It is the modern format for Darwin localization. Skip converts these strings into Android asserts during the build process which will be used to provide translation parity on both platforms.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Sources/AhoySkipper/Resources/Localizable.xcstrings ↗
• Reference: Apple Developer - Localizing UI Strings ↗

This file contains the business logic and state for the app, typically utilizing the @Observable macro.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Sources/SkipperModel/ViewModel.swift ↗

This file contains test cases used to verify the logic of your modules. For a Skip Fuse project, these tests can be run directly with skip android test, and for a Skip Lite project, tests will be transpiled into Kotlin and can be run with skip test.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Tests/SkipperModelTests/SkipperModelTests.swift ↗

This is an Xcode Build Configuration file. It provides a way to define build settings (such as compiler flags or search paths) in a plain-text format rather than within the opaque .xcodeproj file, making it easier to manage environment-specific settings.

This configuration file automatically includes the root-level Skip.env file, so common properties can be shared between the Darwin and Android projects.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Darwin/AhoySkipper.xcconfig ↗
• Reference: Apple Developer - Configuration Settings File (xcconfig) format ↗

This is the Xcode Project file, a bundle containing the configuration, build targets, and file references for the Darwin (iOS/macOS) version of the app. It is the primary entry point for developers focused on the Apple ecosystem.

This project will automatically be included by the generated Project.xcworkspace.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Darwin/AhoySkipper.xcodeproj ↗
• Reference: Apple Developer - Xcode Project Structure ↗

This is the Primary Asset Catalog for the Darwin application. It typically contains the application’s icon sets, launch images, and global color assets required for the iOS target.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Darwin/Assets.xcassets ↗

This is the Source Image file for the Darwin application icon.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Darwin/Assets.xcassets/AppIcon.appiconset ↗
• Reference: Apple Developer - App icons ↗

This is an XML Property List that defines the capabilities and permissions of the iOS app, such as Push Notifications or application permissions.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Darwin/Entitlements.plist ↗
• Reference: Apple Developer - Entitlements ↗

This file is the Information Property List for the iOS application. It contains essential configuration data, such as the bundle identifier, supported orientations, and required hardware capabilities.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Darwin/Info.plist ↗
• Reference: Apple Developer - Info.plist Keys ↗

This file serves as the Darwin Entry Point. It contains the @main attribute which initializes the SwiftUI App lifecycle for the iOS/macOS version of the project.

The contents of this file will be quite minimal. Like its Kotlin Main.kt counterpart, it mostly calls into the shared <Module>App.swift.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Darwin/Main.swift ↗
• Reference: Apple Developer - App Structure ↗

This directory contains Fastlane configuration files (Deliverfile, Fastfile, Appfile) used to automate the deployment process for the iOS app, specifically for uploading to the Apple App Store and TestFlight.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Darwin/fastlane ↗
• Reference: Fastlane - Upload metadata and binary to App Store Connect ↗

This is the Android Entry Point. It contains the MainActivity class, which serves as the primary Activity for the Android app. The contents of this file will be quite minimal. Like its Swift Main.swift counterpart, it mostly calls into the shared <Module>App.swift.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Android/app/src/main/kotlin/Main.kt ↗
• Reference: Android Developers - Activities ↗

This is a Gradle Settings file written in Kotlin DSL. It defines the project-level settings and includes the sub-modules (like :app) that make up the Android build.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Android/settings.gradle.kts ↗
• Reference: Gradle - Settings File ↗

This is the Module-level Gradle Build file. It defines the Android-specific build configuration, including SDK versions, signing configurations, and dependencies (including the transpiled Swift modules).

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Android/app/build.gradle.kts ↗
• Reference: Android Developers - Configure Your Build ↗

This file contains R8/ProGuard rules for code shrinking and optimization. It ensures that the Kotlin code and its dependencies are properly minified for production.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Android/app/proguard-rules.pro ↗
• Reference: Enable app optimization ↗

This is the Android Manifest file. It describes essential information about the app to the Android build tools, the Android OS, and Google Play, including permissions and the entry point Activity.

• Example: https://github.com/skiptools/skipapp-ahoy/blob/main/Android/app/src/main/AndroidManifest.xml ↗
• Reference: Android Developers - App Manifest Overview ↗

This is a folder that contains app icon for various density Android screens.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Android/app/src/main/res ↗
• Reference: Android Developers - App Icons ↗

This directory contains Fastlane configuration files (Appfile, Fastfile) used to automate the deployment process for the Android app, specifically for uploading to the Google Play Store.

• Example: https://github.com/skiptools/skipapp-ahoy/tree/main/Android/fastlane ↗
• Reference: Fastlane - Upload metadata, screenshots and binaries to Google Play ↗

The Skip Getting Started guide demonstrates using skip create to generate a basic app project interactively, but there are a variety of additional project types. This document discussed the various different project types that can be created and built with Skip.

The skip init command is an alternative to the interactive skip create command, which facilitates the initialization of an app with a single, non-interactive command. Run skip init --help or see the the command line reference for a complete listing of skip init options.

Create a new dual-platform app project with the command:

skip init --native-app --appid=bundle.id project-name AppName

Pass the --open-xcode argument to immediately open the project in Xcode. For example:

skip init --open-xcode --native-app --appid=bundle.id.HelloSkip hello-skip HelloSkip

This will create a hello-skip/ folder with a new SwiftPM package containing a single module named HelloSkip, along with folders named Darwin and Android and the shared Skip.env app configuration file. The Darwin folder will contain a HelloSkip.xcodeproj project with a HelloSkip target, which you can open in Xcode.

Skip is designed to accommodate and encourage using multi-module projects. You can create a modularized project by specifying additional module names to skip init at the end of the chain. For example:

skip init --native-app --appid=bundle.id.HelloSkip multi-project HelloSkip HelloModel HelloCore

This command will create a SwiftPM project with three modules: HelloSkip, HelloModel, and HelloCore. The heuristics of such module creation is that the modules will all be dependent on their subsequent peer module, with the first module (HelloSkip) having an initial dependency on SkipFuseUI and the second module depending on SkipFuse and SkipModel. The Package.swift file can be manually edited to shuffle around dependencies, or to add new dependencies on additional frameworks.

You might choose to share functionality using dual-platform frameworks, but create separate iOS and Android apps. Some development teams, for example, would like to share common model and business logic layers, but write the UI separately for each platform.

The Travel Posters sample app provides an example of this pattern. You can read more about it in this blog post. It has the following top-level entries:

• travel-posters-model: This SwiftPM package builds a dual-platform framework containing a common model layer for the iOS and Android apps. Skip ensures that the @Observable types you write in Swift can power not only a SwiftUI interface, but a Compose interface as well. See the Development documentation for details.
• iOS: Directory containing the TravelPosters iOS app and Xcode project, which has travel-posters-model as a package dependency.
• Android: Directory containing the Android version of the app. The Android/lib directory contains exported archives of travel-posters-model and the various Skip frameworks that it depends on.
• TravelPostersNative.xcworkspace: A workspace that includes both the iOS app and the travel-posters-model package.

Use TravelPostersNative.xcworkspace to iterate on the iOS app and/or shared model layer. To donate the latest travel-posters-model code to the Android app:

skip export --project travel-posters-model -d Android/lib/debug/ --debug
skip export --project travel-posters-model -d Android/lib/release/ --release

There are many ways to automate this process, from simple scripting to git submodules to publishing Skip’s generated Android travel-posters-model output to a local Maven repository. Use whatever system fits your team’s workflow best.

Additional notes:

• You may need to “Sync Project with Gradle Files” in Android Studio after updating the exported libraries.
• Using an exported library function which has transitive dependencies on additional Android libraries can cause a runtime error. You must ensure that all transitive dependencies are in your own app’s build.gradle.kts.

SkipFuse apps can depend on pure SwiftPM packages as well as pure Kotlin/Java Android libraries. See the chapter covering dependencies for details. This section describes how to create a Swift framework whose API can be used from both Swift and Kotlin. The most common use cases are powering SkipLite transpiled apps or separate iOS and Android apps.

Dual-platform Skip frameworks are pure SwiftPM packages that encapsulate common functionality. Frameworks are simpler than app projects, as they do not need Darwin/ and Android/ folders.

A new framework project can be generated with:

skip init --native-model lib-name ModuleName

This will create a new lib-name folder containing a Package.swift with targets of ModuleName and ModuleNameTests.

The generated package can be opened in Xcode, which you can use to build and run the unit tests. Or use swift build and swift test from the Terminal for headless testing as part of a continuous integration process.

The --native-model option we passed to skip init will configure Skip to automatically bridge our model’s public API from compiled Swift to Android’s ART ↗ Java runtime. This is done through the skip.yml configuration file included in every Skip module. See the documentation on bridging and skip.yml for details.

The structure of a Skip framework is exactly the same as any other SwiftPM package:

Skip frameworks use a standard Package.swift file, with the exception of added dependencies on Skip libraries and use of the skipstone plugin for transpilation:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "lib-name",
    defaultLocalization: "en",
    platforms: [.iOS(.v16), .macOS(.v13), .tvOS(.v16), .watchOS(.v9), .macCatalyst(.v16)],
    products: [
        .library(name: "ModuleName", targets: ["ModuleName"]),
    ],
    dependencies: [
        .package(url: "https://github.com/skiptools/skip.git", from: "1.7.0"),
        .package(url: "https://github.com/skiptools/skip-fuse.git", from: "1.0.0"),
        .package(url: "https://github.com/skiptools/skip-model.git", from: "1.0.0"),
    ],
    targets: [
        .target(name: "ModuleName", , dependencies: [
            .product(name: "SkipFuse", package: "skip-fuse")
            .product(name: "SkipModel", package: "skip-model")
        ], plugins: [
            .plugin(name: "skipstone", package: "skip")
        ]),
        .testTarget(name: "ModuleNameTests", dependencies: ["ModuleName"], plugins: [.plugin(name: "skipstone", package: "skip")]),
    ]
)

This configuration includes the dependencies you need to write common model code, including @Observables that will work with both SwiftUI and Compose user interfaces. You are free to edit Package.swift for your particular needs.

Migrating an existing app to Skip is not trivial. Most apps contain many iOS-only dependencies that make an Android port challenging.

Additionally, when you use skip create or skip init to create a new Skip app, it handles all the messy details involved in making an app that can build for both iOS and Android. The process is complex enough that we do not recommend trying to migrate an existing Xcode project. Instead, choose one of two options to create an Android version of your existing app:

1. Use skip create or skip init to create a new Skip app, then add your existing app’s dependencies and code.
2. Keep your existing Xcode app, and create a separate Android app using Android Studio or your IDE of choice. Manage the apps separately, but share code by creating dual-platform frameworks.

Regardless of which option you choose, your first steps are the same:

1. Modularize your app into Swift Package Manager packages, if it isn’t already.
2. Starting with your “base” module and working your way up the stack, attempt to get each module building for Android.

We recommend using Skip Fuse where possible, as it offers greater compatibility with existing Swift code and dependencies.

Porting an app to an entirely new platform isn’t easy, even with Skip. Remember that we’re here to help.