Installation

SwiftStruct is a production-ready starter kit for building iOS apps with SwiftUI, Firebase, and a Next.js admin dashboard. This guide will walk you through the complete installation and setup process.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js (version 18 or higher)
• npm
• Xcode (latest version recommended)
• Git
• A GitHub account (for repository setup)

Clone the repository

Start by cloning the SwiftStruct repository to your local machine:

git clone https://github.com/phoqe/swiftstruct.git my-app-name
cd my-app-name

Replace my-app-name with your desired project directory name.

Run the setup script

The interactive setup script will configure your project automatically:

npm run setup

What the setup script does

The setup script will guide you through the initial project configuration by prompting you for:

• Project name: Use kebab-case format (e.g., my-app, awesome-project)
• Display name: Human-readable name for your app (e.g., My App, Awesome Project)
• Bundle identifier: Reverse domain notation (e.g., com.company.myapp, com.yourname.project)

After collecting this information, the script automatically:

• Installs all npm dependencies
• Renames files and updates configurations throughout the project
• Creates a .env file from .env.example template
• Configures git remotes:
  • Renames origin to template (preserves connection to SwiftStruct for updates)
  • Disables push access to the template repository (prevents accidental pushes)
• Sets up your GitHub repository and pushes all branches
• Commits all setup changes and pushes to your repository

Setup your GitHub repository

The setup script will prompt you to configure your GitHub repository with two options:

Option 1: Create new repository using GitHub CLI

If you have the GitHub CLI (gh) installed and authenticated, the setup script can create a new repository for you automatically.

Option 2: Enter existing repository URL

If you've already created a repository on GitHub, simply enter the repository URL when prompted (e.g., https://github.com/username/repo.git).

The setup script will automatically:

• Add your repository as the origin remote
• Create local branches from all template branches
• Push all branches and tags to your new repository

This ensures your repository maintains the complete branch structure from the template, making it easier to pull updates in the future.

Open in Xcode and build

Now that your project is configured and updated, it's time to open it in Xcode:

1. Open the project: Navigate to the iOS project folder and open the .xcodeproj or .xcworkspace file in Xcode

2. Wait for SPM packages: Xcode will automatically detect and install all Swift Package Manager (SPM) dependencies. This may take a few minutes depending on your internet connection

3. Select a target: Choose either a simulator or a connected device from the device dropdown in Xcode's toolbar

4. Build and run: Press Cmd + R or click the Run button to build and run your app

If the build succeeds and your app launches successfully, you've completed the basic installation.

Complete setup

While your app can now build and run, you'll need to complete additional configuration for full functionality:

• Firebase Configuration: Set up Firebase projects and configure authentication, Firestore, storage, and cloud functions. See our Firebase guides for detailed instructions.
• Environment Variables: Configure all required environment variables in your .env file
• Next.js Admin Dashboard: Set up and deploy the admin dashboard
• Third-party Services: Configure optional integrations like RevenueCat, Sentry, and Xcode Cloud

Visit the specific documentation pages for each service to complete the setup process.

Updating from the template

SwiftStruct is regularly updated with new features, bug fixes, and improvements. To pull the latest updates into your project:

Fetch the latest changes

First, fetch the latest changes from the template repository:

git fetch template

View available updates

Before merging, you can review what updates are available:

git log HEAD..template/master --oneline

Review detailed changes (optional)

To see exactly what files have changed:

git diff HEAD..template/master --stat

Merge the updates

Once you're ready, merge the updates into your project:

git merge template/master

If you encounter merge conflicts, resolve them manually in your editor, then complete the merge:

git add .
git commit

Install updated dependencies

After merging, make sure to install any new or updated dependencies:

npm install

Cherry-picking specific updates

If you prefer to selectively apply updates instead of merging everything, you can cherry-pick individual commits:

git cherry-pick <commit-hash>

This is useful when you want to apply only specific features or fixes without merging all changes from the template.