Skip to content

SETUP.md

Latest commit

 

History

History
222 lines (165 loc) · 6.69 KB

SETUP.md

File metadata and controls

222 lines (165 loc) · 6.69 KB

Setup Instructions for TCA and Redux Patterns

This document provides step-by-step instructions for adding the newly implemented TCA (The Composable Architecture) and Redux patterns to the Xcode project.

Current Status

The following files have been created but are not yet added to the Xcode project:

TCA Pattern Files

Examples/TCA/
├── Features/
│   └── TCAAppFeature.swift
├── Models/
│   ├── TCAListItem.swift
│   └── TCASidebarCategory.swift
├── Views/
│   ├── TCAContentListView.swift
│   ├── TCAContentView.swift
│   ├── TCADetailView.swift
│   ├── TCASettingsContentView.swift
│   └── TCASidebarView.swift
└── README.md

Redux Pattern Files

Examples/Redux/
├── Actions/
│   └── ReduxActions.swift
├── Models/
│   ├── ReduxListItem.swift
│   └── ReduxSidebarCategory.swift
├── Reducers/
│   └── ReduxReducers.swift
├── State/
│   └── ReduxAppState.swift
├── Store/
│   └── ReduxStore.swift
├── Views/
│   ├── ReduxContentListView.swift
│   ├── ReduxContentView.swift
│   ├── ReduxDetailView.swift
│   ├── ReduxSettingsContentView.swift
│   └── ReduxSidebarView.swift
└── README.md

Setup Steps

Step 1: Add TCA Dependency

TCA requires the Swift Package from Point-Free:

  1. Open SwiftUIExamples.xcodeproj in Xcode
  2. Go to File > Add Package Dependencies...
  3. Enter the repository URL: https://github.com/pointfreeco/swift-composable-architecture
  4. Select version: 1.0.0 or later (recommended: latest)
  5. Click Add Package
  6. Ensure ComposableArchitecture is added to the SwiftUIExamples target

Step 2: Add TCA Files to Project

  1. In Xcode's Project Navigator, right-click on the Examples folder
  2. Select Add Files to "SwiftUIExamples"...
  3. Navigate to Examples/TCA
  4. Select the TCA folder
  5. Ensure the following options are checked:
    • ✅ Copy items if needed (leave unchecked since files are already in project)
    • ✅ Create groups (not "Create folder references")
    • ✅ Add to targets: SwiftUIExamples
  6. Click Add

Important: When adding files, Xcode may warn about the README.md file. See "Resolving README Conflicts" below.

Step 3: Add Redux Files to Project

  1. In Xcode's Project Navigator, right-click on the Examples folder
  2. Select Add Files to "SwiftUIExamples"...
  3. Navigate to Examples/Redux
  4. Select the Redux folder
  5. Ensure the following options are checked:
    • ✅ Copy items if needed (leave unchecked)
    • ✅ Create groups
    • ✅ Add to targets: SwiftUIExamples
  6. Click Add

Step 4: Resolving README Conflicts

The project currently has multiple README.md files in different pattern directories, which causes build conflicts:

  • Examples/ViewOnly/README.md
  • Examples/MVVM/Models/README.md
  • Examples/MVVM/ViewModels/README.md
  • Examples/MVVM/Views/README.md
  • Examples/MVVMC/README.md
  • Examples/MVVMC/Coordinators/README.md
  • Examples/TCA/README.md
  • Examples/Redux/README.md

Solution: Remove README files from the target membership:

  1. In Xcode's Project Navigator, select each README.md file
  2. In the File Inspector (right panel), under Target Membership
  3. Uncheck SwiftUIExamples
  4. Repeat for all README.md files

This prevents the build error: "Multiple commands produce README.md"

Step 5: Verify Build

  1. Select the SwiftUIExamples scheme
  2. Choose a destination (Mac, iOS Simulator, etc.)
  3. Press ⌘B to build
  4. Verify no errors appear

Step 6: Test the Implementations

Testing TCA Pattern

  1. Run the app (⌘R)
  2. From ImplementationSelectionView, click TCA (The Composable Architecture)
  3. Verify the 3-pane NavigationSplitView appears
  4. Test navigation:
    • Select different categories in the sidebar
    • Select items in the content list
    • Verify detail view updates correctly
  5. Test the Settings category:
    • Should show a custom settings form instead of item list
  6. Test state updates:
    • Toggle switches in settings
    • Verify changes persist while navigating

Testing Redux Pattern

  1. Run the app (⌘R)
  2. From ImplementationSelectionView, click Redux
  3. Verify the 3-pane NavigationSplitView appears
  4. Test navigation (same as TCA):
    • Category selection
    • Item selection
    • Detail view updates
  5. Test the Settings category
  6. Test state updates and action dispatch

Troubleshooting

Issue: TCA Import Not Found

Error: Cannot find 'ComposableArchitecture' in scope

Solution:

  • Ensure the TCA package was added correctly (Step 1)
  • Clean build folder: Product > Clean Build Folder (⇧⌘K)
  • Rebuild the project

Issue: Build Error - Multiple Commands Produce README.md

Error: Multiple commands produce .../README.md

Solution:

  • Follow Step 4 to remove README files from target membership
  • Alternatively, rename README files to be unique (e.g., TCA_README.md)

Issue: Files Not Showing in Xcode

Solution:

  • Files were created in the file system but not added to Xcode project
  • Follow Steps 2 and 3 to add files manually
  • Alternatively, drag-and-drop the folders into Xcode's Project Navigator

Issue: TCA Files Show Build Errors

Possible causes:

  1. TCA package not properly linked
  2. Minimum iOS version incompatible (TCA requires iOS 16.0+)
  3. Swift version mismatch

Solution:

  • Check project settings: Target > Build Settings > Deployment Target
  • Ensure iOS 16.0+ and macOS 13.0+
  • Verify Swift version is 5.9 or later

Platform Requirements

The TCA and Redux implementations require:

  • iOS 16.0+ / macOS 13.0+
  • Swift 5.9+
  • Xcode 15.0+
  • TCA 1.0.0+ (for TCA pattern only)

Documentation

After completing setup, refer to these documents for learning:

  • Documentation/TCA_Architecture.md - TCA pattern deep dive
  • Documentation/Redux_Architecture.md - Redux pattern deep dive
  • Examples/TCA/README.md - TCA implementation guide
  • Examples/Redux/README.md - Redux implementation guide
  • Documentation/CONCEPTUAL_OVERVIEW.md - Visual comparison of all patterns

Next Steps

Once setup is complete and tests pass:

  1. Read through the architecture documentation
  2. Explore the code with inline comments
  3. Compare TCA vs Redux patterns
  4. Try modifying the implementations to learn the patterns
  5. Experiment with adding new features using each pattern

Note: This is a teaching repository. The implementations prioritize clarity and pedagogy over production optimization. All code includes extensive comments explaining the "why" behind architectural decisions.