Update Scala.js guide - package command (#823)

lwronski · web-flow · commit c0d1df62c4d9 · 2022-03-30T16:01:40.000Z
* Update Scala.js guide - package command

* Unify the name Scala.js
diff --git a/examples/cross-build/Hello.js.scala b/examples/cross-build/Hello.js.scala
@@ -6,6 +6,6 @@ import scala.scalajs.js
 object Test {
   def main(args: Array[String]): Unit = {
     val console = js.Dynamic.global.console
-    console.log("Hello from Scala.JS")
+    console.log("Hello from Scala.js")
   }
 }
diff --git a/examples/scala-js/foojs.sc b/examples/scala-js/foojs.sc
@@ -1 +1 @@
-println(s"Hello from Scala.JS ${scala.scalajs.runtime.linkingInfo.linkerVersion}")
+println(s"Hello from Scala.js ${scala.scalajs.runtime.linkingInfo.linkerVersion}")
diff --git a/modules/build/src/main/scala/scala/build/errors/ScalaJsLinkingError.scala b/modules/build/src/main/scala/scala/build/errors/ScalaJsLinkingError.scala
@@ -1,3 +1,3 @@
 package scala.build.errors
 
-final class ScalaJsLinkingError extends BuildException("Error linking Scala.JS")
+final class ScalaJsLinkingError extends BuildException("Error linking Scala.js")
diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/HelpGroupOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/HelpGroupOptions.scala
@@ -23,7 +23,7 @@ case class HelpGroupOptions(
   }
 
   def maybePrintGroupHelp(help: Help[_]): Unit = {
-    if (helpJs) printHelpWithGroup(help, "Scala.JS")
+    if (helpJs) printHelpWithGroup(help, "Scala.js")
     else if (helpNative) printHelpWithGroup(help, "Scala Native")
   }
 }
diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/ScalaJsOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/ScalaJsOptions.scala
@@ -8,67 +8,67 @@ import com.github.plokhotnyuk.jsoniter_scala.macros._
 final case class ScalaJsOptions(
 
   @Group("Scala")
-  @HelpMessage("Enable Scala.JS. To show more options for Scala.Js pass `--help-js`")
+  @HelpMessage("Enable Scala.js. To show more options for Scala.Js pass `--help-js`")
     js: Boolean = false,
 
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("The Scala JS version")
     jsVersion: Option[String] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("The Scala JS mode, either `dev` or `release`")
     jsMode: Option[String] = None,
   @HelpMessage("The Scala JS module kind: commonjs/common, esmodule/es, nomodule/none")
-  @Group("Scala.JS")
+  @Group("Scala.js")
     jsModuleKind: Option[String] = None,
 
-  @Group("Scala.JS")
+  @Group("Scala.js")
   jsCheckIr: Option[Boolean] = None,
 
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("Emit source maps")
     jsEmitSourceMaps: Boolean = false,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("Set the destination path of source maps")
    jsSourceMapsPath: Option[String] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("Enable jsdom")
     jsDom: Option[Boolean] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("A header that will be added at the top of generated .js files")
     jsHeader: Option[String] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("Primitive Longs *may* be compiled as primitive JavaScript bigints")
     jsAllowBigIntsForLongs: Option[Boolean] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("Avoid class'es when using functions and prototypes has the same observable semantics.")
     jsAvoidClasses: Option[Boolean] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("Avoid lets and consts when using vars has the same observable semantics.")
     jsAvoidLetsAndConsts: Option[Boolean] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("The Scala JS module split style: fewestmodules, smallestmodules")
     jsModuleSplitStyle: Option[String] = None,
-  @Group("Scala.JS")
+  @Group("Scala.js")
   @HelpMessage("The Scala JS ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021")
     jsEsVersion: Option[String] = None,
 
-  @Group("Scala.JS")
-  @HelpMessage("Path to the Scala.JS linker")
+  @Group("Scala.js")
+  @HelpMessage("Path to the Scala.js linker")
   @ValueDescription("path")
   @Hidden
     jsLinkerPath: Option[String] = None,
-  @Group("Scala.JS")
-  @HelpMessage("Scala.JS CLI version to use for linking")
+  @Group("Scala.js")
+  @HelpMessage("Scala.js CLI version to use for linking")
   @ValueDescription("version")
   @Hidden
     jsCliVersion: Option[String] = None,
-  @Group("Scala.JS")
-  @HelpMessage("Scala.JS CLI Java options")
+  @Group("Scala.js")
+  @HelpMessage("Scala.js CLI Java options")
   @ValueDescription("option")
   @Hidden
     jsCliJavaArg: List[String] = Nil,
-  @Group("Scala.JS")
-  @HelpMessage("Whether to run the Scala.JS CLI on the JVM or using a native executable")
+  @Group("Scala.js")
+  @HelpMessage("Whether to run the Scala.js CLI on the JVM or using a native executable")
   @Hidden
     jsCliOnJvm: Option[Boolean] = None
 )
diff --git a/modules/cli/src/main/scala/scala/cli/commands/Package.scala b/modules/cli/src/main/scala/scala/cli/commands/Package.scala
@@ -131,7 +131,7 @@ object Package extends ScalaCommand[PackageOptions] {
   ): Either[BuildException, Option[Long]] = either {
 
     val packageType = forcedPackageType.getOrElse {
-      // FIXME We'll probably need more refined rules if we start to support extra Scala.JS or Scala Native specific types
+      // FIXME We'll probably need more refined rules if we start to support extra Scala.js or Scala Native specific types
       if (build.options.notForBloopOptions.packageOptions.isDockerEnabled)
         PackageType.Docker
       else if (build.options.platform.value == Platform.JS)
diff --git a/modules/cli/src/main/scala/scala/cli/commands/ScalaCommand.scala b/modules/cli/src/main/scala/scala/cli/commands/ScalaCommand.scala
@@ -110,7 +110,7 @@ abstract class ScalaCommand[T](implicit parser: Parser[T], help: Help[T])
         ""
       )))
       .withHiddenGroups(Some(Seq(
-        "Scala.JS",
+        "Scala.js",
         "Scala Native"
       )))
       .withTerminalWidthOpt {
diff --git a/modules/cli/src/main/scala/scala/cli/errors/ScalaJsLinkingError.scala b/modules/cli/src/main/scala/scala/cli/errors/ScalaJsLinkingError.scala
@@ -6,6 +6,6 @@ final class ScalaJsLinkingError(
   val expected: os.RelPath,
   val foundFiles: Seq[os.RelPath]
 ) extends BuildException(
-      s"Error: $expected not found after Scala.JS linking " +
+      s"Error: $expected not found after Scala.js linking " +
         (if (foundFiles.isEmpty) "(no files found)" else s"(found ${foundFiles.mkString(", ")})")
     )
diff --git a/modules/cli/src/main/scala/scala/cli/internal/ScalaJsLinker.scala b/modules/cli/src/main/scala/scala/cli/internal/ScalaJsLinker.scala
@@ -140,9 +140,9 @@ object ScalaJsLinker {
     val retCode = res.waitFor()
 
     if (retCode == 0)
-      logger.debug("Scala.JS linker ran successfully")
+      logger.debug("Scala.js linker ran successfully")
     else {
-      logger.debug(s"Scala.JS linker exited with return code $retCode")
+      logger.debug(s"Scala.js linker exited with return code $retCode")
       value(Left(new ScalaJsLinkingError))
     }
   }
diff --git a/modules/core/src/main/scala/scala/build/errors/NoFrameworkFoundByBridgeError.scala b/modules/core/src/main/scala/scala/build/errors/NoFrameworkFoundByBridgeError.scala
@@ -1,4 +1,4 @@
 package scala.build.errors
 
 final class NoFrameworkFoundByBridgeError
-    extends TestError("No framework found by Scala.JS test bridge")
+    extends TestError("No framework found by Scala.js test bridge")
diff --git a/modules/core/src/main/scala/scala/build/errors/TooManyFrameworksFoundByBridgeError.scala b/modules/core/src/main/scala/scala/build/errors/TooManyFrameworksFoundByBridgeError.scala
@@ -1,4 +1,4 @@
 package scala.build.errors
 
 final class TooManyFrameworksFoundByBridgeError
-    extends TestError("Too many frameworks found by Scala.JS test bridge")
+    extends TestError("Too many frameworks found by Scala.js test bridge")
diff --git a/modules/directives/src/main/scala/scala/build/preprocessing/directives/UsingPlatformDirectiveHandler.scala b/modules/directives/src/main/scala/scala/build/preprocessing/directives/UsingPlatformDirectiveHandler.scala
@@ -19,7 +19,7 @@ import scala.build.{Logger, Positioned}
 
 case object UsingPlatformDirectiveHandler extends UsingDirectiveHandler {
   def name             = "Platform"
-  def description      = "Set the default platform to Scala.JS or Scala Native"
+  def description      = "Set the default platform to Scala.js or Scala Native"
   def usage            = "//> using platform (jvm|scala-js|scala-native)+"
   override def usageMd = "`//> using platform `(`jvm`|`scala-js`|`scala-native`)+"
   override def examples = Seq(
diff --git a/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala b/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala
@@ -32,7 +32,7 @@ object GenerateReferenceDoc extends CaseApp[Options] {
     }
     val value = l.mkString
       .replace("Scala native", "Scala Native")
-      .replace("Scala js", "Scala.JS")
+      .replace("Scala js", "Scala.js")
       .split("\\s+")
       .map(w => if (w == "ide") "IDE" else w)
       .mkString(" ")
diff --git a/modules/integration/src/test/scala/scala/cli/integration/ExportMillTestDefinitions.scala b/modules/integration/src/test/scala/scala/cli/integration/ExportMillTestDefinitions.scala
@@ -75,7 +75,7 @@ abstract class ExportMillTestDefinitions(val scalaVersionOpt: Option[String])
     }
 
   if (runExportTests)
-    test("Scala.JS") {
+    test("Scala.js") {
       simpleTest(ExportTestProjects.jsTest(actualScalaVersion))
     }
 
diff --git a/modules/integration/src/test/scala/scala/cli/integration/ExportSbtTestDefinitions.scala b/modules/integration/src/test/scala/scala/cli/integration/ExportSbtTestDefinitions.scala
@@ -70,7 +70,7 @@ abstract class ExportSbtTestDefinitions(val scalaVersionOpt: Option[String])
     }
 
   if (runExportTests)
-    test("Scala.JS") {
+    test("Scala.js") {
       simpleTest(ExportTestProjects.jsTest(actualScalaVersion))
     }
 
diff --git a/modules/options/src/main/scala/scala/build/Artifacts.scala b/modules/options/src/main/scala/scala/build/Artifacts.scala
@@ -242,7 +242,7 @@ object Artifacts {
               None,
               forcedVersions,
               logger,
-              cache.withMessage("Downloading Scala.JS CLI"),
+              cache.withMessage("Downloading Scala.js CLI"),
               None
             )
           }
diff --git a/modules/options/src/main/scala/scala/build/options/BuildOptions.scala b/modules/options/src/main/scala/scala/build/options/BuildOptions.scala
@@ -46,7 +46,7 @@ final case class BuildOptions(
   lazy val projectParams: Either[BuildException, Seq[String]] = either {
     val platform0 = platform.value match {
       case Platform.JVM    => "JVM"
-      case Platform.JS     => "Scala.JS"
+      case Platform.JS     => "Scala.js"
       case Platform.Native => "Scala Native"
     }
     Seq(s"Scala ${value(scalaParams).scalaVersion}", platform0)
diff --git a/website/docs/commands/package.md b/website/docs/commands/package.md
@@ -8,7 +8,7 @@ The `package` command can package your Scala code in various formats, such as:
 - [standard library JARs](#library-jars)
 - so called ["assemblies" or "fat JARs"](#assemblies)
 - [docker container](#docker-container)
-- [JavaScript files](#scalajs) for Scala.JS code
+- [JavaScript files](#scalajs) for Scala.js code
 - [GraalVM native image executables](#native-image)
 - [native executables](#scala-native) for Scala Native code
 - [OS-specific formats](#os-specific-packages), such as deb or rpm (Linux), pkg (macOS), or MSI (Windows)
@@ -163,9 +163,9 @@ The following command generate a `hello-docker` image using base image `openjdk:
 scala-cli package --docker HelloDocker.scala --docker-from openjdk:11 --docker-image-repository hello-docker
 ```
 
-## Scala.JS
+## Scala.js
 
-Packaging Scala.JS applications results in a `.js` file, that can be run with `node`:
+Packaging Scala.js applications results in a `.js` file, that can be run with `node`:
 
 <!-- TODO: add something js specific -->
 
diff --git a/website/docs/commands/run.md b/website/docs/commands/run.md
@@ -89,9 +89,9 @@ scala-cli run Hello.scala --revolver
 # Watching sources, press Ctrl+C to exit.
 ```
 
-## Scala.JS
+## Scala.js
 
-Scala.JS applications can also be compiled and run with the `--js` option.
+Scala.js applications can also be compiled and run with the `--js` option.
 Note that this requires `node` to be [installed](/install#scala-js) on your system:
 
 ```bash
diff --git a/website/docs/cookbooks/scala-docker.md b/website/docs/cookbooks/scala-docker.md
@@ -36,8 +36,8 @@ docker run hello-docker
 Hello from Docker
 -->
 
-You can also package your app in the Scala.JS or Scala Native environments.
-For example, this command creates a Scala.JS Docker image:
+You can also package your app in the Scala.js or Scala Native environments.
+For example, this command creates a Scala.js Docker image:
 
 ```bash
 scala-cli package --js --docker HelloDocker.scala --docker-image-repository hello-docker
diff --git a/website/docs/guides/scala-js.md b/website/docs/guides/scala-js.md
@@ -1,19 +1,19 @@
 ---
-title: Scala.JS
+title: Scala.js
 sidebar_position: 21
 ---
 
-Scala CLI can compile, run, test, and package Scala.JS sources.
+Scala CLI can compile, run, test, and package Scala.js sources.
 
 One caveat is that Scala CLI doesn't have support for JS bundlers (such as [webpack](https://webpack.js.org))
 like [scalajs-bundler](https://github.com/scalacenter/scalajs-bundler) has.
 For this, you'll have to handle bundling yourself, with the `.js` file generated by `scala-cli`.
 
-In order to run Scala.JS sources, `node` is required.
+In order to run Scala.js sources, `node` is required.
 
 ## Configuration
 
-Enable Scala.JS support by passing `--js` to `scala-cli`, such as:
+Enable Scala.js support by passing `--js` to `scala-cli`, such as:
 
 ```scala
 scala Test.scala --js
@@ -26,6 +26,58 @@ This section is currently a work in progress, but here are some initial notes:
 - Beware platform dependencies
 - `run` / `test` / `package` should all work
 
+## Package
+
+Packaging Scala.js applications results in a `.js` file, that can be run with `node`:
+
+```scala title=HelloJs.scala
+import scala.scalajs.js
+
+object Hello {
+  def main(args: Array[String]): Unit = {
+    val console = js.Dynamic.global.console
+    val msg = "Hello World from Scala.js"
+    console.log(msg)
+  }
+}
+```
+
+```bash
+scala-cli package --js HelloJs.scala -o hello.js
+node hello.js
+# Hello World from Scala.js
+```
+
+<!-- Expected:
+Hello World from Scala.js
+-->
+
+### Module Split Style - Smallest Modules
+
+Passing `--js-module-split-style smallestmodules` to the `package` sub-command creates js modules that are as small as possible. 
+Scala.js linker generates a lot of js modules, which are copied to the `output` directory.
+
+```scala title=SmallestModules.scala
+import scala.scalajs.js
+
+case class Foo(txt: String)
+
+object Hello extends App {
+  println(Foo("Hello World from Scala.js").txt)
+}
+```
+
+```bash
+scala-cli package --js SmallestModules.scala --js-module-split-style smallestmodules --js-module-kind es --output hello 
+echo "{\"type\": \"module\"}" >> package.json # enable ES module
+node hello/main.js
+# Hello World from Scala.js
+```
+
+<!-- Expected:
+Hello World from Scala.js
+-->
+
 ## Emit source maps
 
 Passing `--js-emit-source-maps` to the `package` sub-command emits source maps alongside js files. To set the destination path of source maps, pass `--js-source-maps-path` flag with the argument.
@@ -86,11 +138,11 @@ Scala.Js options are supported by using directives in ScalaCLI:
 
 For more options, see our [`using` directive section](./reference/directives.md#scala-js-options).
 
-## Supported Scala.JS Versions
+## Supported Scala.js Versions
 
-In the future, the ScalaCLI will be able to support any version of Scala.JS independently of the version of scala-cli. But for now, there are some limitations and it isn't possible to use each version of Scala.JS. 
+In the future, the ScalaCLI will be able to support any version of Scala.js independently of the version of scala-cli. But for now, there are some limitations and it isn't possible to use each version of Scala.js. 
 
-The table below lists the last supported version of Scala.JS in ScalaCLI. If you want to use newer Scala.JS, update scala-cli.
+The table below lists the last supported version of Scala.js in ScalaCLI. If you want to use newer Scala.js, update scala-cli.
 
 | ScalaCLI versions   |      ScalaJs      | 
 |---------------------|:-----------------:|
diff --git a/website/docs/reference/cli-options.md b/website/docs/reference/cli-options.md
diff --git a/website/docs/reference/commands.md b/website/docs/reference/commands.md
diff --git a/website/docs/reference/directives.md b/website/docs/reference/directives.md

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,6 @@ import scala.scalajs.js`
`6`	`6`	`object Test {`
`7`	`7`	`def main(args: Array[String]): Unit = {`
`8`	`8`	`val console = js.Dynamic.global.console`
`9`		`- console.log("Hello from Scala.JS")`
	`9`	`+ console.log("Hello from Scala.js")`
`10`	`10`	`}`
`11`	`11`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-println(s"Hello from Scala.JS ${scala.scalajs.runtime.linkingInfo.linkerVersion}")`
	`1`	`+println(s"Hello from Scala.js ${scala.scalajs.runtime.linkingInfo.linkerVersion}")`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`package scala.build.errors`
`2`	`2`
`3`		`-final class ScalaJsLinkingError extends BuildException("Error linking Scala.JS")`
	`3`	`+final class ScalaJsLinkingError extends BuildException("Error linking Scala.js")`
Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@ case class HelpGroupOptions(`
`23`	`23`	`}`
`24`	`24`
`25`	`25`	`def maybePrintGroupHelp(help: Help[_]): Unit = {`
`26`		`- if (helpJs) printHelpWithGroup(help, "Scala.JS")`
	`26`	`+ if (helpJs) printHelpWithGroup(help, "Scala.js")`
`27`	`27`	`else if (helpNative) printHelpWithGroup(help, "Scala Native")`
`28`	`28`	`}`
`29`	`29`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,6 @@ final class ScalaJsLinkingError(`
`6`	`6`	`val expected: os.RelPath,`
`7`	`7`	`val foundFiles: Seq[os.RelPath]`
`8`	`8`	`) extends BuildException(`
`9`		`- s"Error: $expected not found after Scala.JS linking " +`
	`9`	`+ s"Error: $expected not found after Scala.js linking " +`
`10`	`10`	`(if (foundFiles.isEmpty) "(no files found)" else s"(found ${foundFiles.mkString(", ")})")`
`11`	`11`	`)`
Original file line number	Diff line number	Diff line change
`@@ -140,9 +140,9 @@ object ScalaJsLinker {`
`140`	`140`	`val retCode = res.waitFor()`
`141`	`141`
`142`	`142`	`if (retCode == 0)`
`143`		`- logger.debug("Scala.JS linker ran successfully")`
	`143`	`+ logger.debug("Scala.js linker ran successfully")`
`144`	`144`	`else {`
`145`		`- logger.debug(s"Scala.JS linker exited with return code $retCode")`
	`145`	`+ logger.debug(s"Scala.js linker exited with return code $retCode")`
`146`	`146`	`value(Left(new ScalaJsLinkingError))`
`147`	`147`	`}`
`148`	`148`	`}`