There are a few reasons you might want to ignore things:
- A dependency of a library you want to use might fail conversion/compilation and you can try to salvage the situation by ignoring it.
- A dependency is slow to convert/build and you have no use for it
The consequence of ignoring a library is typically that whenever another library references something in it,
that reference will be translated as
js.Any with a comment (and there will be warnings when importing).
You cannot ignore the
Some usage examples:
csstypeis a type-only library from DefinitelyTyped which describes all of react CSS with Typescript interfaces, enabling type-safe use. It is a dependency of
react, and used throughout that ecosystem. This is something you either want, or don't care about. If you don't, you can exclude it like this:
project.settings( stIgnore += "csstype" )
- Let's say you want to use an old version of
material-uiwhich comes bundled with 5000 icons, modelled as react component classes. You also don't need the icons. If that's the case, you can also exclude prefixes of module names with the same mechanism
project.settings( stIgnore ++= List("material-ui/svg-icons") )
As explained in the corresponding Scala.js documentation page,
@ScalaJSDefined traits are more convenient because they can be
newed, extended and so on.
However, there an imperfection somewhere in Scala.js and/or scalac with handling huge amounts of annotations
which makes compilation of some libraries insanely much slower.
@material-ui/core takes ~600 seconds to compile with
@ScalaJSDefined traits, and ~35 without.
This setting also uses
Selection, so an example usage is:
project.settings( stEnableScalaJsDefined := Selection.All() )
By default this is off, that is
This mirrors the
--lib option to typescript, see
project.settings( stStdlib := List("es6", "es2018.asyncgenerator") )
Note that if you use
scala-js-dom APIs they are naturally not affected.
Also note that if you use a flavour which translates types to
only types found in the chosen stdlib will be translated.
You can adjust the top-level package into which we put the generated code.
project.settings( stOutputPackage := "org.awesome.sauce", )
true (which is the default) uses scala-js-dom types when possible instead of types we translate from typescript in
true is also implied by the react flavours.
Benefit from setting to
- more comprehensive DOM API. scala-js-dom is nowhere close to the coverage typescript has. We keep all the generated types which dont exist in scala-js-dom, but the ones which are there will have fewer things defined on them.
- more coherent DOM API, since it will all be equal instead of belonging to two different worlds.
Benefit from keeping as
- less code to compile when
stMinimizeis enabled for
- easier interop with other Scala.js libraries
Enable this to configure the React flavours to prefer react components in long module paths instead of in short.
project.settings( stReactEnableTreeShaking := Selection.NoneExcept("office-ui-fabric-react") )
Typical difference in generated code:
- @JSImport("react-bootstrap", "ButtonGroup") + @JSImport("react-bootstrap/lib/ButtonGroup", JSImport.Namespace)
The difference in bundle size can be remarkable, for instance the Slinky
material-ui demo ended up one fifth of the original size.
Customize the build
Do you find the debug output tiring?
Global / stQuiet := true
By default we store caches and built artifacts in
~/.cache/scalablytyped or a similar directory for your operating system.
If that doesn't suit you, you can specify another directory
Global / stDir := file("/some/other/dir")