PhantomTuistModular

Tuist-based modular iOS template for feature-oriented apps with explicit boundaries between layers.

What this repository is for

This repository gives you a clean starting point for a modular iOS app. Each module has a clear purpose and depends on other modules only through explicit Tuist wiring.

The root application lives in Projects/App.

Current Tuist setup

• Tuist version: 4.203.1
• Root manifest: Tuist.swift
• Workspace manifest: Workspace.swift
• Local plugins:
  • Plugin/DependencyPlugin
  • Plugin/ConfigurationPlugin
  • Plugin/EnvironmentPlugin

The root manifest enables enforceExplicitDependencies, so module relationships stay visible instead of being implied.

Architecture overview

The repo is organized around these layers:

• Feature
  • User-facing flows and screens.
• Domain
  • Business rules and domain logic.
• Core
  • Shared capability modules such as networking, storage, or services.
• Common
  • Shared UI modules, design system pieces, and reusable visual components.
• NetworkService
  • Networking layer modules for API clients, request infrastructure, and service wrappers.
• Shared
  • Cross-cutting utilities such as helpers, extensions, and logging.
• Navigations
  • Shared navigation flow modules and route coordination.
• MainAssembly
  • Top-level app composition modules that wire the root feature set together.

The current template also includes an App project as the root application entry point.

Source of truth

Module scaffolding lives in Tuist/Templates.

Scripts/GenerateModule.swift uses those templates to create modules. The duplicate template plugin was removed so the template source stays in one place.

Prerequisites

• macOS
• Xcode
• mise
• Tuist installed through mise

Setup

1. Set project metadata.

   • Run make init
   • Enter the project name, organization name, minimum deployment target, and UI framework when prompted.
   • If Projects is still empty, this also bootstraps a minimal App project so tuist generate has a project to load.
   • Choose SwiftUI when you want a SwiftUI starter app. This requires a minimum deployment target of iOS 14.0 or newer.
   • Choose UIKit when you want the UIKit starter app.
   • You can enter 16 or 16.0; the initializer normalizes it to 16.0 before writing the environment file.

2. Set signing information.

   • Run make signing
   • Enter your Apple Developer Team ID when prompted.

3. Generate the Xcode project and workspace.

   • Run make generate

Common commands

• make init

  • Runs swift Scripts/InitEnvironment.swift
  • Writes project metadata, minimum deployment target, and UI framework into Plugin/EnvironmentPlugin/ProjectDescriptionHelpers/ProjectEnvironment.swift
  • Bootstraps a starter app in Projects/App when no project manifests exist yet

• make signing

  • Runs swift Scripts/CodeSigning.swift
  • Writes signing settings into Tuist/ProjectDescriptionHelpers/SettingsDictionary/CodeSign.swift

• make generate

  • Runs tuist install
  • Runs tuist generate

• make ci_generate

  • Runs tuist install
  • Runs TUIST_ENV=CI tuist generate

• make cd_generate

  • Runs tuist install
  • Runs TUIST_ENV=CD tuist generate

• make module

  • Runs swift Scripts/GenerateModule.swift
  • Creates a new module under Projects/<Layer>/<ModuleName>
  • If the module already exists, the generator asks whether you want to overwrite it or skip it

• make dependency

  • Runs swift Scripts/NewDependency.swift
  • Adds a new Swift Package dependency and its helper entry

• make clean

  • Deletes generated .xcodeproj and .xcworkspace files

• make reset

  • Runs tuist clean
  • Deletes generated .xcodeproj and .xcworkspace files

Module generation flow

make module asks for:

• Layer
• Module name
• Whether the module needs:
  • Interface target
  • Testing target
  • Unit test target
  • UI test target

Generated targets are wired through shared helpers in Tuist/ProjectDescriptionHelpers and dependency helpers in Plugin/DependencyPlugin.

How to add a new module

1. Run make module.
2. Enter a layer name:
   • Feature
   • Domain
   • Core
   • Shared
   • Common
   • NetworkService
   • Navigations
   • MainAssembly
3. Enter the module name.
4. Answer the target prompts.
   • Interface
   • Testing
   • UnitTests
   • UITests
5. Review the generated files.

The generator will:

• Create Projects/<Layer>/<ModuleName>/Project.swift
• Register the module in Plugin/DependencyPlugin/ProjectDescriptionHelpers/ModulePaths.swift
• Create XCConfig/<ModuleName>/DEV.xcconfig
• Create XCConfig/<ModuleName>/STAGE.xcconfig
• Create XCConfig/<ModuleName>/PROD.xcconfig
• Scaffold the selected targets from Tuist/Templates

If a module with the same name already exists, you will see a prompt:

• n
  • Skip generation and keep the current files.
• y
  • Remove the existing module scaffold and generate it again.

If you need a new Swift Package dependency, run make dependency after the package is added to Package.swift.

End-to-end example

Example: create a feature module named AuthFeature.

1. Run make module.
2. Enter Feature as the layer.
3. Enter AuthFeature as the module name.
4. Choose the targets you need.
   • For a standard feature module, the usual choices are:
     • Interface
     • Testing
     • UnitTests
     • UITests

After generation, you should see:

• Projects/Feature/AuthFeature/Project.swift
• Projects/Feature/AuthFeature source and test scaffolding from Tuist/Templates
• XCConfig/AuthFeature/DEV.xcconfig
• XCConfig/AuthFeature/STAGE.xcconfig
• XCConfig/AuthFeature/PROD.xcconfig
• A new entry in Plugin/DependencyPlugin/ProjectDescriptionHelpers/ModulePaths.swift

If the module needs Swift Package dependencies, add them first, then run make dependency so the helper entry stays in sync.

Generated structure

Modules live under:

Projects/<Layer>/<ModuleName>

Example modules:

Projects/App
Projects/Feature/AuthFeature
Projects/Domain/AuthDomain
Projects/Core/Networking
Projects/Common/DesignSystem
Projects/NetworkService/NetworkService
Projects/Navigations/AppNavigation
Projects/MainAssembly/AppAssembly
Projects/Shared/Logging

Typical folder roles:

• Projects/App
  • Root application target and app-specific resources.
• Projects/Feature
  • User-facing screens and flows.
• Projects/Domain
  • Business rules and domain entities.
• Projects/Core
  • Shared capability modules such as networking or storage infrastructure.
• Projects/Common
  • Shared UI components and design system pieces.
• Projects/NetworkService
  • API clients and service wrappers.
• Projects/Navigations
  • Shared navigation flow modules and route coordination.
• Projects/MainAssembly
  • Root composition modules that assemble screens, flows, and dependencies.
• Projects/Shared
  • Utilities, helpers, extensions, and logging.

Environment behavior

• Default environment is DEV
• TUIST_ENV=CI disables dev-only scripts such as SwiftLint
• TUIST_ENV=CD also disables dev-only scripts
• make init now asks for the minimum deployment target and the UI framework before generating the starter app scaffold

Notes

• tuist inspect dependencies --only implicit should stay clean.
• Scripts/SwiftLintRunScript.sh is used by dev builds when SwiftLint is available.
• The repository defaults to iOS 16.0 in the environment helper, but make init can now regenerate it with a different minimum deployment target.
• make generate expects valid project manifests under Projects/**.

Template reference

Tuist/Templates currently contains:

• Interface
• Sources
• Testing
• Tests
• UITests

These templates are the reference for module bootstrapping.

Troubleshooting

• If make generate reports a deployment target version error, run make init again and enter a valid version such as 16 or 16.0.
• If make module says the module already exists, choose a new module name or answer y to overwrite the existing scaffold.
• If tuist generate fails after a module change, check whether Plugin/DependencyPlugin/ProjectDescriptionHelpers/ModulePaths.swift contains duplicate cases for the same module name.