Improve GCC/ Minifier documentation

[OndrejSpanel]

I would like to experiment with the new minifier a bit. How can I control if the new minifier or GCC is used?

I find the documentation about scalaJSLinkerConfig a bit lacking, esp. when Google often shows me pages which are quite old.

The documentation I am aware of:

https://www.scala-js.org/doc/project/module.html
https://www.scala-js.org/doc/internals/compile-opt-pipeline.html

#4482 mentions:

We automatically enable the new minifier under fullLink when GCC is disabled. This can be overridden with a scalaJSLinkerConfig setting.

There is no more explanation.

In LinkerBackendImpl.scala I can see some functions which look they might do something:

withClosureCompilerIfAvailable
withMinify

Similar properties can be seen in https://www.scala-js.org/api/scalajs-linker-interface-js/latest/org/scalajs/linker/interface/StandardConfig.html, but there is no documentation for them.

I guess when I want to use the new minifier I want:

fullOptJS / scalaJSLinkerConfig ~= (_.withClosureCompiler(false).withMinify(true))

[gzm0]

Yes. Also, the config is documented in source:
linker-interface/shared/src/main/scala/org/scalajs/linker/interface/StandardConfig.scala

Seems like the scaladoc comments are not in the right place. We should obviously fix that.

[OndrejSpanel]

I do not think the GCC stops being used unless I use scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.ESModule) }. With CommonJSModule I always see [info] Closure: 0 error(s), 0 warning(s) and the filesize is exactly what is was before.

[gzm0]

Ah, right. I think you need to scope it in the config as well:

Compile / fullLinkJS / scalajsLinkerConfig

[OndrejSpanel]

Confirmed, with Compile / fullLinkJS I can choose the minifier.

Why is the Compile scope not needed for withModuleKind, but is needed for withMinify? How about withOptimizer - does it need the Compile scope as well?

I am checking some other basic documentation and tutorials. If you clone https://github.com/scala-js/scalajs-tutorial, it uses ancient versions of sbt and Scala.js, IntelliJ is unable to import the project. I can prepare PR for that if desired.

A bit related: it seems the minifier assumes some other JS minification will be done later in the pipeline, at least its ScalaDoc says so. Would this also be in scope of the Basic Tutorial?

[gzm0]

Why is the Compile scope not needed for withModuleKind, but is needed for withMinify?

Because of how we configure the fullLink config:

scala-js/sbt-plugin/src/main/scala/org/scalajs/sbtplugin/ScalaJSPluginInternal.scala

Lines 468 to 475 in 80eafa9

	scalaJSLinkerConfig in fullOptJS ~= { prevConfig =>
	val useClosure = prevConfig.moduleKind != ModuleKind.ESModule
	prevConfig
	.withSemantics(_.optimized)
	.withClosureCompiler(useClosure)
	.withMinify(true) // ignored if we actually use Closure
	.withCheckIR(true) // for safety, fullOpt is slow anyways.
	},

You'll notice this is scoped in both the configuration and the task. I guess at some point in the past, we decided (explicitly or implicitly) it's more important to be able to re-configure configs easily then re-configure fast v.s. full defaults easily. (I'm making the assumption here that sbt axis are not hierarchical but I believe this is the case).

I can prepare PR for that if desired.

Always appreciated. Please do note that the commit structure of that repo is a bit odd: The commits correspond to steps. So you essentially need to rewrite its entire history to update it.

Would this also be in scope of the Basic Tutorial?

IMO no. The basic tutorial is officially "old" (as you can see from the Tutorial Overview). The Scala.js and Vite tutorial does perform JS minification (or more precisely Vite's production build does).

[OndrejSpanel]

Thanks for the explanation.

How about withOptimizer - does it need the Compile scope as well?

Still unclear about withOptimizer(false) - should it be used from Compile / fastOptJS or just fastOptJS?

[sjrd]

First, always use fastLinkJS/fullLinkJS when configuring, even if you use the Opt tasks in the end.

Second, just fastLinkJS / never does anything. It's always Compile / fastLinkJS /.

[OndrejSpanel]

Explanation is good, but the main point of this issue is to improve documentation so that the explanation here is not necessary.

Besides the links I have provided, some related documentation seems to be present in https://www.scala-js.org/doc/project/building.html as well. However I doubt I want to have this in my SBT:

scalaJSLinkerConfig ~= { _.withOptimizer(false) }

I would almost certanly want to disable optimizer for fastOpt only, because that is where I expect to do my debugging.

[OndrejSpanel]

First, always use fastLinkJS/fullLinkJS when configuring

I have tried it now with the Scala.js Tutorial project.

This affects fastOptJS output:

Compile / fastOptJS / scalaJSLinkerConfig ~= (_.withOptimizer(false))
Compile / fastLinkJS / scalaJSLinkerConfig ~= (_.withOptimizer(false))
fastOptJS / scalaJSLinkerConfig ~= (_.withOptimizer(false))

This does not:

fastLinkJS / scalaJSLinkerConfig ~= (_.withOptimizer(false))

[gzm0]

Regarding the doc of StandardConfig: I've attempted to move the doc comments to @params to make them appear in Scaladoc (based off scala/bug#577), but it seems this has no effect :-/ I do not know where the doc comments for the fields should go.