src/features/nodejs-support.adoc

////
Copyright (c) 2016 NumberFour AG.
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html

Contributors:
  NumberFour AG - Initial API and implementation
////


.Node.js Support
= Node.js Support
:doctype: book
:toc: right

N4JS and its IDE are optimized to develop large scale server applications with https://nodejs.org[Node.js]
Besides launching and testing code from the IDE using Node.js, additional support is provided for automatically downloading
https://www.npmjs.com/[npm] packages and exporting N4JS projects to npm. This allows for seamless integration
of N4JS projects with existing Node.js based environments.

== Installing and using npm packages

N4JS helps Node.js developers to use third-party npm packages with support both on the language and tooling level. The
required packages can be downloaded and installed on-demand into the IDE via the library manager and this feature is also
supported in the headless tooling.

image::images/quickfixnpminstall.png[]

=== Dynamic Import

Third-party packages are supported in two different ways. If an npm package does not have any corresponding type definition
files defined yet, then the required module can be imported into an N4JS module dynamically. In order to support the import
of modules without any N4JS (`.n4js`) or N4JS type definition (`.n4jsd`) files, N4JS extends the ES2015
module import. This is done by declaring the imported module with "`+`" appended to the end of the named import.
This so called "dynamic module import" will be treated as a type of `any+`.

[source,n4js,numbered]
----
import * as mongodb+ from 'mongodb';

var client = mongodb.MongoClient;

client.connect("…", function (err, db: any+) {
    if (err) {
        console.log('Unable to connect to the mongoDB:', err);
    } else {
        …
        db.close();
        console.log('Connection closed at', url);
    }
});
----

In the example above, `mongodb` is dynamically imported. It is therefor possible to access arbitrary properties,
such as the "class" `MongoClient` in line 3. The type of these properties will become any+ as well, so that it is
possible to access properties from the class as well, as shown in line 5 and 10.


=== Automatic Download of Type Definitions

If type definitions are available at https://github.com/NumberFour/n4jsd[our N4JS type definition project] for a
particular npm package
these definitions will be included automatically when the npm package is being downloaded and installed. All npm packages with
type definitions seamlessly integrate into the N4JS system. This means that all third-party npm packages with the correct type
definitions behave just like any other N4JS module or project declared in the workspace. The language provides type safety while
the tooling provides content assist, navigation, search functionality and so on.

image::images/nodejs.png[]

The IDE also supports a way to check for any type definition updates in an on-demand fashion. This means that you can initially
begin to use any third-party packages that don't yet have type definition files. In such cases (as described above) the modules
from the npm packages have to be imported dynamically.
It's then possible to perform a manual refresh from the IDE and the
application will check for any type definition updates. If the type definitions have been declared and been made available,
meanwhile, the application will download the definitions and warn the user at the location of the dynamic imports about the
availability of the type definition file. It's then possible to switch to the type safe approach by removing the appended
`+` from the named module import.

At the moment, writing type definition files requires to manually set up a new project and configuring the manifest etc.
accordingly. We will improve supporting that to simplify users to write new and enrich existing type definitions and share
them with others via https://github.com/NumberFour/n4jsd[our N4JS type definition project] in future releases.

== Exporting N4JS projects as npm packages

Besides supporting npm package download and usage, the IDE comes with an npm package export feature.
Any N4JS workspace project can then be transformed into a structure that complies to npm requirements and can be exported
into the local file system.
These exported structures can later be used to manually publish them as packages to npm.
The corresponding `package.json` file will be created based on the dependencies declared in the N4JS manifest file of
the exported N4JS project.
Although all direct and transitive dependencies will be included in the brand new `package.json` file, only the
desired N4JS projects will be transformed and exported.
The `package.json` content can be customized by creating a `package.json` template file in the root of
the N4JS project
With this template, additional attributes can be defined.
This feature is further explained in the <<../userguides/npm-export-guide.html#npm_export_guide,npm export guide>>.