├── CONTRIBUTING.md ├── deployment.md ├── README.md ├── application-tips.md ├── getting-started.md └── windows-environment.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ### Pull requests are welcome! 2 | This is still a work in progress, an experiment - if you will, and we'd love your help to make it better! Please file an issue on any major changes you're planning - e.g. "Add new X section", and comment on issues you intend to take on to prevent duplication of effort. 3 | 4 | It's also good to make a pull request for any change to the README (minor spelling and wording changes are fine to commit to master). This enables everyone to stay updated on what's going on in the repo. We'll be lax on this in the beginning as we work together to populate this with an initial set of content. 5 | -------------------------------------------------------------------------------- /deployment.md: -------------------------------------------------------------------------------- 1 | ## Deployment 2 | > :triangular_flag_on_post: **TODO** 3 | * Continuous integration with VSO. 4 | * Docker and containers. 5 | * Cross-platform remote debugging. 6 | 7 | ### Process Management (Keeping Applications Running) 8 | 9 | Process managers will function to keep your node-based applications running while keeping some complexity outside of your application's code. Features vary and may include restart on failure, clustering, and rolling-upgrades. 10 | 11 | * [PM2](http://pm2.keymetrics.io/) 12 | * [forever](https://www.npmjs.com/package/forever) 13 | * [node-cluster-service](https://github.com/godaddy/node-cluster-service) 14 | * [nodemon](http://nodemon.io/) 15 | 16 | ### Deployment on Windows 17 | * Running As A Service 18 | * [windows-service](https://www.npmjs.com/package/windows-service) 19 | * [node-windows](https://github.com/coreybutler/node-windows) 20 | * [Non-Sucking Service Manager (NSSM)](http://nssm.cc/) 21 | * [WinSer](http://jfromaniello.github.com/winser/) wrapper for NSSM 22 | * Service Alternative: [Use Task Sheduler to run a task at startup](http://www.howtogeek.com/138159/how-to-enable-programs-and-custom-scripts-to-run-at-boot/) 23 | * [Application Request Routing (ARR)](http://www.iis.net/downloads/microsoft/application-request-routing) for IIS 24 | * Setup ARR as reverse-proxy to node app running as a service 25 | * iisnode: 26 | * [GitHub repo](https://github.com/tjanczuk/iisnode/wiki) and [wiki](https://github.com/tjanczuk/iisnode/wiki) 27 | * [Scott Hanselman's blog post](http://www.hanselman.com/blog/InstallingAndRunningNodejsApplicationsWithinIISOnWindowsAreYouMad.aspx) 28 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Microsoft + Node.js Guidelines 2 | Microsoft :heart: Node.js! 3 | 4 | We work hard to contribute to the Node.js community and we want to make sure your experience is as seamless as possible. In particular, our goals here are to: 5 | * make it easier for people using Microsoft services and technologies to get started on the right foot with Node.js 6 | * consolidate Microsoft's Node.js offerings in a centralized place to make it easier for you to find information 7 | * communicate status on key issues we're addressing and collect feedback from the Node.js community on how we can do better. 8 | * provide a forum to connect with various teams at Microsoft working on improving the Node.js experience. 9 | 10 | Note that this is not intended to be a comprehensive set of recommendations. Rather it's meant to be a helpful set of content that makes it easier to avoid any potential gotchas, and the beginning of what we expect to be an ongoing conversation on how we can improve the Node.js experience on Microsoft platforms. 11 | 12 | ### Emoji legend 13 | 14 | > :bulb: This is a tip that provides the reader with some additional info that's not necessary, but potentially useful for the task at hand. 15 | 16 | > :triangular_flag_on_post: **TODO** This describes a todo item that we'd like some help with. 17 | 18 | > :chart_with_upwards_trend: **IN PROGRESS** This provides awareness about an important issue that we're currently working on resolving. 19 | 20 | ## Node.js tips, tricks, resources, and more! 21 | * [Hello World](getting-started.md) 22 | * [Working with npm packages](getting-started.md#working-with-npm-packages) 23 | * [Using an existing npm package](getting-started.md#using-an-existing-npm-package) 24 | * [Managing npm dependencies](getting-started.md#managing-npm-dependencies) 25 | * [Publishing npm packages to the registry](getting-started.md#publishing-npm-packages-to-the-registry) 26 | * [Local vs. Global packages](getting-started.md#local-vs-global-packages) 27 | * [Using nodemon](getting-started.md#using-nodemon) 28 | * [Configuring your Windows development environment](windows-environment.md#configuring-your-windows-development-environment) 29 | * [Command-line console recommendations and other tools](windows-environment.md#command-line-console-and-other-useful-tools) 30 | * [Editors and IDEs](windows-environment.md#editors-and-ides) 31 | * [MAX_PATH explanation and workarounds](windows-environment.md#max_path-explanation-and-workarounds) 32 | * [Compiling native Addon modules](windows-environment.md#compiling-native-addon-modules) 33 | * [Building for cross-platform](building-for-cross-platform.md) 34 | * [Deployment](deployment.md) 35 | * [Application-specific tips](application-tips.md) 36 | * [Node.js + Microsoft products, services, and contributions](README.md#nodejs--microsoft-products-services-and-contributions) 37 | * [Anything you want!](CONTRIBUTING.md) 38 | 39 | ## Node.js + Microsoft products, services, and contributions 40 | * [**Visual Studio Developer Essentials**](https://www.visualstudio.com/products/visual-studio-dev-essentials-vs): The go-to collection of essential free tools and introductory subscriptions. 41 | * [**Visual Studio Code**](https://code.visualstudio.com/): Lightweight cross-platform editor for building and debugging modern web and cloud applications. 42 | * [**Node.js Tools for Visual Studio**](https://www.visualstudio.com/features/node-js-vs): Free, open-source extension that turns Visual Studio into a powerful Node.js development environment. 43 | * [**TypeScript**](https://www.npmjs.com/package/typescript): TypeScript is a language for application scale JavaScript development. 44 | * Also useful for working with typescript is [tsd](https://www.npmjs.com/package/tsd), which enables you to quickly download TypeScript definition files. 45 | * [**Azure SDK for Node.js**](https://github.com/Azure/azure-sdk-for-node#readme): We provide both [fine-grained modules](https://www.npmjs.com/~windowsazure) for different Microsoft Azure services which you can install separately, and an [all-up module](https://www.npmjs.com/package/azure) which contains everything. 46 | * [**Application Insights**](https://www.npmjs.com/~msftapplicationinsights): Monitor your application's performance and usage with just a few lines of code. 47 | * [**Node-Chakra and Windows IoT**](https://github.com/Microsoft/node#readme): This project enables Node.js to optionally use the Chakra JavaScript engine on Windows 10, allowing Node.js to run on Windows 10 IoT. 48 | * [**Visual Studio Online**](https://www.npmjs.com/~vsonline) 49 | * [**Docker Tools, `yo docker`**](https://github.com/Microsoft/DockerToolsDocs#yo-docker) 50 | * [**Node.js Technical Steering Committee**](https://nodejs.org/en/foundation/tsc/) and [**Node.js Foundation Board**](https://nodejs.org/en/foundation/board/) 51 | * [**Others**](https://www.npmjs.com/~microsoft) 52 | 53 | > :triangular_flag_on_post: **TODO** Add other Microsoft services related to Node.js. 54 | 55 | ## Contributions Welcome! 56 | This is still a work in progress, an experiment - if you will, and we'd love your help to make it better! Please see our [contributing guidelines](CONTRIBUTING.md) for details. 57 | -------------------------------------------------------------------------------- /application-tips.md: -------------------------------------------------------------------------------- 1 | ## Application-specific tips and tricks 2 | > :triangular_flag_on_post: **TODO** 3 | * .NET in-process using Edge.js. 4 | * [node-windows](https://github.com/coreybutler/node-windows): Windows services, logging, and commands using Node.js. 5 | 6 | ### Setting up and working with Azure DocumentDB 7 | 8 | 1. [Create a DocumentDB database account](https://azure.microsoft.com/en-us/documentation/articles/documentdb-create-account/) 9 | 2. [Create a database](https://azure.microsoft.com/en-us/documentation/articles/documentdb-create-database/) 10 | 3. [Create a collection](https://azure.microsoft.com/en-us/documentation/articles/documentdb-create-collection/) 11 | 4. [Add documents to the collection](https://azure.microsoft.com/en-us/documentation/articles/documentdb-view-json-document-explorer/) 12 | 5. Navigate to the root project directory and install the `documentdb` package: `npm install documentdb` 13 | 6. *(Optional, but helpful for IntelliSense support in Visual Studio Code)* Install the type definition file for DocumentDB with `tsd install documentdb` 14 | 7. Load the documentdb module: `var DocumentClient = require('documentdb').DocumentClient;` 15 | 8. Create a new `DocumentClient` object by specifying the endpoint URL and master key: `var ddbClient = new DocumentClient(endpointUrl, {masterKey: masterKey});` 16 | > :bulb: The endpoint URL and keys can be found in the Azure portal by navigating to your DocumentDB account 17 | 18 | 9. Query all documents in a particular collection in a database 19 | ```javascript 20 | // note: the below code queries all documents in the collection with no 21 | // predicate to filter any documents out 22 | ddbClient.queryDatabases('SELECT * from d WHERE d.id = "database_name"') 23 | .current(function (err, database) { 24 | ddbClient.queryCollections(database._self, 'SELECT * FROM c WHERE c.id = "collection_name"') 25 | .current(function (err, collection) { 26 | var docQuery = 'SELECT * FROM collection c'; 27 | ddbClient.queryDocuments(collection._self, docQuery) 28 | .toArray(function (err, documents) { 29 | if (!err) { 30 | console.log('found ' + documents.length + ' documents...'); 31 | for (var i = 0; i < documents.length; i++) { 32 | console.log(documents[i]); 33 | } 34 | } 35 | }); 36 | }); 37 | }); 38 | ``` 39 | 40 | ### Connecting to Microsoft SQL Server 41 | 42 | * [tedious](https://www.npmjs.com/package/tedious) - TDS client written in JavaScript, no binary dependencies 43 | * [mssql](https://www.npmjs.com/package/mssql) - Friendly interface wrapper around SQL clients, tedious by default. 44 | * [mssql-ng](https://www.npmjs.com/package/mssql) - Next generation ES6-template interface for SQL (uses mssql/tedious). 45 | 46 | ### Setting up and working with MongoDB 47 | 48 | 1. [Install MongoDB on Windows](https://docs.mongodb.org/manual/tutorial/install-mongodb-on-windows/) 49 | 2. Install the MongoDB npm package in the project root by running `npm install mongodb` 50 | 3. *(Optional, but helpful for IntelliSense support in Visual Studio Code)* Install the type definition file for MongoDB with `tsd install mongodb` 51 | 4. Load the mongodb module: `var MongoClient = require('mongodb').MongoClient;` 52 | 5. [Determine your MongoDB connection string URI](https://docs.mongodb.org/manual/reference/connection-string/) and set it to a variable: `var mongoUrl = '...'`; 53 | > Example: mongodb://localhost:27017/yourDatabaseName 54 | 55 | > :bulb: MongoDB by default listens on 27017, but to verify this open the MongoDB log file `mongod.log` in the log directory and navigate the line that shows the port number (i.e. `[initandlisten] waiting for connections on port 27017`) 56 | 6. Access your MongoDB database by calling `MongoClient.connect()` and query the returned database 57 | ```javascript 58 | MongoClient.connect(mongoUrl, function (err, db) { 59 | if (!err) { 60 | // query the collection and return a cursor to use 61 | // to access the data 62 | // 63 | // note: calling find() with no parameters is the equivalent 64 | // of pulling all documents in the collection with no 65 | // predicate 66 | var cursor = db.collection('yourCollectionName').find(); 67 | 68 | // loop through all of the documents returned by the 69 | // query 70 | cursor.each(function (err, element) { 71 | if (!err && element) { 72 | // do something with the document 73 | } 74 | // if error and the document are undefined then 75 | // we have reached the no-more-documents condition 76 | if (!err && !element) { 77 | console.log('done!'); 78 | } 79 | }); 80 | } 81 | }); 82 | ``` 83 | 84 | ### Azure Services 85 | 86 | * [azure](https://www.npmjs.com/package/azure) - Full client for azure 87 | * [azure-storage](https://www.npmjs.com/package/azure-storage) - client for Azure Storage services (Tables, Blobs, Files, Queues), which is part of the `azure` module above. 88 | * [azure-storage-simple](https://www.npmjs.com/package/azure-storage-simple) - Promise based interface wrapper around `azure-storage` with a simpler UI. 89 | 90 | 91 | ## Accessing platform APIs 92 | Sometimes you need to access plaform functionality for which no suitable module is available. For example your app may need to access the registry running on a Windows Server or Desktop. In this case there are 2 ways to proceed. 93 | 94 | 1. Create a native module add-on by wrapping code in C binding boilerplate code [using the V8 sdk and dev tools](https://nodejs.org/api/addons.html). 95 | 2. Use [ref](https://github.com/TooTallNate/ref) and [node-ffi](https://github.com/node-ffi/node-ffi) modules to access C buffers and call shared library (DLL) functions from javascript. 96 | 97 | There are plenty of examples of [creating native modules](http://www.martinchristen.ch/node/tutorial11), including our notes on [Compiling native addon modules](windows-environment.md#compiling-native-addon-modules) but less on [using ref and node-ffi](http://opendirective.net/blog/2015/10/working-with-windows-native-code-from-node-js). 98 | 99 | > :bulb: Note it is good practice to ensure published modules are [written to run on all platforms](building-for-cross-platform.md#writing-cross-platform-modules-and apps), even though this can be conciderable extra work. Modules that only work on Windows or Linux are likely to unpopular so such code is best restricted to private modules or app code. 100 | -------------------------------------------------------------------------------- /getting-started.md: -------------------------------------------------------------------------------- 1 | ## Getting Started with Node and NPM 2 | Let's start with the basics. 3 | 4 | 1. Install Node.js: https://nodejs.org. 5 | > :bulb: When you install Node.js, you'll want to ensure your `PATH` variable is set to your install path so you can call Node from anywhere. 6 | 7 | 2. Create a new directory named `hello-world`, add a new `app.js` file: 8 | ```js 9 | /* app.js */ 10 | console.log('Hello World!'); 11 | ``` 12 | 13 | 3. In the command prompt, run `node app.js`. 14 | > :bulb: Your environment variables are set at the time when the command prompt is opened, so ensure to open a new command prompt since step 1 if you get any errors about Node not being found. 15 | 16 | 4. Moving beyond from simple console applications... 17 | ```js 18 | /* app.js */ 19 | 20 | // Load the built-in 'http' module. 21 | var http = require('http'); 22 | 23 | // Create an http.Server object, and provide a callback that fires after 'request' events. 24 | var server = http.createServer(function (request, response) { 25 | // Respond to the http request with "Hello World" and a basic header. 26 | response.writeHead(200, {'Content-Type': 'text/plain'}); 27 | response.end('Hello World!\n'); 28 | }); 29 | 30 | // Try retrieving a port from an environment variable, otherwise fallback to 8080. 31 | var port = process.env.PORT || 8080; 32 | 33 | // Start listening on the specified port and print out a url to visit. 34 | server.listen(port); 35 | console.log('Listening on http://localhost:' + port); 36 | ``` 37 | 38 | 5. In the command prompt, run `node app.js`, and visit the url that's printed out to the console. 39 | 40 | 6. To stop the application, run `Ctrl+C`. 41 | 42 | ## Working with npm packages 43 | As shown above, it's pretty impressive what you can do with so few lines of code in Node.js. Part of the philosophy of Node.js is that the core should remain as small as possible. It provides just enough built-in modules, such as filesystem and networking modules, to empower you to build scalable applications. However, you don't want to keep re-inventing the wheel every time for common tasks. 44 | 45 | Introducing, npm! 46 | 47 | npm is the package manager for JavaScript. npm ships with Node.js, so there's no need to install it separately. 48 | 49 | ### Using an existing npm package 50 | To get a sense for how to use npm packages in your app, let's try getting started with `express`, the most popular web framework for Node.js. 51 | 52 | 1. Create a new directory entitled `my-express-app`, then install `express` from within that directory. When `express` is installed, the package and its dependencies appear under a `node_modules` folder. 53 | ``` 54 | C:\src> mkdir my-express-app 55 | C:\src> cd my-express-app 56 | C:\src\my-express-app> npm install express 57 | ``` 58 | 59 | > :bulb: We recommend starting with a short path like C:\src to work around any potential MAX_PATH issues. 60 | 61 | 2. Now, create a new file, `app.js`. This code will load the express module we just installed, and use it to start a lightweight web server. 62 | ```js 63 | /* app.js */ 64 | 65 | var express = require('express'); 66 | var app = express(); 67 | 68 | app.get('/', function (req, res) { 69 | res.send('Hello World!'); 70 | }); 71 | 72 | var port = process.env.PORT || 3000; 73 | 74 | app.listen(port); 75 | console.log('Listening on http://localhost:' + port); 76 | ``` 77 | 78 | 3. Start the app by running `node app.js` in the command line. Tada! 79 | 80 | There are many more packages available at your disposal (200K and counting!). Head on over to https://www.npmjs.com to start exploring the ecosystem. 81 | 82 | > :bulb: Most of the packages available via npm tend to be pure JavaScript, but not all of them. For instance, there's a small percentage of native module addons available via npm that provide Node.js bindings, but ultimately call into native C++ code. This includes packages with `node-gyp`, `node-pre-gyp`, and `nan` dependencies. In order to install and run these packages, some additional machine configuration is required (described below). 83 | 84 | ### Managing npm dependencies 85 | Once you start installing npm packages, you'll need a way to keep track of all of your dependencies. In Node.js, you do this through a `package.json` file. 86 | 87 | 1. To create a `package.json` file, run the `npm init` in your app directory. 88 | ``` 89 | C:\src\my-express-app> npm init 90 | ``` 91 | 92 | 2. Npm will prompt you to fill in the details about your package. 93 | 3. In the `package.json` file, there is a "dependencies" section, and within it, an entry for `"express"`. A value of `"*"` would mean that the latest version should be used. To add this entry automatically when you install a package, you can add a `--save` flag: `npm install express --save`. 94 | > :bulb: If you only require a dependency as part of a development environment, then you could/should install the package in the "devDependencies". This is accomplished by using the `--save-dev` parameter. For example: `npm install --save-dev mocha`. 95 | 96 | 4. Now that your packages are listed in `package.json`, npm will always know which dependencies are required for your app. If you ever need to restore your packages, you can run `npm install` from your package directory. 97 | 98 | > :bulb: When you distribute your application, we recommend adding the `node_modules` folder to `.gitignore` so that you don't clutter your repo with needless files. This also makes it easier to work with multiple platforms. If you want to keep things as similar as possible between machines, npm offers many options that enable you to fix the version numbers in `package.json`, and even more fine-grained control with `npm-shrinkwrap.json`. 99 | 100 | ### Publishing npm packages to the registry 101 | Once you've created a package, publishing it to the world is only one command away! 102 | 103 | `C:\src\my-express-app> npm publish` 104 | 105 | > :bulb: Use npm's private modules. 106 | 107 | > :triangular_flag_on_post: **TODO** Add description about how to authorize the machine using `npm adduser`. 108 | 109 | ### Local vs. global packages 110 | There are two types of npm packages - locally installed packages and globally installed packages. It's not an exact science, but in general... 111 | * Locally installed packages are packages that are specific to your application 112 | * Globally installed packages tend to be CLI tools and the like 113 | 114 | We went through locally installed packages above, and installing packages globally is very similar. The only difference is the `-g` command. 115 | 116 | 1. `npm install http-server -g` will install the module globally. 117 | 118 | > :bulb: The module will be installed to the path indicated by `npm bin -g`. 119 | 120 | 2. Run `http-server .` to start a basic fileserver from any directory. 121 | 122 | > :bulb: In fact the only difference when using -g is that executables are placed in a folder that is on the path. If you install without the -g option you can still access those executables in `.\node_modules\.bin`. This folder is automatically added to the path when any scripts defined in `package.json` are run. Doing this will help avoid version clashes when a project uses skrinkwrap or otherwise specifies the version of a module different to other projects. It also avoids the need for manual install instructions for some dependencies so a single "npm install" will do. 123 | 124 | ### And much more! 125 | * [npm docs and tutorials](https://docs.npmjs.com/) 126 | * [Laurie Voss - npm past, present, and future](https://www.youtube.com/watch?v=-fqu-5IuOkc) 127 | 128 | ## Using nodemon 129 | 130 | [nodemon](http://nodemon.io/) is a utility that will monitor for any changes in your source and automatically restart your server. Use npm to install it: 131 | 132 | ``` 133 | npm install -g nodemon 134 | ```` 135 | 136 | After installation, you can launch your application using nodemon. For example: 137 | 138 | ``` 139 | nodemon app.js 140 | ``` 141 | 142 | After this, you don't have to restart the Node server after making changes since nodemon will automatically restart it for you. If you're developing a web application, simply refresh your browser to examine your update. Pretty handy for development! 143 | -------------------------------------------------------------------------------- /windows-environment.md: -------------------------------------------------------------------------------- 1 | # Configuring your Windows development environment 2 | ## Command line console and other useful tools 3 | One of the pain points we hear from users is that the command line console in Windows could use some work. We hear ya, and we're [working on it](https://wpdev.uservoice.com/forums/266908). In the meantime, we want to enable you to have the best experience possible. So here are some links to recommended tools to complement your existing experience. 4 | * **cmd:** cmd has had some improvements in Windows 10, so be sure to check it out if you abandoned ship in the past :smiley:. When you're working with Node.js, chances are you'll be spending a bit more time in the console, so it's well worth brushing up on your CLI commands. 5 | * **PowerShell:** PowerShell is a powerful object-oriented shell (as opposed to a text-based shell). It's a bit of a learning curve, but well worth it. It also has a bunch of aliases for commands, like `ls`, that'll make bash-happy people feel more at home. Here's a [good walkthrough](https://developer.rackspace.com/blog/powershell-101-from-a-linux-guy/) of some PowerShell commands from a *nix perspective, and there are [many other resources](https://technet.microsoft.com/en-us/scriptcenter/dd742419.aspx) to help you get started. 6 | * **Chocolatey:** [Chocolatey](https://chocolatey.org) is the apt-get of Windows. There are also some other alternatives like Ninite which have their own advantages, but Chocolatey is the most commonly used. 7 | * **Git:** `choco install git`. 8 | * **nvm-windows:** https://github.com/coreybutler/nvm-windows - there are new versions of Node.js coming out all the time, so it can be annoying to migrate between versions. nvm-windows makes it way easier to switch between various versions. 9 | * **npm-windows-upgrade:** npm is shipped with Node.js, and upgrading on Windows often requires manual upgrade steps. npm-windows-upgrade makes this process much easier. Install it by running `npm install npm-windows-upgrade -g`, and run the command by running `npm-windows-upgrade`. 10 | * **terminal emulators:** cmder and ConEmu. 11 | * **Cygwin:** [Cygwin](http://cygwin.com/index.html) can be handy if you're more familiar with bash, or are trying to use a Node app that assumes a *nix environment. Cygwin is a distribution of popular GNU and other open source tools running on Microsoft Windows. The core part is the Cygwin library which provides the POSIX system calls and environment these programs expect. 12 | * **Git for Windows** [Git for windows](https://git-for-windows.github.io/) provides native versions of the BASH shell and some *nix utilites in addition to the command line git and GUI tool. It is probably the best of shells based on MSYS/MinGW but still supplies ports of older versions of the *nix utilities. Works very well in combination with [ConEmu](https://conemu.github.io/). 13 | * **GitHub Desktop** [GitHub Desktop](https://desktop.github.com/) (previosuly GitHub for Windows) is primarilarly a GUI but it also includes a version of MSYS/MinGW Bash. 14 | * **Putty:** ssh client. 15 | * **WinSCP:** free [S]FTP client, also supports SCP and webDAV. 16 | * **Fiddler:** a web debugging tool. In general, people use it for the browser-side debugging, but you can also [configure it](http://stackoverflow.com/questions/8697344/can-a-proxy-like-fiddler-be-used-with-node-jss-clientrequest) to view server-side requests from Node.js. 17 | 18 | > :triangular_flag_on_post: **TODO** Provide more dev environment options and a PowerShell script to make things easier. 19 | 20 | > :chart_with_upwards_trend: **IN PROGRESS** We're currently planning the next Windows release, so it's a great time to let us know your biggest command line pain points! 21 | 22 | ## Editors and IDEs 23 | * **[Visual Studio Code](https://code.visualstudio.com/)** is a light weight code editor. Yet, it offers powerful capabilies in [editing](https://code.visualstudio.com/Docs/editor/editingevolved), [debugging](https://code.visualstudio.com/Docs/editor/debugging), and [git integration](https://code.visualstudio.com/Docs/editor/versioncontrol) for Node.js development. It is free and available on your favorite platform - Windows, Mac, and Linux. For more information, check out: http://johnpapa.net/visual-studio-code. 24 | 25 | * **[Node.js Tools for Visual Studio](https://aka.ms/explorentvs)** is a free, open-source extension that turns Visual Studio into a powerful Node.js IDE: intelligent code completions, advanced debugging and profiling, cloud deployment, unit-testing, REPL window, and more. For more information, check out these [walkthrough](https://channel9.msdn.com/events/Visual-Studio/Connect-event-2015/801) and [overview](https://channel9.msdn.com/Blogs/Seth-Juarez/Nodejs-Tools-for-Visual-Studio) videos. Note that while Visual Studio can be used as a stand-alone additional IDE 'layer' to a comprehensive commandline based workflow, several Visual Studio extensions may also prove useful: 26 | * [EditorConfig](https://visualstudiogallery.msdn.microsoft.com/c8bccfe2-650c-4b42-bc5c-845e21f96328) consistent editor spaces and indents. 27 | * [NPM scripts task runner](https://visualstudiogallery.msdn.microsoft.com/8f2f2cbc-4da5-43ba-9de2-c9d08ade4941) adds npm scripts to the Visual Studio task runner explorer. 28 | * [Web Analyzer](https://visualstudiogallery.msdn.microsoft.com/6edc26d4-47d8-4987-82ee-7c820d79be1d) various linting tools incl. ESLint. 29 | * [Web Essentials](https://visualstudiogallery.msdn.microsoft.com/ee6e6d8c-c837-41fb-886a-6b50ae2d06a2) many useful tools for client and server dev. 30 | * [GitHub Extensions for Visual Studio](https://visualstudiogallery.msdn.microsoft.com/75be44fb-0794-4391-8865-c3279527e97d) (can installed by selecting during VS installation). 31 | 32 | ## MAX_PATH explanation and workarounds 33 | For the uninitiated, MAX_PATH is a limitation with many Windows tools and APIs that sets the maximum path character length to 260 characters. There are some workarounds involving UNC paths, but unfortunately not all APIs support it, and that's not the default. This can be problematic when working with Node modules because dependencies are often installed in a nested manner. 34 | 35 | ### Workarounds 36 | 37 | * :heart: Start in a short path (e.g. c:\src) 38 | * `> npm install -g rimraf` 39 | delete files that exceed max_path 40 | * `> npm dedupe` 41 | moves duplicate packages to top-level 42 | * `> npm install -g flatten-packages` 43 | moves all packages to top-level, but can cause versioning issues 44 | * :heart: Upgrade to npm@3 which attempts to the make the `node_modules` folder heirarchy maximally flat. 45 | * Ships with Node v5 46 | * Or… > npm install –g npm-windows-upgrade 47 | * Future: 48 | * .NET file APIs: 49 | * The plan: https://www.youtube.com/watch?v=lpa2OFauASM 50 | * Progress :tada: https://github.com/dotnet/corefx/issues/645 51 | 52 | For additional discussion, please see https://github.com/Microsoft/nodejstools/issues/69 53 | 54 | ## Compiling native Addon modules 55 | There are three primary reasons you might be interested in this section: 56 | * you have an existing C++ library you'd like to take advantage of in your Node.js application 57 | * you are interested in optimizing the performance of some code by writing it in C++ 58 | * you're running into dreaded `node-gyp` issues and have no idea what's going on. 59 | 60 | ### Identifying native modules 61 | How do you know if an npm package you want to install is a native module? Look for `nan`, `node-gyp`, or `node-pre-gyp` dependencies. 62 | 63 | ### C++ and Node.js? Tell me more... 64 | * Node.js Addon documentation: https://nodejs.org/api/addons.html 65 | * NodeSchool tutorial https://github.com/workshopper/goingnative 66 | 67 | ### Environment setup and configuration: 68 | #### Prerequisites 69 | **Option 1: Standalone C++ Build Tools (Technical Preview)** 70 | 71 | 1. Install [VC++ Build Tools Technical Preview](https://www.microsoft.com/en-us/download/details.aspx?id=49983) 72 | > :bulb: [Windows 7 only] requires [.NET Framework 4.5.1](http://www.microsoft.com/en-us/download/details.aspx?id=40773) 73 | 74 | 2. Install [Python 2.7](https://www.python.org/downloads/), and add it to your `PATH`, `npm config set python python2.7` 75 | 3. Launch cmd, `npm config set msvs_version 2015 --global` (this is instead of `npm install [package name] --msvs_version=2015` every time.) 76 | 4. *SO MUCH npm install* :tada: 77 | 78 | **Option 2: Visual Studio 2015** (takes longer) 79 | * Download Python 2.7 (3.x will not work) 80 | * Download Visual Studio 2015 (free Community Edition and Express for Desktop work) 81 | 82 | > :bulb: During installation, be sure to check the the C++ option. 83 | 84 | > :chart_with_upwards_trend: **IN PROGRESS** there are currently two efforts underway to make it easier to install native modules. 85 | * We recognize that installing full VS can be burdensome, so we're investigating ways to provide a bundle with just the required compiler dependencies on Windows. Watch [this thread](https://github.com/nodejs/node-gyp/issues/629) for updates. 86 | * There are [long-term](https://github.com/nodejs/build/issues/151) efforts underway to build and cache pre-compiled packages on a server to get rid of compiler dependencies altogether. 87 | 88 | #### Verify everything's working 89 | Here are a few packages you can try installing to see if your environment is set up properly. 90 | * bson 91 | * bufferutil 92 | * kerberos 93 | * node-sass 94 | * sqlite3 95 | * phantomjs 96 | * utf-8-validate 97 | 98 | #### Resolving common issues 99 | 100 | | Errors about... | Issue | Resolution | 101 | |--------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 102 | | **Python** | Python 2.7 is not installed or can't be found | | 103 | | **Inability to find msbuild, Visual Studio, or VC compiler** | VC compiler not installed, or environment not properly configured | | 104 | | **NaN/Node/v8/iojs-related syntax errors** | Package incompatible with current version of Node.js | | 105 | | **Other syntax errors** | Incompatible with compiler version | | 106 | | **Missing command or *.h file** | Configuration is probably fine, but missing other prerequisites | | 107 | 108 | #### Deploying native modules 109 | Sometimes, when deploying a native module to production, oftentimes it is not possible to set up the production machine with all the required prerequisites to build the native Addon. Therefore, building locally or on a CI server and deploying `node_modules` may be the best option assuming there aren't any platform differences between the development and deployment machines. 110 | --------------------------------------------------------------------------------