As most probably do, I have create a full guide to install the entire environment needed to run Cordova/Ionic. It constantly evolves and usually makes big jumps every 6 to 12 months. The following guide is my latest file, tailored for Ionic v1, as I had to install Ionic v1 on a new Mac to continue support for the older app. However, I found the same guide also works for newer versions of Ionic:
This setup guide, and caveats, was used to install the latest Node/Cordova/Ionic on Mac OSX 10.15.5 Catalina. If you experience different issues throughout the various steps, please post your step number, what the issue was and how you got around it - so others can benefit too.
Mac 10.15.5 Catalina - Cordova install guide (July 15, 2020):
Android (Windows) install guide: Android (Windows) full environment install guide for Cordova/Ionic
===================================================
Lets get started
NOTE: The importance of installing base packages with Homebrew âbrewâ is key. Otherwise you begin running into access/write issues on certain directories which then forces you to try to use âsudoâ to install various packages which is itself a bigger problem and will create headaches. Use brew unless you really know what youâre doing.
PREREQUISITE - Install homebrew:
A: ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
B: brew update
1. Download and install Java SDK v1.8_xxx
A. Link: https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html
B. Cordova 10.x is still pinned to Java 1.8, you can't use a higher Java version
2. Install latest Apache ANT
A. "brew install ant"
3. Install intel universal mavericks
A. Link: https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwix4vrrms3qAhWjT98KHcdwDnsQFjABegQIARAB&url=https%3A%2F%2Fsourceforge.net%2Fprojects%2Fgit-osx-installer%2F&usg=AOvVaw0ab9OGLPy1CnM8PKUa9k_c)
4. Install highest Xcode for your OSX
A. start xcode and agree to licenses
5. Install latest node for
A. Ionic CLI greater than v1.7.16, use nodeJS@latest
B. If for whatever reason you still need Ionic cli older than v1.7.16, then you will need to pin your node install to nodeJS@6.11.0 (this will auto install npm 3.10.10)
- from here: https://nodejs.org/en/ (use the 6.11.0 package)
- after you install DO NOT update/upgrade node and npm to the latest versions
- Node versions > 6.11.0 are incompatible with ionic v1.7.16+
- However, as Ionic is up to v6x, there should be no reason for v1.7.16
"brew update"
"brew install node"
C. If you get an error creating symlinks, THEN perform the following
1. "sudo chown -R $(whoami) $(brew --prefix)/*"
2. "brew doctor"
3. "brew link node"
6. Install NVM
A. "brew install nvm"
B. IF you get errors on /usr/local/share/man/(man3/man5/man7) directories, THEN perform the following
1. "brew uninstall nvm"
2. "chmod u+w /usr/local/share/man/man3 /usr/local/share/man/man5 /usr/local/share/man/man7"
3. "brew install nvm"
Now that NODE/NVM are cleanly installed, we move over to NPM for the
remainder of installs. You SHOULD NOT have to use âsudoâ for any npm
install commands. If you do, see opening notes and continue at your
own risk. âsudo npm install -g XXXXâ can open up a can of worms for
you. After each NPM package install I recommend saving to a
POST_INSTALL.log file any package WARN/Deprecated notices for future
reference. I did this and it saved my butt on a few things
7. Install gulp-cli:
A. "npm install gulp-cli -g". // global install
8. Install gulp
A. To install to project only: "npm install --save-dev gulp"
B. OR to install globally: "npm install -g gulp"
9. Install Cordova:
A. Local install only: "npm install cordova@latest"
B. Or global install: "npm install -g cordova@latest" (preferred (you MAY need 'sudo' here)
10. Install Ionic-CLI:
A. "npm install -g @ionic/cli"
11. Install ios Simulator module:
A. "npm install -g ios-sim"
12. Install ios-deploy - with NOTES
A. "npm install -g ios-deploy"
B. IF you get "xcode-select: error tool 'xcodebuild' requires xcode" type error
THEN:
1: "xcode-select âinstall" // might already be installed
2: "sudo xcode-select --switch /Library/Developer/CommandLineTools"
3: "sudo xcodebuild -license accept" // might already be accepted
4. "npm install -g ios-deploy"
C. IF this doesn't work and you are still getting the same error, then the xcode-select path probably needs to be changed:
1. "xcode-select -p" // probably outputs '/Library/Developer/CommandLineTools'
2. And your xcode is installed elsewhere
3. "sudo xcode-select --reset" // this will reset your path
4. "xcode-select -p" // should output '/Applications/Xcode.app/Contents/Developer'
5. "npm install -g ios-deploy"
D. Additional errors? If you get errors on /usr/local/share/man/(man3/man5/man7) directories, THEN perform:
1. "chmod u+w /usr/local/share/man/man3 /usr/local/share/man/man5 /usr/local/share/man/man7"
2. IF your OSX is over 10.11 El Capitan OSX, THEN you will MAY need to use:
"npm install -g ios-deploy --unsafe-perm=true"
13. Run NPM Audit to fix any errors
A. "npm audit fix" - if necessary, add "--force"
14. Update existing modules, to eliminate potential dependency issues:
A. "npm update -g fsevent@latest"
B. "npm update -g graceful-fs@latest"
C. "npm update -g chokidar@latest"
15. Install cordova resources:
A. "npm install -g cordova-res" //cordova/ionic resource files for icon/splash images
B. "npm install -g native-run" //provides support to launch app direct to simulators
16. Will your project need Facebook4 and/or FirebaseX plugins, then you WILL need cocoapods
A. "sudo gem install cocoapods"
B. "pod setup"
17. Create a project : 'ionic start appName tabs'
NOTE: if you are still needing an Ionic v1 project, go to #18
A. this should auto add: 'ionic Cordova platform add ios' for you if it does not, you will need to execute that command manually
1. "cd $PATH/<project-name>"
2. "ionic cordova platform add ios"
B. build your base project
1. "cd $PATH/<project-name>"
2. "ionic cordova build ios"
C. deploy your first project
1. "ionic Cordova run iOS"
18. **For Ionic v1 projects ONLY**. As of ionic/tool-kit 3.2.4 (Sept 2020), Gulp was upgraded from 3.9.1 to 4.0.2 - this causes breaking changes in v1 projects. The following few items need to happen:
A. "npm update -g gulp-sass@latest (to gulp-sass v5)
B. "npm install --save-dev sass@latest (sass compiler)
C. Create a project : 'ionic start myApp tabs --type=ionic1 --no-link'
D. this should auto add: 'ionic Cordova platform add ios' for you if it does not, you will need to execute that command manually
1. "cd $PATH/<project-name>"
2. "ionic cordova platform add ios"
E. The ionic v1 project auto installs a `gulpfile.js` to the root of your project, the file is formatted for gulp v3.9.1, it will need to be modified to work with gulp v4.x. See `gulpfile.js` changes below.
F. build your base project
1. "cd $PATH/<project-name>"
2. "ionic cordova build ios"
G. deploy your first project
1. "ionic Cordova run iOS"
If you have compiled without errors then you are good to go. Next begin building your real project by installing all the necessary plugins and testing on real iOS device or simulators. For true beginners below are some tips on how to get started deploying apps in the Mac world:
Install all necessary cordova plugins - the repository can be found at web address above: www.nmpjs.com
You can deploy apps to the iOS Simulator, but to deploy apps directly to phones you will need:
- Apple Developer Account ($100 fee) http://developer.apple.com - you will need to sign your apps with your developer ID.
- I donât recall, but I donât think you canât even compile an app to the simulator, let alone to a real phone, without a developer ID. Once you create your developer ID account, you then add in âauthorized devicesâ to your online developer account
- you would add your iPhones, or other iPhones UUIDs to your developer account
- then attach that device to your MacâŚand then that phone will appear in Xcode which will allow you to deploy apps to ONLY those devices listed in your developer account (apple sucks this way)
- In Xcode, in your project link/sign your project with your developerID
- You may find your version of Xcode still wonât deploy your app to your phone (step #3) because it doesnât recognize the phone type or latest iOS on that device, here is a thread to help you understand what you must do if this happens:
- xcode8 - Model is running iOS 10.2 (14C92), which may not be supported by this version of Xcode - Stack Overflow
- and you can get the latest Device files from one or both of these two GitHubs:
A: GitHub - filsv/iOSDeviceSupport: Xcode iPhoneOS (iOS) DeviceSupport files (6.0 - 16.5)
B: GitHub - iGhibli/iOS-DeviceSupport: This repository holds the device support files for the iOS, and I will update it regularly.
Happy coding!
PS: I will periodically update this guide as it evolves and/or others make relevant contributions.
==========================================
For Ionic v1 projects, the gulpfile.js is preformatted for gulp v3.9.1, it will need to be modified to work with gulp v4.x (ie: 4.0.2):
Default installed gulpfile.js:
var gulp = require('gulp');
var sass = require('gulp-sass');
var cleanCss = require('gulp-clean-css');
var rename = require('gulp-rename');
var paths = {
sass: ['./scss/**/*.scss']
};
gulp.task('default', ['sass']);
gulp.task('sass', function(done) {
gulp.src('./scss/ionic.app.scss')
.pipe(sass())
.on('error', sass.logError)
.pipe(gulp.dest('./www/css/'))
.pipe(cleanCss({
keepSpecialComments: 0
}))
.pipe(rename({ extname: '.min.css' }))
.pipe(gulp.dest('./www/css/'))
.on('end', done);
});
gulp.task('watch', ['sass'], function() {
gulp.watch(paths.sass, ['sass']);
});
There are only a few changes, they are subtle, but the gulpfile.js needs to be modified to look like this:
var gulp = require('gulp');
var sass = require('gulp-sass')(require('sass')) ;
var cleanCss = require('gulp-clean-css');
var rename = require('gulp-rename');
var paths = {
sass: ['./scss/**/*.scss']
};
gulp.task('sass', function(done) {
gulp.src('./scss/ionic.app.scss')
.pipe(sass())
.on('error', sass.logError)
.pipe(gulp.dest('./www/css/'))
.pipe(cleanCss({
keepSpecialComments: 0
}))
.pipe(rename({ extname: '.min.css' }))
.pipe(gulp.dest('./www/css/'))
.on('end', done);
});
gulp.task('watch', function () {
gulp.watch(paths.sass, gulp.series('sass'));
});
gulp.task('default', gulp.series('sass','watch'));
