By default, the -fastopt.js and -fullopt.js files produced by Scala.js are top-level scripts, and their @JSExported stuff are sent to the global scope.With modern JavaScript toolchains, we typically write modules instead, which import and export things from other modules.You can configure Scala.js to emit a JavaScript module instead of a top-level script.

Two kinds of modules are supported: CommonJS modules (traditional module system of Node.js) and ECMAScript modules.They are enabled with the following sbt settings:

// ECMAScript
scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.ESModule) }
// CommonJS
scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.CommonJSModule) }

Important: Using this setting is incompatible with the (deprecated) setting persistLauncher := true.It is also basically incompatible with jsDependencies; use scalajs-bundler instead.

When emitting a module, @JSExportTopLevels are really exported from the Scala.js module.Moreover, you can use top-level @JSImport to import native JavaScript stuff from other JavaScript module.

For example, consider the following definitions:

import scala.scalajs.js
import scala.scalajs.js.annotation._
@js.native
@JSImport("bar.js", "Foo")
class JSFoo(val x: Int) extends js.Object
// @ScalaJSDefined // required for Scala.js 0.6.x, unless using -P:scalajs:sjsDefinedByDefault
@JSExportTopLevel("Babar")
class Foobaz(x: String) extends js.Object {
  val inner = new JSFoo(x.length)
  def method(y: String): Int = x + y
}

Once compiled under ModuleKind.ESModule, the resulting module would be equivalent to the following JavaScript module:

import { Foo as JSFoo } from "bar.js";
class Foobaz {
  constructor(x) {
    this.x = x;
    this.inner = new JSFoo(x.length);
  }
  method(y) {
    return this.x + y;
  }
}
export { Foobaz as Babar };

With ModuleKind.CommonJSModule, it would instead be equivalent to:

var bar = require("bar.js");
class Foobaz {
  constructor(x) {
    this.x = x;
    this.inner = new bar.Foo(x.length);
  }
  method(y) {
    return this.x + y;
  }
}
exports.Babar = Foobaz;

ES modules and Node.js

Support for ECMAScript modules is still experimental in Node.js.To run and test a Scala.js application or library using ES modules with Node.js, you will need the following additional settings:

jsEnv := {
  new org.scalajs.jsenv.NodeJSEnv(
      org.scalajs.jsenv.NODEJSEnv.Config()
        .withArguments(List("--experimental-modules"))
  )
}
artifactPath in (proj, Compile, fastOptJS) :=
  (crossTarget in (proj, Compile)).value / "myproject.mjs"
artifactPath in (proj, Test, fastOptJS) :=
  (crossTarget in (proj, Test)).value / "myproject-test.mjs"

The first setting is required to enable the support of ES modules in Node.js.The other two make sure that the JavaScript produced have the extension .mjs, which is required for Node.js to interpret them as ES modules.

The support for running and testing ES modules with Node.js is experimental, as the support of ES modules by Node.js is itself experimental.Things could change in future versions of Node.js and/or Scala.js.