Node.js Support
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.
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+.
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 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.
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 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 npm export guide.