Running a Meteor App on iOS, or Android

Meteor is famous for giving you the power to develop reactive web applications with fewer lines of code and in less time. But not many developers know that you also can develop cross-platform Meteor apps. Or, in simpler words, your Meteor apps can run on the web, on iOS, and on Android devices.

This guide shows you how to run your application on an iPhone or iPad. You also can take this guide and replace the word ios with android and you should be able to install your app on an Android device as well.

Creating a Sample Application

Obviously, you need something you can run on your device. We will install one of the provided sample apps, which come with every Meteor installation. The sample app we use is called Local Market. It is the nicest looking of the sample projects.

Open a terminal window and in your projects folder (mine is ~/projects) enter the following commands.

  meteor create --example localmarket
  cd localmarket
  meteor

This should print the following to the console:

  => App running at: http://localhost:3000/

Point your browser to the given URL http://localhost:3000. You should see the app running in the browser.

Now that we have something we can push to our device, let’s see if we can run it on the iOS Simulator first. Press control-c in the terminal to stop our app. Then check whether you have the necessary platform installed. You can do this with the following command:

  meteor list-platforms

At the time of this writing Meteor supports four platforms: browser, server, ios, and android.

The two platforms browser and server are installed with every Meteor installation and cannot be removed. For mobile applications Meteor also supports two more platforms: ios and android.

Now, if you do not see your target platform, you need to install it. This is easily done with the following command:

  meteor add-platform ios

If you get an error, it is probably because the necessary SDK is not installed on your computer. Again, Meteor has you covered:

  meteor install-sdk ios

Please note that you can install the iOS SDK on OS X only. If you run Linux or Windows you are left behind. This is not Meteor’s fault. The iOS SDK is just not available on these operating systems. Address any complaints to Apple.

When you have managed to install the SDK and the platform support you should be able to run the app on the simulator. (Each SDK, iOS and Android comes with a simulator and should be available after you install the SDK.)

We used the command meteor run earlier to start our sample application. The run command also accepts a target. It must be one of the following:

  • ios
  • ios-device
  • android
  • android-device

The targets ios and android will start one of the simulators and run your application on it. Go ahead and try it:

  meteor run ios

If all goes well you should see a message like this on your console:

  …
  => Started app on iOS Simulator.
  …

Please notice one thing. It might be possible that the simulator window is not coming to the front, although it is running in the background. Use your application switcher to bring it to the front (command-tab on OS X).

This was a lot of introductory text. Now we will get into the nitty-gritty of running the application on an actual device. You do this by passing in a different target to the meteor run command:

  meteor run ios-device

Please do not expect that the above command will run right off-the-cuff. It probably won’t, unless you have developed apps in the past using this device.

The first run will try to open Xcode, Apple’s integrated development environment (IDE). If you see the following dialog, just press Install and allow Xcode to run with the requested permissions.

Xcode dialog missing components

If you do not have any device connected to your computer, you will see the following dialog pop up. To resolve this, connect your iOS device via USB.

Xcode dialog no supported device available

Run the localmarket app again, now with the connected device. You can start the app in Xcode, right from the menu bar. Next to the run button (the black triangle) you should see the app’s name (localmarket) and the selected target. Make sure the target is iOS Device and not one of the simulators.

Xcode menu bar with run button and Meteor app Local Market

It is very likely that you will run into yet another problem. Every time an app is copied to a device the app’s code will be signed with your developer certificate. If this certificate is not known to Xcode, it will try to download it from the iOS Developer Center.

Xcode dialog code sign failure

If you already have an Apple Developer Account and you have entered your account credentials in the Xcode settings, then you can click on the Fix Issue button.

In the past you had to sign up for the iOS Developer Program, if you wanted to deploy your app to a real device. Not anymore so. Since Xcode 7, you can use free provisioning for deployment. You need an Apple ID and a lightning cable to see your app runnning on a physical device.[1]

When you want to publish to the App Store, you will have to get an iOS Developer Certificate. This will take a $99 morsel from your wallet.

If you have not done so already, you need to enter your iOS Dev Center credentials into the accounts settings of Xcode (Xcode > Preferences… > Accounts). Fill in your Apple ID and your password. This will allow Xcode to download your certificate and the keys.

Now, try to run the app again. This time, if you see the Fix Issue button, click on it. Xcode will try to solve all code signing and provisioning issues it has. For me it worked, except for one minor issue I will talk about briefly below. Should you have further issues, you can look at Apple’s article on Launching Your Apps On Devices.

Another problem which might arise when you want to deploy your app to a real device is that you need to accept a change in the terms or license agreement for your account. In the past this was not easily spotted but nowadays, Xcode will show a dialog with the corresponding warning message. Normally this happens when Xcode needs to access your iOS Dev Center Account but cannot because login is halted until you have agreed to the new terms or license.

Xcode dialog iOS license agreement

If you see this, log into Apple’s Developer Center and accept the change of terms, or whatever it is. After that Xcode should be able to go forward and resolve the issues.

Now you should have the sample app running on your device. But you will notice a small message at the bottom of your iDevice: Trying to connect.

The local market app cannot connect to server

This is because the mobile app wants to talk to the application on the server. The app is trying to connect, but does not know where the server application is running. We can pass this information to the meteor run command.

  meteor run ios-device --mobile-server=https://YOURAPPNAME.meteor.com

Obviously you need to deploy your application to Meteor.com first. You can do this with your Meteor development account and the command meteor deploy YOURAPPNAME.meteor.com.

In the screenshot below you will see that the *Trying to connect * message has disappeared. Instead a NEWS item gets displayed in the middle of the screen. This information is not in the app’s code, but is coming from the server.

Meteor app Local Market connected to the server application

This was a rather long post, but there are quite a few snags one can strike when deploying to a real device. I’m sure that there are also many more. Let me know when you encounter problems I have not covered in this tutorial. I will be happy to help, whenever you require it.


  1. Thanks Michael for pointing this out to me.


Jo's Profile ImageWritten by Jo Meenen who lives and works in Frankfurt building digital doodah. Stalk him on Twitter

ImpressumDatenschutz