Skip to content

Latest commit

 

History

History
108 lines (87 loc) · 13.6 KB

windows-environment.md

File metadata and controls

108 lines (87 loc) · 13.6 KB
Raw

Configuring your Windows development environment

Command line console and other useful tools

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. 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.

  • cmd: cmd has had some improvements in Windows 10, so be sure to check it out if you abandoned ship in the past 😃. 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.
  • 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 of some PowerShell commands from a *nix perspective, and there are many other resources to help you get started.
  • Chocolatey: Chocolatey 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.
  • Git: choco install git.
  • 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.
  • 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.
  • terminal emulators: cmder and ConEmu.
  • Cygwin: Cygwin 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.
  • Git for Windows Git for windows 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.
  • GitHub Desktop GitHub Desktop (previosuly GitHub for Windows) is primarilarly a GUI but it also includes a version of MSYS/MinGW Bash.
  • Putty: ssh client.
  • WinSCP: free [S]FTP client, also supports SCP and webDAV.
  • Fiddler: a web debugging tool. In general, people use it for the browser-side debugging, but you can also configure it to view server-side requests from Node.js.

🚩 TODO Provide more dev environment options and a PowerShell script to make things easier.

📈 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!

Editors and IDEs

MAX_PATH explanation and workarounds

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.

Workarounds

  • ❤️ Start in a short path (e.g. c:\src)
  • > npm install -g rimraf delete files that exceed max_path
  • > npm dedupe moves duplicate packages to top-level
  • > npm install -g flatten-packages moves all packages to top-level, but can cause versioning issues
  • ❤️ Upgrade to npm@3 which attempts to the make the node_modules folder heirarchy maximally flat.
    • Ships with Node v5
    • Or… > npm install –g npm-windows-upgrade
  • Future:

For additional discussion, please see microsoft/nodejstools#69

Compiling native Addon modules

There are three primary reasons you might be interested in this section:

  • you have an existing C++ library you'd like to take advantage of in your Node.js application
  • you are interested in optimizing the performance of some code by writing it in C++
  • you're running into dreaded node-gyp issues and have no idea what's going on.

Identifying native modules

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.

C++ and Node.js? Tell me more...

Environment setup and configuration:

Prerequisites

  1. Visual C++ Build Environment:

  • Option 1: Install Visual C++ Build Tools (Technical Preview), choose Custom Install, and select both the Windows 8.1 and Windows 10 SDKs.

  • Option 2: Install Visual Studio 2015 (or modify an existing installation) and select Common Tools for Visual C++ during setup. This also works with the free Community and Express for Desktop editions.

💡 [Windows Vista / 7 only] requires .NET Framework 4.5.1

  1. Install Python 2.7 (v3.x.x is not supported), and run npm config set python python2.7
  2. Launch cmd, npm config set msvs_version 2015

📈 IN PROGRESS there are currently two efforts underway to make it easier to install native modules.

  • We recognize that installing full VS can be burdensome, and we released the more minimal Visual C++ Build tools to help resolve this issue. The Build Tools are still in Technical preview, so please let us know if you run into any Windows-specific configuration issues so we can address them in the next release, and watch this thread for updates.
  • There are long-term efforts underway to build and cache pre-compiled packages on a server to get rid of compiler dependencies altogether.

Verify everything's working

Here are a few packages you can try installing to see if your environment is set up properly.

  • bson
  • bufferutil
  • kerberos
  • node-sass
  • sqlite3
  • phantomjs
  • utf-8-validate

Resolving common issues

Errors about... Issue Resolution
Python Python 2.7 is not installed or can't be found
  • Install Python 2.7 and add to PATH
  • Specifiy --python=2.7 during npm install
  • npm config set python 2.7 to set default
Inability to find msbuild, Visual Studio, or VC compiler VC compiler not installed, or environment not properly configured
  • Install VC++ compiler
  • Specify --msvs_version=2015 (or other VS version)
  • npm config set msvs_version 2015 -g
NaN/Node/v8/iojs-related syntax errors Package incompatible with current version of Node.js
  • Upgrade to latest version of package + node.js, and see if issue still exists
  • Search issues and/or file an issue on package repo
Other syntax errors Incompatible with compiler version
  • Upgrade to latest version of package + node.js, and see if issue still exists
  • Search issues and/or file an issue on package repo
*Missing command or .h file Configuration is probably fine, but missing other prerequisites
  • Upgrade to latest version of package
  • Check docs, try to install missing prerequisites, ensure they're accessible in PATH
  • Search for header file or other pre-requisite that's missing, that may provide a clue where it's supposed to come from (e.g. Windows SDK not installed, OpenSSL, etc.)
  • Search issues and/or file an issue on package repository

Deploying native modules

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.