Remote JavaScript debugging with WebStorm and PHPStorm

From IntelliJ-Wiki

Jump to: navigation, search

The possibility to debug JavaScript is vital for Web developers. With WebStorm and PHPStorm, such debugging becomes quite easy. To illustrate the JavaScript debugging capabilities, we’ll create a very simple application that just shows some numbers in the browser, deploy it to a local Web server, and then debug it from WebStorm. Although in real life Web development you most often work with previously deployed applications, for the purposes of this tutorial we will consider a vice versa workflow.

In the context of WebStorm and PHPStorm, the term remote debugging applies to any set up when the application files are deployed on a host and you their copies are arranged in a WebStorm or PHPStorm project on your computer. This host itself can be remote or local, the point is that its location is different from the project location.

The server is launched either by the IDE itself, or manually by the user. When you debug such scripts, you actually place breakpoints in the JavaScript files on your machine that are mapped to the corresponding pages on the server.



  • You are working with WebStorm or PhpStorm, version 2.1 or higher. JavaScript support in WebStorm and PHPStorm is identical. Although this tutorial uses WebStorm, you can successfully repeat all the described steps in PHPStorm.

Note: JavaScript debugging is also available in IntelliJ IDEA and RubyMine, version 2.5 or higher.

  1. JavaScript Support
  2. JavaScript Debugger
  3. Remote Hosts Access
  • The JetBrains Firefox extension that supports JavaScript debugging from WebStorm and PhpStorm. The extension will be installed automatically when you initiate a JavaScript debugging session for the first time.
  • No specific JS libraries are required. You are welcome to use any JS libraries you need.
  • A Web server (in this tutorial Apache is used), integrated with WebStorm or PHPStorm.

Preparing contents for remote debugging

For our purposes, let's create a simple “show numbers” application as described in the tutorial Debugging JavaScript locally. The application will consist of a starting HTML page and a JavaScript that implements the application functionality. when you are through with the project creation, add the same “show numbers” contents. To do that, follow these steps:

1. In the </nowiki>numbers.html</nowiki> file generated by WebStorm automatically and opened in the editor (Image 1), add a reference to the JavaScript file </nowiki>numbers.js</nowiki> that will implement the application functionality. Inside the <body></body> tag (1), type the following code (2):

<script type="text/javascript" src="numbers.js" language="JavaScript"></script>

When ready, pay attention to the unresolved reference to numbers.js (3).

Image 1. Reference to numbers.js added to numbers.html.

2. Use the suggested quick fix to create the numbers.js stub JavaScript file. Expand the stub file (Image 2) with the following code:

var i=0;
 for (i=0;i<=10;i++)
  {if (i==3)
  document.write("The number is " + i);
Image 2. File numbers.js.

Deploying the application on a local Web server

Deploying your own JavaScript application on a local Web server for further debugging may seem artificial. However while following this sample workflow you will make all the steps required in real-life JavaScript development.

Installing and configuring Apache Web server

For the purposes of our tutorial, we use a local Apache HTTP Server. There are many ways to configure this server on your machine, but we suggest that you install it inside a XAMPP package. This will save time and effort.

First of all, download the XAMPP for windows, version 1.7.1 or higher. Install the package according to the installation instructions. When ready, launch the XAMPP control pane (Image 3) and click the Start button (1) next to the Apache label. To have the Apache server launched upon the operating system start-up, declare the server as service by selecting the Svc check box (2).

Image 3. XAMPP control pane.

The pane shows (Image 4) that the Apache server is running (1) and listens to port 80 (2):

Image 4. XAMPP control pane. Apache server running.

If you now open the Apache configuration file /xampp/apache/conf/httpd.conf, you can easily locate the lines that specify the following basic Apache server configuration settings:

  • server name:

# ServerName gives the name and port that the server uses to identify itself. # This can often be determined automatically, but we recommend you specify it explicitly to prevent problems during start-up. # If your host doesn't have a registered DNS name, enter its IP address here.

ServerName localhost:80

  • port:

# Listen: Allows you to bind Apache to specific IP addresses and/or ports, instead of the default.

Listen 80

  • document root:

# DocumentRoot: The directory out of which you will serve your documents. By default, all requests are taken from this directory, but symbolic links and aliases may be used to point to other locations.

DocumentRoot "C:/xampp/htdocs"

Note: If the server does not start, most likely a port conflict takes place because another application that listens to port 80 is already running. To improve the issue, change the server configuration as follows:

Listen 8080

ServerName localhost:8080

Configuring access to the Web server

Now we know that Apache takes files for processing from its <xampp installation folder>/htdocs/ document root. So the easiest way is just copy our application sources or the entire project folder to /xampp/htdocs/. Having this backup plan in mind, let's however see how this can be done using the facilities provided by the IDE.

Data exchange between the IDE and servers is supported through the Deployment functionality enabled by the Remote Hosts Access bundled plugin. The set of parameters that enable and determine this access is called a server configuration.

Let's create a server configuration to work with our local Apache server from the IDE. On the main menu, choose Tools | Deployment, then click Configuration on the context menu (Image 5):

Image 5. Create new deployment configuration.'

In the Deployment dialog box (Image 6), click the Add toolbar button File:add.png (1). Then in the Add Server dialog box that opens, type the configuration name Apache in the Name text box (2). From the Access type list (3), choose the method to exchange data between the IDE and the server. We are not going to harden our life even more, are we? So leave the FTP and SFTP options for another case and choose Mounted Folder (4).

Image 6. Adding a server access configuration.

Upon clicking OK you return to the Deployment dialog box that looks quite different (Image 7). First of all, the newly created server configuration is displayed in the list on the left-hand pane (1) and the configuration name is displayed in the Name text box (2). Next, the rind-hand pane of the dialog box shows the Connection tab (3) where the configuration type Mounted folder is preselected in the Access type (4) drop-down list.

Now let's tell the IDE where the Apache server stores files for processing and how to access this storage through the http protocol:

  1. In the Mounted folder (5) text box, type the path to the server document root in the format </nowiki><xampp installation folder>/htdocs</nowiki>.
  2. In the </>Web server root URL (6) text box, type the URL address that corresponds to the server root in the format http://localhost:<port>.
Image 7. Create new deployment configuration. Connection tab.

Let's check that the specified configuration ensures successful connection. Click the Open button (7). The XAMPP Welcome Page opens (Image 8):

Image 8. XAMPP welcome page.

This means that the IDE knows how to access the data on the Apache server in general. To put our connection settings into force, click the Apply button. The settings are saved, while we remain in the Deployment dialog box.

Let's now specify where we want our application deployed. To do that we only need to specify correspondence between files and folders on the server, the URL addresses to access them through the http protocol, and their local copies. This correspondence is also known as mapping, so to set it, let's switch to the Mappings tab (Image 9).

Image 9. Create new deployment configuration. Mappings tab.

As you can see, the path to the local copies is already filled in: the Local path field (2) shows the root folder of our project.

The other two sides of the mapping are not specified: the fields Deployment path on server (3) and Web path on server (4) are empty. If we leave the fields as is, our application sources will be deployed right in the server document root and will be accessible through the server root URL address. This approach works but is considered bad practice. So we will specify the target location of our sources on the server relative to the server document root (Image 10).

Image 10. Mappings tab. Mappings specified.

As the starting point, let's suppose that the server document root htdocs corresponds to the root folder of the local drive where our project is stored. To be specific, in our case it is the C:/ drive.

For the sake of simplicity, let's reproduce the entire C:\MY_PROJECTS\JAVA_SCRIPT_PROJECTS\numbers sub-tree on the server. This means that the path to the application sources on the server relative to the server document root must be the same as the path to the project folder relative to the C:/ drive root. In the Deployment path on server (1) text box, type:


Accordingly, the URL address to access the application will be a concatenation of the Web server root URL and the relative path to the file that implements the starting page of our application, that is, the file numbers.html. In the Web path on server (2) text box, type:


Finally, let's appoint this server configuration as default by clicking the Use this server as default button (3). This will help us set up synchronization.

That is all with configuring access to the server, just click OK. The configuration will be saved and ready for use.

Configuring synchronization with the server

We have just one thing to do left: we need to define how the IDE will ensure synchronization between the application sources on the server and their local copies, for example, in case you decide to update the application.

Scrupulous readers may have also noticed that the folder <xampp installation>\htdocs\MY_PROJECTS\JAVA_SCRIPT_PROJECTS\numbers that we specified as the target folder for deployment does not actually exist.

To fix these discrepancies, let's configure the synchronization with the server. Choose Tools | Deployment on the main menu, then click Options on the context menu (Image 11):

Image 12. Configuring deployment. Options menu.

In the Options dialog box that opens (Image 13), select the following check boxes:

  • Create empty directories (1) to have the currently missing folders \MY_PROJECTS\JAVA_SCRIPT_PROJECTS\numbers created automatically under <xampp installation>\htdocs.
  • Upload changed files automatically to the default server (2) to ensure that any changes you make to the application locally are automatically reproduced on the server. Now you see why we appointed our configuration as default.
Image 13. Deployment options.

All the other necessary settings are already specified, so just click OK and prepare for upload!

Uploading the application sources

After all that fuzz with configurations, the upload itself will seem infantile pastimes. All you need is choose Tools | Deployment | Upload to and select apache on the context menu, as shown in Image 14:

Image 14. Uploading the application.

To make sure that the application has been successfully deployed on the server, open the starting page of the application in the browser. Type the following URL:


The starting page shows the results of application execution (Image 15):

Image 15. Application starting page.

That's all with deployment, let's pass on to debugging.

Creating run/debug configuration for remote debugging

Unlike local debugging, for which the default run/debug configuration is provided, we’ll have to create one for remote debugging ourselves. This is how it’s done:

Press Alt+Shift+F9, and then press 0 to choose Edit configuration on the pop-up menu (Image 16):

Image 16. Open the Edit Configurations dialog.

In the Run/Debug Configurations dialog box, click the File:add.png toolbar button (1), then select in sequence JavaScript Debug (2) and Remote (3) on the context menus (Image 17):

Image 17. Creating configuration JavaScript Debug - Remote.

In the right-hand pane of the dialog box (Image 18), specify the main debug configuration settings:

  • In the Name (1) text box, type remote_numbers.
  • In the URL to open (2) text box, specify the URL address for accessing the starting page of the application as defined in the server configuration. Type http://localhost/my_projects/java_script_projects/numbers/numbers.html.
  • From the Browser (3) drop-down list, choose Firefox to have the starting page opened in this browser.
Image 18. Creating configuration: specifying browser and URL.

Synchronizing files on server with local copies

When a remote HTML file with a JavaScript injection is opened, the debugger tells the IDE the name of the currently processed file and the number of the line to be processed. The IDE opens the local copy of this file and indicates the line with the provided number. This behaviour is enabled by specifying correspondence between the URL addresses to access files and folders on the server and their local copies. This correspondence is called mapping. Mappings can be defined per files as well as for entire folders.

We will map the entire local project folder to the URL address of its counterpart on the server (Image 19'). In the Remote URLs of local files (1) area, click the Remote URL (3) field next to the project root node C:\MY_PROJECTS\JAVA_SCRIPT_PROJECTS\numbers (2) and type the following URL address (4):


Image 19. Creating configuration: specifying mappings.

The debug configuration is ready, click OK to save it.

Setting breakpoints

Now let’s set breakpoints to our JavaScript. This is most easy – just click the left gutter at the line you want the script to suspend (Image 20):

Image 20. Breakpoints in JavaScript set.

Starting the debugging session

Now that all the preliminary steps are done, it’s time to proceed with the debugging session itself (Image 21). From the Edit COnfigurations (1) drop-down list, select the newly created remote_numbers (2) configuration and click the File:debug.png (3) button on the toolbar.

Image 21. Starting a debugging session.

If you are launching the debugger for the very first time, WebStorm will install an extension that enables JavaScript debugging in Firefox and notify you about it (Image 22):

Image 22. Installing an extension to Firefox.

After launching the debugger, Firefox will inform you that the extension has been installed.

Note: adding the JetBrains extension results in adding the Debug in WebStorm command to the context menu of the pages in Firefox.

WebStorm starts the debugging session.

Examining the debugging information

When the debugging session is launched, the starting HTML page appears in the browser, and the Debug tool window (Image 23) opens in WebStorm:

Image 23. Debug tool window.

As soon as the first breakpoint is hit, the program execution suspends. The focus in the WebStorm editor switches to the file numbers.js, where the cursor positioned at the beginning of the line with the breakpoint hit (Image 24). The line is marked with a blue stripe in the background:

Image 24. The first breakpoint in numbers.js reached.

Let’s now step through the script. Actually, you can use the stepping buttons on the toolbar of the Debug tool window (Image 23), but since you are working in a keyboard-centric IDE, use the handy shortcuts, depending on your debugging algorithm. For example, you can press F7 to step to the next line or F9 to resume the program and have it work automatically till the next breakpoint is hit.

As you step through your application, the corresponding information appears in the Debug tool window, and the numbers.html page displays the script output step by step (Image 25):

Image 25. Intermediate result of script execution.

Finally, when the program execution is completed (Image 26), the debugging session data is cleared (1) and the numbers.html page displays the entire script output (2):

Image 26. Final script execution output.

That’s it with remote debugging in Firefox.

See also

Personal tools