Skip to content

Using IntelliJ Idea to build HTML5 apps on a Node.JS server

So unless you’ve been hiding under a rock for the past few years you’ve probably heard of JetBrains and their wonderful IDE, IntelliJ IDEA. Originally a Java IDE, they’ve fleshed it out to support a variety of additional platforms. They have arguably the best Flex tooling on the market and have since added support for the Web stack, Ruby, Python, etc etc etc.

I know not everyone is crazy about using IDEs, if it’s not your cup of tea then thanks for stopping by and you can feel free to stop reading here. If you want to learn how to set up IDEA to do fancy things with Node.JS and HTML5 development, however, keep reading!

(Note: I did this using IntelliJ IDEA 11. I do not have any idea how this will apply to previous or future versions of the IDE. If you have success or failure using this approach on other versions please let us know in the comments, as well as describing any tweaks you had to do to make it work right!)

Here’s the end goal: we want to have two separate applications, one of them a web server running on localhost in Node.JS, the other a website being served by that server. We want to be able to build, launch and debug both projects using IntelliJ IDEA, but we want to make sure that we’re not dependent upon IDEA – we want to be able to rsync our local folder to a remote server and have it simply run.

There are a variety of ways to make this happen, but I’m going to step you through the process I used.

Step 1 – Install Node

Install node.js on your machine. Go ahead, I’ll wait. It’s pretty quick now, if you’re on a Mac or PC you just run the installer – no more waiting for it to build etc.

(EDIT: In order to get code hinting from IntelliJ’s Node.JS plugin you’ll need to provide it with a path to the core node libraries. If you use the installer as I just suggested above then these libraries will not be accessible to the node plugin. In order to get code-hinting you’ll need to download the source tarball, unzip it, stick it somewhere and tell the plugin to point to that folder.)

Step 2 – Install the Node.JS plugin

Before we can set up our Node server we need to get the Node.js plugin for intelliJ. This is kind of really really easy, but it’s an extra step.

Open IntelliJ Idea and open the Plugin Manager (there should be a link in the upper-right of the default splash screen). In the popup that comes up, click “Browse Repositories” on the bottom left. Use the search box in the upper right to type “NodeJS” and you should see your options reduce to two plugins, NodeJS and NUnitJS. I’m not mucking around with testing right now, so ignore NUnitJS – right click on NodeJS and click “Download and Install”. When it finishes it’ll ask you to restart the IDE. Do so.

(Edit: to get code hinting there’s one more step. Once you’ve restarted your IDE you should see a green “Node.JS” Icon in your toolbar. It’ll be to the far right, after the Help icon. Click it. It just wants a path to the node.js source. If you installed via the official installer, follow my recommendation above and download the source as well. Either way, now that you have access to the source, tell IDEA to look at that source for the node.js plugin. It it works you’ll get a new folder linked in your project window that points to the source. As noted in the comments below, if you use this approach while having also used the installer it means that you will have to manually update the source every time you update your node install. I’m waiting for feedback from Jetbrains to see if there’s a better way.)

Now we’re ready to begin.

EDIT: As manners points out below, you also need to make sure that you enable the Remote Hosts plugin in order to debug this once we’re up and running!

Step 3 – Create the Server project

Open IntelliJ IDEA and click “Create New Project”. You’ll get a dialog box with some options. Give your project a name (“Node Server Project”), confirm that the location matches your desired location. Make sure that “create module” is checked and set the type to “Web Module”.

(This appears to be something of a compromise – technically we’d want a JavaScript module, since Node doesn’t make use of the rest, but JS is a subset of what the Web module gives us so we’ll roll with it.)

When your dialog box looks like this, click “finish”:

New Project config dialog box for a Node.JS project in IntelliJ IDEA

New Project config dialog box for a Node.JS project in IntelliJ IDEA

So in your Project panel, right-click on your “Node Server Project” module and create a new directory, call it “server”. Then right click on that directory and create a new JavaScript file, call it “server” too. Finally, right click on your “server” folder one more time and create a folder called “www” – this is where we’ll be deploying our website later.

Here is an example of a very simple Node.JS server that simply serves up files from a “www” folder. Copy this and paste it into the “server.js” file that you created.

server.js

var http = require("http");
var fs = require("fs");
var path = require("path");
var url = require("url");
 
var mimeTypes = {
    "html": "text/html",
    "jpeg": "image/jpeg",
    "jpg": "image/jpeg",
    "png": "image/png",
    "js": "text/javascript",
    "css": "text/css"
};
 
var server = http.createServer(function(request, response) {
 
    var uri = url.parse(request.url).pathname;
 
    uri = "www/" + uri;
 
    if (uri.charAt(uri.length - 1) == "/") {
        uri += "index.html";
    }
 
    if (uri.indexOf("..") != -1) {
        response.writeHead(403);
        response.end();
    }
 
    var filename = path.join(process.cwd(), uri);
 
    console.log("\tAttempting to serve: " + filename);
 
    path.exists(filename, function(exists) {
 
        if (!exists) {
            console.log("File not found: " + filename);
            response.writeHead(404);
            response.end("Sorry, the file you requested was not found. Don't let it ruin your day! :)");
            return;
        }
 
        var mimeType = mimeTypes[path.extname(filename).split(".")[1]];
        response.writeHead(200, {'Content-Type':mimeType});
 
        var fileStream = fs.createReadStream(filename);
        fileStream.pipe(response);
    });
 
 
}).listen(8080);

Now all we have to do is configure our application server. In the upper middle of your IDEA window should be a little combo box containing your run configurations. Right now it should be empty – click it and select “Edit Configurations”.

IntelliJ IDEA Run Configurations

A popup will appear. Press the “+” sign in the upper left and select “NodeJS”. If “NodeJS” isn’t available then you don’t have the NodeJS plugin installed – go back to Step 2 of these instructions and make sure you’ve restarted your IDE upon completion.

Select NodeJS and name your configuration “NodeJS Server”. The path to Node is OS specific, but I know on a Mac if you use their installer it’ll stick it into /usr/local/bin/node. If you’re on a PC or if you have a custom install just set that to point to the actual “node” executable, wherever it is.

Now you have to to set “Path to Node App JS File” equal to the server.js file you created above. Then set the “Working Directory” equal to the path to your “server” folder – for me, it looks like this: “/Users/mykola/temp/Node Server Project/server”

Once you’ve done that, your Run Configuration should look like this. If it does, hit OK:
Server Run Configuration

Congratulations, you’re done! To test this, click the “Debug” button next to that combo box – not the green arrow, the one after that. That’ll launch your server in debug mode. Then open a browser window and navigate to “http://localhost:8080″ and you’ll be greeted by a wonderful File Not Found! message. No worries, everything is going great!


Set a Breakpoint in your Node.JS server using IntelliJ Idea
Before we move on to the website project, take a second to play with IDEA’s debugger. Set a break point inside of your server handler – right on line 17, for instance, where “uri” gets defined. Do that by clicking on the gutter to make the red dot appear, as shown. With the breakpoint set and the server running, hit localhost:8080 again to put IDEA through it’s paces. It should hit the breakpoint at which point you can tab over to the debugger at the bottom and introspect all of the objects in scope, evaluate watch expressions, see and navigate the call stack, etc. Really, really useful and way better than just sticking random debug values into console.log(). ;)

IntelliJ Debugger after a breakpoint has been hit.

Step 4 – Setting up your Web Application Project

Now completely forget about all of that. Shut down your server and close the project, we’ll come back to it in a few minutes.

First, go ahead and create a brand new IntelliJ project called “MyWebsite”. For its location you can put it anywhere – we are going to be deploying the files from this project to the “www” folder in our server project, but we can automate that later so we never have to think about it. Just go ahead and create your new project with a Web module ready to go.

Right click on your module in the project view and add a folder called “www”. Inside of that folder, add a folder called “script” and a folder called “style”. This is a pretty simple run-of-the-mill html file structure. Inside of “www”, create an html file called “index.html”. Inside of “script”, create a javascript file called “main.js”. Inside of “style”, create a CSS file called “style.css”.

Here is some sample content for those files:

index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
    <title>Sample Index</title>
    <script type="text/javascript" src="script/main.js"></script>
    <link href="style/style.css" rel="stylesheet" />
</head>
 
<body>
    <h1 onclick="headerClicked()">This is my Index page!</h1>
</body>
</html>

script/main.js

function headerClicked() {
    var foo = 2 + 2;
 
    alert("Sample Alert: " + foo * 2);
}

style/style.css

body {
    color:#fff;
    background-color:#000;
}

So far so good, right? It’s a really simple website, when you click on the header text you’ll get an alert showing you a random number, blah blah blah. The point is, we want to be able to do two things:

  1. Deploy this sucker to our Node server!
  2. Set breakpoints and debug our javascript in IntelliJ IDEA

In order to achieve these two goals we need to do the following:

  1. Configure our remote deployment options so that these files get magically sent to our server’s /www folder
  2. Build a debug configuration that’ll access these files via our server, instead of from the file system.

Set up a Deployment Configuration for our Web SiteSo, the first thing we need to tackle is Deployment. In IntelliJ IDEA, click on “Tools” in the menu, go down to “Deployment” and click “Configuration.”

In the ensuing popup we’ll need to add a deployment target, configure the Connection, then the mappings. First, click the “+” sign in the upper left. Name your Server and set its type to “Local or Mounted Folder”.


Deployment Config - ConnectionThe Connection tab tells IDEA how to connect to your deployment target, both to upload/download files and also to actually access it as a remote http endpoint. So in the Connection tab, make sure “Type” is equal to “Local or mounted folder”. Set the “Folder” path equal to the path to the folder that holds server.js that you created earlier.

In my case, folder is “/Users/mykola/temp/Node Server Project/server”. Set the “Web Server Root URL” to “http://localhost:8080/”. We’re using port 8080 because that’s what port we’re listening on in our server.js file.

When your “Connection” tab looks like this, tab over to “Mappings”.


Deployment Config - MappingsThe “Mappings” tab is where you map files and folders in your HTML project to files and folders in your remote endpoint. Go ahead and click the “use this server as default” button. If you added a “www” folder to the root of your project as I advised above, append “/www” to the “Local path” that’s populated by default. Set your Deployment Path on server ‘NodeServer’ equal to “/www”, and wet your Web Path equal to simply “/”. Your “Mappings” tab should look like the attached screenshot.


Deployment OptionsPress OK, you’re almost done! Go back to the menu and select Tools > Deployment > Options. Check the boxes that say “Create Empty Directories” and “Upload changed files automatically to the default server.” Hit OK.

In your projects panel, Right Click your “MyWebApplication” Module and go all the way down to the Deployment item in the context menu. Select “Upload to NodeServer”. This should be the only time you ever have to do this – from now on, every time you make a change in this project it will automagically push that change to your server/www folder.

Let’s stop for a second and make sure everything is wired up correctly:

  1. Go to File -> Open Recent in IntelliJ and Open your Server project. It’ll ask you if you want to open it in a new window or the same window – use a New Window.
  2. In the projects panel, look into your “www” folder – you should see the files from your web project. If you don’t then you did something wrong above – make sure that you deployed your files from the context menu as I outlined last paragraph!
  3. If you still have a breakpoint set, go ahead and get rid of it. Just click on it in the gutter and it should go away.
  4. Make sure that the run config we set up is selected, and start your server in Debug mode.
  5. Point your browser to http://localhost:8080 and voila, you should see your html page!

The very last step is to set up a Run Configuration for your Web project. This is very similar to the Run Configuration we set up for our server. Click on the combo box, select “Edit Configurations”, click the plus sign in the upper left and select “JavaScript Debug –> Remote”. Name your configuration “JS Debugger”, set the URL to “http://localhost:8080″ and map your project to the following remoteURL: “/”. Your screen should look like this:

HTML Run Configuration


Now for the big test! Switch back to your server project and make sure it’s running. If so, then in your HTML project go ahead and press the “Debug” button – it should open your browser to your website, served up via localhost:8080.

(Note, if you have trouble with getting it to open in the right browser, you can go into IntelliJ’s settings and make sure that the “Web Browsers” settings are working the way you’d like. This can be highly specific so I didn’t cover it above.)

While your browser is open and showing your app, click your text. You should see an Alert come up with some gibberish in it, right? Click OK and then without closing anything go back to your Web project. In script/main.js, put a breakpoint on the line that generates that alert. Tab back to your browser and click again and you’ll see that you’ve just triggered that breakpoint!

Final Words

Phew! Thanks for reading all of that. This can be a big pain in the ass to configure, but once it’s working the way you want it to you have a lot more options. Debugging in IntelliJ IDEA is more powerful than debugging in a browser console, and you can make updates and edits in your code on the fly.

If this worked for you, let me know in the comments! If it didn’t, well, I’m sure that it CAN with a bit more nudging. Feel free to ask for help in the comments and I’ll see if I can’t take a look, but with this many variables in play it probably makes sense just to tinker with it and figure out what’s breaking.

I hope that helped!

{ 16 } Comments

  1. nicity | February 19, 2012 at 10:24 am | Permalink

    Please add some words on Node.Js javascript sources configuration, it allows completion for standard symbols from e.g. http module

  2. mykola | February 21, 2012 at 5:13 pm | Permalink

    @nicity good catch. It took me a while but I figured out how to do that. It seems like the IntelliJ plugin is not designed to work with the Mac/Windows installers, but there’s a workaround! I’ve asked the IntelliJ people if this is the best way to do this right now, and if so then I’ll edit the post. In the meantime, here’s the deal:

    1) Download the node.js source tarball, decompress it and stick it somewhere where you can find it. I now have a folder called /Users/mykola/node/node-v0.6.11, for instance.
    2) Do NOT install this tarball – just unzip it into a place where you can find it and forget about it.
    3) In IntelliJ, once you’ve installed the NodeJS plugin you should see a little “Node.js” icon in your toolbar. For me it’s the last item in my toolbar, after the “help” button. It just looks like a green hexagon with “JS” inside it. Click it.
    4) You’ll get a popup which asks you to specify your node.js location. Simply point it at the node source stuff you unzipped. (ie I put in: /Users/mykola/node/node-v0.6.11).

    Then it works.

    What’s going on is that IntelliJ needs a set of libraries against which to evaluate your code. When you use the packaged installer the core libraries seem to get stuck somewhere inaccessible, so IntelliJ doesn’t know where to find them. By downloading the source like this you’re able to provide the plugin with an alternate set of files.

    The one caveat now is that your code hinting will not keep up with your node installation. Every time you update Node you’ll have to go get a fresh set of source files and reset your plugin’s source or you risk getting outdated code-hinting against the core node libraries.

    Does that make sense?

  3. Chris borghmans | February 22, 2012 at 6:48 pm | Permalink

    Does this only work with IntelliJ 11, because I don’t see an option to create a web module in 10.5?

  4. mykola | February 22, 2012 at 6:50 pm | Permalink

    @Chris Yeah, I only have 11. I haven’t tested any of this with previous versions. I will update the post to that effect. It’s possible that prior versions of IntelliJ didn’t offer JS support? I’m not sure.

  5. mykola | February 22, 2012 at 6:51 pm | Permalink

    @Chris it may be something that you can solve with a plug-in or config setting somewhere in IntelliJ. I seem to recall there being some configuration that allows you to enable, for instance JavaEE, Databases, etc etc etc. You may just have Web stuff turned off?

  6. chuck | February 22, 2012 at 10:20 pm | Permalink

    I am using version 11.02 and everything works except the breakpoint in the JavaScript file of the Web project. I tried this using both Firefox and Chrome in the JS Debugger launch setting.

  7. mykola | February 22, 2012 at 10:45 pm | Permalink

    @chuck that’s very weird. Are you sure you’re hitting the served up version? It’s possible that you’re debugging on localhost but interacting on file:/// or something like that?

    This works for me, and I don’t think I left anything out. Is anyone else having similar trouble?

  8. Thomas Burleson | February 22, 2012 at 11:55 pm | Permalink

    Thanks for the details re integration of IntelliJ with NodeJS

    Your node.js server script is rather bare bones.
    AngularJS provides an amazing server script that responds with directory listings, missing file responses, data files, and more. I created a CoffeeScript version and then provide a support for NodeJS web servers and remote data services. Check out https://github.com/ThomasBurleson/node-proxy-services for details.

  9. mykola | February 23, 2012 at 12:05 am | Permalink

    @Thomas yeah, I wanted to keep the emphasis on the IDE configuration stuff rather than the code so I left it simple enough to be small but robust enough to serve up random files as necessary.

    I am leaning now towards using express.js for actual server-side development, I spent the day reading up on it and playing with it and I think I like it a lot. But I’ll take a look at your link and give AngularJS a look as well, I know you’re not the only one who really likes it.

    Thanks for the feedback!

  10. Simon So | March 6, 2012 at 7:13 am | Permalink

    These instructions are Godsend! Thank you so much! I got everything up and running!

  11. Simon So | March 6, 2012 at 5:47 pm | Permalink

    Hi,

    I tried to create an app with express.

    But when I tried your steps to run in a debugger, I will stuck at this stack:

    fs.statSync(), fs.js:414
    statPath(), module.js:89
    tryFile(), module.js:138
    :
    :
    require(), module.js:370
    express.js:12

    node app.js did run without the debugger.

    Any ideas?

  12. mykola | March 6, 2012 at 5:51 pm | Permalink

    @Simon is Express installed locally or globally? It looks like there are issues with setting paths in the NodeJS plugin for IntelliJ. Make sure that express is installed in /node_modules/express, rather than in some global library folder to which IntelliJ may be having a hard time gaining access.

  13. Manners | March 6, 2012 at 7:36 pm | Permalink

    Thanks for this great write up.

    A quick tip! You should include that you need to have the Remote Hosts plugin enabled in order to proceed past the Deployment section.

  14. mykola | March 6, 2012 at 7:43 pm | Permalink

    Thanks @Manners, I’ve added that above. @Chuck if you check back here, give that a try – it may fix your breakpoint problem!

  15. Simon So | March 6, 2012 at 9:57 pm | Permalink

    @Mykola, I think I kinda know what my problem is.

    I will research a bit more if someone solved this problem already.

    http://stackoverflow.com/a/9590600/1253097

  16. Ciravred | June 1, 2012 at 7:07 am | Permalink

    Hi,

    thanks for the great instructions. :)

    I had the same problems for debugging the web application like Chuck.

    The solution for me was to do 2 things:
    * the remote url root of the web application must be set to the correct document root: MyWebApplication/www
    * and for some reasons the remote url was not reacting when I just put a “/” so I put “http://localhost:8080/” and this worked fine then – I am running under Win7 with the latest Intellij Idea version – maybe it behaves different here?

    Thanks again!

Post a Comment

Your email is never published nor shared. Required fields are marked *