NPM and Ceylon JS

Integration with NPM

When compiling to JS, Ceylon can use the NPM repository. You can simply import NPM modules like this in your module definition:

import npm:"some-module" "1.2.3";

Modules that respect the CommonJS format will work seamlessly. You can import stuff from these modules in your code. If the NPM module has dashes in its name, replace them with dots so they're valid Ceylon package names.

import some.module { SomeClass, someFunction }

Since the JS compiler has no way of knowing if those are valid declarations in the module, it will just create a very simple declaration so it's usable. Uppercased declarations result in classes with a single variadic constructor, while lowercase declarations result in dynamically typed functions, so they can only be used inside dynamic blocks. Classes declared as coming from NPM modules are instantiated using new in the generated JS code.

Non-standard modules

Modules that don't follow the CommonJS format and instead return a single function have to be treated in a different way: If the function is just a simple function with no members, then it is put inside an object, under a key with the module's name. If the name contains dashes, it is changed to camel case (i.e. left-pad is changed to leftPad). If the function contains some members (for example, the express module) then the function itself is added as a member under the module's name.

Calling NPM

Both the compile-js and the run-js commands will install NPM modules if needed. A node_modules directory will be created under the working directory, by simply calling the npm command, which must be on your executable path.