PhpStorm 2016.2 Help

Using Meteor

PhpStorm provides integration with the Meteor framework. Meteor support in PhpStorm involves:

  • Automatic recognition of Meteor projects by detecting the .meteor folder and excluding the .meteor/local folder from project.
  • Attaching the predefine Meteor library to the project automatically.
  • Coding assistance: syntax highlighting, code completion, resolving references.
  • Support of Spacebars via Handlebars with completion for if and each directives. There is also support for navigation between JavaScript source code and templates, allowing for easy navigation by using Ctrl+B to go to Declaration.
  • Running and debugging the server and the client sides of applications.

On this page:

Before you start

Make sure the Meteor and the Handlebars/Mustache plugins are activated. The Handlebars/Mustache enables PhpStorm to recognize Spacebars templates that are an extension of the Handlebars/Mustache templates. As a side effect, HTML files in Meteor projects are marked with the Handlebars/Mustache icon fileTypeHandlebars. The plugins are not bundled with PhpStorm, but they can be installed from the JetBrains plugin repository as described in Installing, Updating and Uninstalling Repository Plugins and Enabling and Disabling Plugins. Once enabled, the plugins are available at the IDE level, that is, you can use it in all your PhpStorm projects.

Installing Meteor

The installation procedure depends on the operating system you are using:

  1. To install Meteor on Windows, download the LaunchMeteor.exe installer at https://github.com/meteor/meteor/wiki/Preview-of-Meteor-on-Windows.
  2. To install Meteor on OSX (OSX 10.6 or higher is required) or Linux, type the following command:
    $ curl https://install.meteor.com | /bin/sh

Learn more at http://docs.meteor.com/.

Preparing to develop a Meteor application

To start your development, you need a PhpStorm project with the Meteor-specific structure. You can have an application stub that meets these requirements generated automatically or open an existing Meteor project in PhpStorm and configure Meteor support in it.

Generating a Meteor application stub

  1. In the left-hand pane, choose Meteor JS App.
  2. In the right-hand pane:
    1. In the Location text box, specify the path to the project folder where the project-related files will be stored.
    2. Specify the location of the Meteor executable file (see Installing Meteor).
    3. From the Template drop-down list, choose the sample to generate. To have a basic project structure generated, choose the Default option.
    4. In the Filename text box, type the name for the mutually related .js, .html, and .css files that will be generated. The text box is available only if the Default sample type is selected from the Template drop-dow list.

When you click Create, PhpStorm generates a skeleton of a Meteor application, including an HTML file, a JavaScript file, a CSS file, and a .meteor folder with subfolders. The .meteor/local folder, which is intended for storing the built application, is automatically marked as excluded and is not involved in indexing.

By default, excluded files are shown in the project tree. To have the .meteor/local folder hidden, click the viewMode button on the toolbar of the Project tool window and remove a tick next to the Show Excluded Files option.

PhpStorm also automatically attaches the predefined Meteor library to the project, thus enabling syntax highlighting, resolving references, and code completion. See Configuring JavaScript Libraries for details.

Meteor uses Spacebars templates that are an extension of the Handlebars/Mustache templates. PhpStorm recognizes Spacebars templates, but as a side effect marks HTML files in Meteor projects with the Handlebars/Mustache icon fileTypeHandlebars.

Enabling Meteor integration in an existing project

PhpStorm automatically detects Meteor projects by locating the .meteor folder. The .meteor/local folder, which is intended for storing the built application, is automatically marked as excluded and is not involved in indexing.

  1. Open the desired Meteor project in PhpStorm by choosing File | Open on the main menu or clicking Open on the Welcome Screen.
  2. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X. Expand the Languages&Frameworks node, and then click Meteor under JavaScript.
  3. On the Meteor page that opens:
    1. Check the location of the Meteor executable file or specify the path to it if PhpStorm has not detected the executable file automatically.
    2. To have PhpStorm involve the .meteor/local folder and its contents in indexing, clear the Automatically exclude ".meteor/local" directory on open project check box. By default, the check box is selected and the .meteor/local folder, which is intended for storing the built application, is automatically marked as excluded and is not involved in indexing.

      By default, excluded files are shown in the project tree. To have the .meteor/local folder hidden, click the viewMode button on the toolbar of the Project tool window and remove a tick next to the Show Excluded Files option.

    3. Make sure the Automatically import Meteor packages as external library check box is selected.
      • When the check box is selected, PhpStorm automatically imports the external packages from the meteor/packages file. As a result, PhpStorm provides full range coding assistance: resolves references to Meteor built-in functions, for example, check(true), and to functions from third-party packages, provides proper syntax and error highlighting, supports debugging with source maps, etc.
      • When this check box is cleared, PhpStorm does not automatically import the external packages from the meteor/packages file. As a result no coding assistance is provided. To improve the situation, open the meteor/packages file in the editor and click the Import packages as library link or run the meteor --update command.
      By default, the check box is selected.
    4. Click Apply to save the settings without leaving the dialog box.
  4. Check that PhpStorm has attached the Meteor library to the project:
    1. Click Libraries under JavaScript.
    2. On the JavaScript. Libraries page that opens, make sure the check box next to the Meteor project library in the Libraries list is selected.
    3. Click OK.

    Alternatively, choose Use JavaScript Library on the context menu of the editor and make sure a tick is set next to Meteor project library.

By default, excluded files are shown in the project tree. To have the .meteor/local folder hidden, click the viewMode button on the toolbar of the Project tool window and remove a tick next to the Show Excluded Files option.

PhpStorm also automatically attaches the predefined Meteor library to the project, thus enabling syntax highlighting, resolving references, and code completion. See Configuring JavaScript Libraries for details.

Importing Meteor packages

Besides the predefined Meteor library that ensures basic Meteor-specific coding assistance, you can download additional packages that are defined in the .meteor/local/packages file.

  1. Open the .meteor/local/packages file in the editor.
  2. Click the Import Meteor Packages link in the upper right-hand corner of the screen.
  3. In the dialog box that opens, specify the packages to download depending on the type of the application you are going to develop in your project.
    • Client
    • Server
    • Cordova: choose this option to import the packages that support development of Meteor applications for iOS and Android, see Meteor Cordova Phonegap Integration for details.

Running and debugging a Meteor application

With PhpStorm, you can debug both the client-side and the server-side of Meteor JavaScript code simultaneously using the PhpStorm debugger. The debugger also pauses at the breakpoints set in the sources stored in the /packages folder. This functionality is supported both for the client side and for the server side code.

Meteor applications are launched only through a dedicated run configuration. Technically, several Meteor projects that implement different applications can be combined within one single PhpStorm project. To run and debug these applications independently, create a separate run configuration for each of them with the relevant working directory. To avoid port conflicts, these run configurations should use different ports. In the Program Arguments field, specify a separate port for each run configuration in the format --port=<port_number>. The results are shown in the console and/or in the browser depending on the settings specified in the Browser / Live Edit tab, see Creating a run configuration below.

In the debugging mode, PhpStorm provides the Live Edit functionality which supports both automatic and manual upload of updated files on the server side. For the client side, Live Edit does not provide any way to apply the changes. For information on enabling and configuring the Live Edit functionality, see Live Editing of HTML, CSS, and JavaScript.

Creating a Meteor run configuration

Technically, PhpStorm creates separate run configurations for the server-side and the client-side code, but you specify all your settings in one dedicated Meteor run configuration.

  1. On the main menu, choose Run | Edit Configurations. In the Edit Configuration dialog box, that opens, click the Add New Configuration toolbar button add.png, and choose Meteor on the context menu.
  2. In the Configuration tab of the Run/Debug Configuration: Meteor dialog box that opens, specify the name of the configuration and the location of the Meteor executable file according to the installation (see Installing Meteor).

    Optionally, in the Program Arguments field, specify the command line additional parameters to be passed to the executable file on start up, if applicable. These can be, for example, --dev, --test, or --prod to indicate the environment in which the application is running (development, test, or production environments) so different resources are loaded on start up.

    In the Working Directory field, specify the folder under which the application files to run are stored. This folder must contain a .meteor folder in the root to be treated a Meteor project. By default, the field shows the path to the PhpStorm project root.

    Technically, several Meteor projects that implement different applications can be combined within one single PhpStorm project. To run and debug these applications independently, create a separate run configuration for each of them with the relevant working directory. To avoid port conflicts, these run configurations should use different ports. In the Program Arguments field, specify a separate port for each run configuration in the format --port=<port_number>.

  3. Switch to the Browser / Live Edit tab and configure the behaviour of the browser:
    1. To view the results of the client-side code execution during running and debugging, select the After Launch check box and choose the browser to open from the drop-down list.
    2. In the text box below, specify the URL address to open the application in. The default value is http://localhost:3000.
    3. To enable debugging the client-side code in the browser, select the With JavaScript Debugger check box.
    4. Click OK to save the run/debug configuration.

Configuring the update policy in the debugging mode

In the debugging mode, PhpStorm provides the Live Edit functionality which supports both automatic and manual upload of updated files on the server side. For the client side, Live Edit does not provide any way to apply the changes.

For information on enabling and configuring the Live Edit functionality, see Live Editing of HTML, CSS, and JavaScript.

The client-side code can be updated through the native Meteor hot code pushes functionality.

Configuring the update policy for the server side code

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X. Expand the Debugger node under Build, Execution, Deployment, and then click Live Edit. The Live Edit page that opens.
  2. In the Update area, configure the way changes made to the code during a debugging session are applied. This functionality is available only for the server-side code. To have the client side code updated, select the Enable Meteor 'Hot code push' check box on the Meteor page of the Settings dialog box.

    Note that an update will be performed only if none of the modified files have any syntax errors.

    • Auto in (ms): Choose this option to have the changes applied automatically at certain time interval and specify the delay in ms in the text box. This policy is not available for the client-side code of Meteor applications.
    • Manual: Choose this option to apply the changes manually by clicking the Update <run configuration name> JavaScript button update_icon or the Update <run configuration name> button update_icon on the toolbar of the Debug tool window.

      It is recommended that you choose this option because applying changes to the client-side code is not supported.

    • Restart if hotswap fails:

      With changes in HTML, CSS, and JavaScript on the client side, the contents of a Web page in the browser are updated without reloading. For NodeJS or Meteor applications, PhpStorm first tries to update the application incorporating the changes without restarting the NodeJS server.

      • Select this check box to have PhpStorm try restarting the server if the changes cannot be applied automatically. After the restart, PhpStorm brings you to the execution point where the problem took place.

        If even with this option chosen automatic upload still fails, tou will have to restart the server manually by clicking the Rerun <run configuration name> button rerun.

      • When the check box is cleared, PhpStorm just displays a pop-up window informing you about the failure and suggesting you to restart the server manually.

Configuring the update policy for the client side code

The client-side code can be updated through the native Meteor hot code pushes functionality. The functionality is enabled by default, to activate it:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X. Expand the Languages&Frameworks node, and then click Meteor under JavaScript.
  2. On the Meteor page that opens, select the Enable Meteor 'Hot code push' check box.

Running a Meteor application

  • To run an application, select the required run configuration from the list on the main tool bar and then choose Run | Run <configuration name> on the main menu or click the Run toolbar button run.png.

    If in the run configuration the browser is configured to open automatically upon application start, the browser opens showing the result of application execution. You can view the same result by opening the browser of your choice manually at the URL specified in the run configuration.

Debugging a Meteor application

  1. Set the breakpoints in the code, where necessary.
  2. To initiate a debugging session, select the required debug configuration from the list on the main tool bar and then choose Run | Debug <configuration name> on the main menu or click the Debug toolbar button debug.png. The Debug tool window opens showing two tabs: one for debugging the server-side code marked with icon_meteor and the other for debugging the client-side code marked with icon_javascript.
  3. Explore the suspended program and step through the program.
  4. Apply the changes to the application depending on the update policy defined in the run configuration:
    • To apply the changes to the client-side code, switch to the icon_javascript tab and click the Update <run configuration name> JavaScript button update_icon on the toolbar.
    • The changes to the server-side code are applied depending on the update policy defined in the run configuration:
      • If you have chosen manual upload, switch to the icon_meteor tab and click the Update <run configuration name> button update_icon on the toolbar.
      • If you have chosen automatic upload, updates to the server-side code are applied automatically. If automatic upload fails, restart the application by clicking Rerun <run configuration name> button rerun. Choosing the Restart if hotswap fails option on the Live Edit page may help: PhpStorm will attempt to restart the server automatically.

See Also

Last modified: 24 November 2016