https://github.com/apparata/bootstrapp
A macOS application for generating initial boilerplate primarily for Swift packages and Xcode projects.
https://github.com/apparata/bootstrapp
app macos
Last synced: about 2 months ago
JSON representation
A macOS application for generating initial boilerplate primarily for Swift packages and Xcode projects.
- Host: GitHub
- URL: https://github.com/apparata/bootstrapp
- Owner: apparata
- License: other
- Created: 2019-12-08T20:31:24.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2026-04-20T21:22:05.000Z (2 months ago)
- Last Synced: 2026-04-20T22:38:20.089Z (2 months ago)
- Topics: app, macos
- Language: Swift
- Homepage:
- Size: 18 MB
- Stars: 43
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Bootstrapp
The main purpose of the Bootstrapp application for macOS is to generate boilerplate for iOS and macOS apps and Swift packages from templates. However, the template system is general enough for just about any type of boilerplate generation.
## License
The Bootstrapp app for macOS is released under the MIT license. See the `LICENSE` file in the repository for details.
However, Bootstrapp depends on other open source software (both first-party and third-party), subject to their own respective licenses. See the `ATTRIBUTIONS` file for details. Most notably, [XcodeGen](https://github.com/yonaskolb/XcodeGen) is used for generating Xcode project files and [Splash](https://github.com/JohnSundell/Splash) is used for generating syntax highlighted Swift code.
### Table of Contents
> ⚠️ This documentation is a work in progress.
- [Installing Bootstrapp](#installing-bootstrapp)
- [System Requirements](#system-requirements)
- [Pre-built Binaries](#pre-built-binaries)
- [Using Bootstrapp](#using-bootstrapp)
- [Templates](#templates)
- [Template Types](#template-types)
- [Structure of a Template](#structure-of-a-template)
- [Bootstrapp.json](#bootstrap-json)
- [Template Language](#template-language)
- [Substitutions](#substitutions)
- [Conditionals](#conditionals)
- [Conditional Expression](#conditional-expression)
- [Loops](#loops)
- [Longer Example](#longer-example)
## Installing Bootstrapp
Bootstrapp is a regular macOS app and is installed by dragging the app bundle to the `/Applications` folder, as usual.
### System Requirements
Bootstrapp was built using SwiftUI, which requires **macOS 10.15 Catalina** or later.
### Pre-built Binaries
With every release, a pre-built app binary along with some example templates will be attached to the assets section of the release entry here on GitHub.
Simply go to the [releases page](https://github.com/apparata/Bootstrapp/releases) and expand the **Assets** section of the release you want to install. There you will find the `Bootstrapp.app.zip` and `Templates.zip` files. The app binary is signed for distribution and notarized by Apple.
## Using Bootstrapp
**Step 1:** Drag a folder containing one or more templates onto the app window. The application will recursively look for any folder that contains a `Bootstrapp.json` file.
**Step 2:** Select a template in the sidebar on the left.
**Step 3:** Fill out the required fields of the form that appears.
**Step 4:** Press the hammer icon in the upper right corner to generate the boilerplate.
## Templates
### Template Types
There are three types of templates:
1. General
2. Swift Package
3. Xcode Project
**General** templates are not processed in any specific ways during the template instantiation. Files and folders will simply be copied from the `Content/` folder to the output folder, only being subjected to parameter substitutions.
**Swift Package** templates are currently not processed in any specific ways either, but they may be in the future. Currently, the only difference is that they will be sorted in their own group in the sidebar and will be represented by a specific sidebar icon.
**Xcode Project** templates are processed just like the other templates with parameter substitutions, but they also contain an `XcodeProject.yml` file that specifies how the Xcode project file should be generated. The Xcode project file is generated by [XcodeGen](https://github.com/yonaskolb/XcodeGen) and the file format is thus the XcodeGen [project specification file format](https://github.com/yonaskolb/XcodeGen/blob/master/Docs/ProjectSpec.md).
#### Meta Templates
There are also templates for generating boilerplate for other templates. These are called _Meta Templates_. There's one meta template type per regular template type.
### Structure of a Template
A Bootstrapp template has the following basic structure:
```text
── Template/
├─ Bootstrapp.json
├─ Bootstrapp.md
├─ Content/
│ ├─
│ └─ [XcodeProject.yml]
└─ Preview/
├─ 1.png
├─ 2.png
⋮
└─ n.png
```
The main template specification is in the `Bootstrapp.json` file.
To provide information about the template, such as code examples or other documentation, add a `Bootstrapp.md` file. It will be shown in the Bootstrapp window for the template below the parameters form.
Any file or folder in the `Content/` folder will be copied to the output folder as part of the generation process.
The `Preview/` folder contains images (600x400 pixels) showcasing what the results will look like. In the case of an app template, it would be a good idea to use screenshots of the app, but any image can be used.
### Bootstrapp.json
This is the main template specification file.
#### Top Level JSON Properties
| Name | Value |
|-----------------------|---------------------------------------------------------------------------|
| specificationVersion | The version of the Bootstap.json file format itself, e.g. `"1.0.0"`. |
| templateVersion | The version of this particular template, e.g. `"1.0.0"`. |
| id | A unique identifier for this template. Also the name, for now. |
| type | One of `"Swift Package"`, `"Xcode Project"`, and `"General"`. |
| description | A brief description of the template, shown at the top of the detail page. |
| outputDirectoryName | The name of the output directory. **Not** the path, just the directory name. Will be processed by substitution engine, e.g. `"<{LIBRARY_NAME_}>"`. |
| substitutions | Non-user-configurable text substitutions as dictionary, e.g. `["DOT": "."]` |
| parameters | User configurable text substitutions. Shown as form in template user interface. |
| parametrizableFiles | An array of regular expressions. File with names that match at least one of the regular expressions will be processed by the text substitution engine. Non-matching files will not. |
| includeDirectories | An array of conditions with expressions that when true will lead to the conditional inclusion of the specified directories. **(Optional)** |
| includeFiles | An array of conditions with expressions that when true will lead to the conditional inclusion of the specified files. **(Optional)** |
#### Example: Swift Package Template
```json
{
"specificationVersion": "1.0.0",
"templateVersion": "1.0.0",
"id": "Library Swift Package",
"type": "Swift Package",
"description": "Use this template to quickly set up new static library Swift packages, complete with e.g. MIT license file, SwiftLint configuration, Jazzy documentation build script.",
"outputDirectoryName": "<{LIBRARY_NAME}>",
"substitutions": {
"DOT": "."
},
"parameters": [
{
"name": "Library Name",
"id": "LIBRARY_NAME",
"type": "String",
"validationRegex": "^[A-Za-z0-9_]+$"
},
{
"name": "Copyright Holder",
"id": "COPYRIGHT_HOLDER",
"type": "String",
"default": "Apparata AB"
},
{
"name": "Docs Author URL",
"id": "DOCS_AUTHOR_URL",
"type": "String",
"default": "https://apparata.se"
},
{
"name": "License",
"id": "LICENSE_TYPE",
"type": "Option",
"default": 0,
"options": [
"MIT",
"BSD",
"Apache 2",
"Zlib",
"Unlicense",
"None"
]
},
{
"name": "Add Executable Target",
"id": "ADD_EXECUTABLE_TARGET",
"type": "Bool",
"default": false
},
{
"name": "Executable Name",
"id": "EXECUTABLE_NAME",
"type": "String",
"validationRegex": "^[A-Za-z0-9_]+$",
"dependsOn": "ADD_EXECUTABLE_TARGET"
},
{
"name": "Add GitHub test action",
"id": "ADD_GITHUB_TEST_ACTION",
"type": "Bool",
"default": false
},
{
"name": "Init git repo",
"id": "GIT_INIT",
"type": "Bool",
"default": false
}
],
"parametrizableFiles": [
"LICENSE",
".*\\.md",
".*\\.swift",
".*\\.h",
".*\\.m",
".*\\.mm",
".*\\.storyboard",
".*\\.xib",
".*\\.plist",
".*\\.json",
".*\\.yml",
".*\\.txt",
".*\\.sh"
],
"includeDirectories": [
{
"if": "ADD_EXECUTABLE_TARGET",
"directories": [
"Sources/<{EXECUTABLE_NAME}>"
]
},
{
"if": "ADD_GITHUB_TEST_ACTION",
"directories": [
"<{DOT}>github"
]
},
{
"if": "GIT_INIT",
"directories": [
"<{GIT}>git"
]
}
],
"includeFiles": [
{
"if": "(LICENSE_TYPE != 'Unlicense') and (LICENSE_TYPE != 'None')",
"files": [
"LICENSE"
]
},
{
"if": "LICENSE_TYPE == 'Unlicense'",
"files": [
"UNLICENSE"
]
}
]
}
```
## Template Language
### Substitutions
#### Simple Value
Input:
```text
This is a <{ thing }>
```
Parameters:
```Swift
"thing": "test"
```
Output:
```text
This is a test
```
#### Simple Value with Transformer
Input:
```text
This is an uppercase <{ #uppercased thing }>
```
Parameters:
```Swift
"thing": "Test"
```
Output:
```text
This is an uppercase test
```
#### Built-in Transformers
- `#lowercased`
- `#uppercased`
- `#uppercasingFirstLetter`
- `#lowercasingFirstLetter`
- `#trimmed`
- `#removingWhitespace`
- `#collapsingWhitespace`
### Conditionals
#### `if ...` ... `end`
Input:
```text
<{ if isMonday }>
This is only kept if isMonday is true.
<{ #uppercased whatever }>
Some more text.
<{ end }>
```
Parameters:
```Swift
"whatever": "Test",
"isMonday": true
```
Output:
```text
This is only kept if isMonday is true.
TEST
Some more text.
```
#### `if ...` ... `else` ... `end`
Input:
```text
<{ if thing }>
Thing is true.
<{ else }>
Thing is false.
<{ end }>
```
Parameters:
```Swift
"thing": true
```
Output:
```text
Thing is true.
```
### Conditional Expression
The conditional expression can be more complicated than a simple boolean value. Here is the complete grammar for the conditional expression:
```text
expr := term ('or' term)*
term := factor ('and' factor)*
factor := 'not'? ( statement | '(' expr ')' )
statement := terminal ( ('==' | '!=') string )?
string := ('"' | ''') character* ('"' | ''')
```
#### Example: `if not ...`
Input:
```text
<{ if not isMonday }>
Today is not Monday.
<{ end }>
```
Parameters:
```Swift
"isMonday": false
```
Output:
```text
Today is not Monday.
```
#### Example: `if not (... and ...)`
Input:
```text
<{ if not (isMonday and isRaining) }>
Today is not Monday and it is not raining.
<{ else }>
Today is either Monday or it is raining.
<{ end }>
```
Parameters:
```Swift
"isMonday": true,
"isRaining": true
```
Output:
```text
Today is either Monday or it is raining.
```
#### Example: `if ... == "..."`
Input:
```text
<{ if license == "MIT" }>
This is the MIT license.
<{ end }>
```
Parameters:
```Swift
"license": "MIT"
```
Output:
```text
This is the MIT license.
```
### Loops
#### `for ... in ...`
Input:
```text
Here are some types of fruits:
<{ for fruit in fruits }>
Fruit name: <{ fruit }>
<{ end }>
```
Parameters:
```Swift
"fruits": [
"banana",
"orange",
"pineapple",
"pear"
]
```
Output:
```text
Here are some types of fruits:
Fruit name: banana
Fruit name: orange
Fruit name: pineapple
Fruit name: pear
```
### Longer Example
Input:
```text
This is a test.
<{ #lowercased whatever }>
So is this.
<{ stuff }>
Whatever
<{ if potato }>
Only if potato is true.
<{ if cucumber }>
Only if both potato and cucumber are true.
<{ end }>
<{ end }>
Here are some types of fruits:
<{ for fruit in fruits }>
Fruit name: <{ fruit }>
<{ end }>
Here they are again:
<{ for fruit in fruits }>Fruit name: <{ car }> <{ end }>
```
Parameters:
```Swift
"whatever": "[WHATEVER]",
"stuff": 1337,
"potato": true,
"cucumber": 1,
"fruits": [
"banana",
"orange",
"pineapple",
"pear"
]
```