Load external Node.js modules with Apache Royale

Expose Node.js modules installed from the npm registry to ActionScript

By creating type definitions with special metadata, developers can use Node.js modules from ActionScript code using Apache Royale.

Let’s try to use the boxen module from the npm registry in ActionScript. This module draws a box around a string to display in the console, and it exposes many styling options like colors, borders, and alignment.

First, make sure to install the boxen module in your project’s root folder:

npm install boxen

To install a module from the npm registry, you must have Node.js installed.

Define the module’s API in ActionScript

Create a file named boxen.as and add the following code:

package
{
	/**
	 * @externs
	 */
	[JSModule(name="boxen")]
	public native function boxen(message:String, options:Object = null):String;
}

This file will tell the Apache Royale compiler how to access the “boxen” module in the generated JavaScript. Let’s look in more detail at each part of this file.

All type definitions must include the @externs asdoc tag.

/**
 * @externs
 */

Additionally, type definitions for Node.js modules must include [JSModule] metadata.

[JSModule(name="boxen")]

Set the name field inside [JSModule] to the string that should be passed to a require() call in JavaScript to load the module.

The default export of a module should either be a class, a function, or a variable. In this case, the default export of the “boxen” module is a function.

public native function boxen(message:String, options:Object = null):String;

The name of the default export should be derived from the name of the module. In this case, the name of the module and the name of the function are both boxen.

If the module name contains dashes, the symbol name should be converted to camel case. For example, [JSModule(name="my-example-module")] would require the symbol to be named myExampleModule.

By specifying that the function is native, no body is required.

Use a Node.js module in ActionScript

Create a file named MyScript.as, and add the following content:

package
{
	public class MyScript
	{
		public function MyScript()
		{
			var result:String = boxen("I loaded a module!");
			trace(result);
		}
	}
}

This simple script passes a string to boxen(), and then it writes the result to the console.

Compile with asnodec

Using Apache Royale’s asnodec compiler, compile the project into JavaScript code that can be run with Node.js:

asnodec MyScript.as

The generated JavaScript code will be created in the bin/js-debug folder for debug builds, and the bin/js-release folder for release builds.

Run the project

To run the generated JavaScript, you must have Node.js installed.

Use the following command to run the compiled project:

node bin/js-release/index.js

The following output will appear in the console:

┌────────────────────────┐
│                        │
│   I loaded a module!   │
│                        │
└────────────────────────┘