Natrium configuration

June 8, 2022 · View on GitHub

.natrium.yml

Example

---

settings:
  stringType: "StaticString"

environments:
  - Staging
  - Production

natrium_variables:
   DeeplinkUrlSchemeName:
     Staging: "natriumexample_staging"    
     Production: "natriumexample"    

xcconfig:
    PRODUCT_BUNDLE_IDENTIFIER:
        Staging: com.esites.app.staging
        Production:
            Adhoc,Debug: com.esites.app.production
            Release: com.esites.app
    DEEPLINK_URL_SCHEME: "#{DeeplinkUrlSchemeName}"

variables:
    testVariableDouble:
        Staging: 1.1
        Production: 5.5
    testVariableString:
        Staging,Production:
            Debug: "debugString"
            Adhoc: "adhocString"
            Release: "releaseString"
    testVariableBoolean: false
    testVariableInteger: 125
    testArray:
    	Staging: 
    		- StagingFoo
    		- StagingBar
    	Production:
    		- ProductionFoo
    		- ProductionBar
    triggerError: "#error"
    deeplinkUrlSchemeName: "#{DeeplinkUrlSchemeName}"
    apiKey:
        Staging: "api_key_staging"
        Production: "#env(API_KEY_PRODUCTION)"

plists:
    "NatriumExampleProject/Info.plist":
        CFBundleDisplayName:
            Staging: App_staging
            Production: App
    "NatriumExampleProject/App.entitlements":
        "aps-environment":
            "*":
                Debug: "development"
                Release: "production"

files:
    Firebase/GoogleService-Info.plist:
        Dev: Firebase/GoogleService-Info_DEV.plist
        Staging: Firebase/GoogleService-Info_STAGING.plist
        Production: Firebase/GoogleService-Info_PRODUCTION.plist

target_specific:
    NatriumExampleProject2:
      variables:
          testVariableString: "Target #2"
      infoplist:
        CFBundleDisplayName: "App #2"
        
appicon:
    original: icon.png
    appiconset: NatriumExampleProject/Assets.xcassets/AppIcon.appiconset/
    all_sizes: false
    idioms: 
        - ipad
        - iphone
    ribbon:
        Production: ""
        Staging: "STAGING"

launch_screen_versioning:
    path: NatriumExampleProject/Base.lproj/LaunchScreen.storyboard
    labelName: LaunchScreenVersionLabel
    enabled:
        Staging: true
        Production: false

Key	Type	Description
environments	Array	Which environments does your project support
settings	Dictionary `{stringType: String}`	Define the string type (defaults to `"String"`)
xcconfig	Dictionary*	Build settings per environment / configuration
variables	Dictionary*	Custom variables per environment / configuration (written in Natrium.swift). See Special variables for more advanced variable types.
plists	Dictionary¹*	Individual plist file locations with corresponding environment / configuration values. A `null` value will delete the specific key from the plist file. An `array` will also work here.
files	Dictionary²*	Overwrite a specific file per environment / configuration. Relative to path the project directory.
target_specific	Dictionary³*	Target specific values. The first key of this dictionary is the target name, the value of that dictionary is the same as the values shown above (`infoplist`, `xcconfig`, `variables`, `files`, `appicon`, `natrium_variables`). This way you can make target specific modifications per build.
appicon	App-icon	Place a ribbon on your app-icon
launch_screen_versioning	Launch screen versioning	Launch screen settings

Dictionary¹*:
The plists dictionary's first key is the filepath, the value should be of a Dictionary* type.

Dictionary²*:
The files dictionary's first key is the filepath, the value should be of a Dictionary* type.

Dictionary³*:
The target_specific dictionary's first key is the target name, the value should be of a Dictionary* type.
⚠️ A target specific variable must be set in the variables field, so it can only overwrite existing variables.

Dictionary* = All the dictionaries support different types of notations:

Every environment / configuration will use that value:
```
key: value
```

Differrent values per environment

key:
    Staging: value1
    Production: value2

Differrent values per environment and configuration

key:
    Staging:
        Debug: stagingDebugValue
        Release: stagingReleaseValue    
    Production:
        Debug: productionDebugValue
        Release: productionReleaseValue

Differrent values per configuration

key:
    Staging,Production:
        Debug: debugValue
        Release: releaseValue

# or use an asterisk (*) to define all the environments: 

key:
    "*":
        Debug: debugValue
        Release: releaseValue

App icon

The app-icon setting has 4 options:

Key	Type	Description
original	String *	The relative path (according to your project) of the original icon file (preferably a size of 1024x1024). Which can be used to place the ribbon on top of it.
appiconset	String *	The relative path (according to your project) of the `AppIcon.appiconset` folder, to store the icons in
ribbon	String *	The text that should be placed in the ribbon. An empty string (`""`) would remove the ribbon
idioms	Array *	What idioms should be used. Array (`ipad`, `iphone`, `watch`, `car` or `mac`)
all_sizes	Boolean	(Default: `true`) Since Xcode14 a single 1024x1024 icon is sufficient instead of all the separate icons sizes. By default Natrium will generate all individual app icons. If you would like to generate a single universal app icon (1024x1024) set this value to `false`. (For iOS and watchOS only)

This option fills your App icon asset catalog with perfectly resized icons for each device.
Completely with a custom ribbon at the bottom of the icon. All you need is a hi-res app icon.

For git convenience add Project/Resources/Assets.xcassets/AppIcon.appiconset to your .gitignore file.

Launch screen versioning

Alter a UILabel in the LaunchScreen storyboard to show the current app version.

Arguments:

Key	Type	Description
path	String *	Relative path to the LaunchScreen.storyboard file
labelName	String *	The accessability label value of the UILabel in that storyboard
enabled	Boolean *	Disabling this will empty the UILabel

Special variables

Key	Description
`#error`	If you want Natrium to throw an error.
`#env(KEY)`	If you want to use a environment variable (from a CI system for instance), you can use this (e.g. `"#env(API_KEY_PRODUCTION)"`).
`#{KEY}`	To be replaced by a `natrium_variable` value