The plugin uses scalajs-bundler to download NPM packages, and translates typescript type definitions into Scala.js jars before your project compiles.
I just want to see how it works
Then check out the demo projects:
- Scalajs-bundler has some functionality where it picks up
npmDependenciesfrom your classpath. This plugin generates parts of the classpath, so to avoid a circular dependency that functionality is disabled.
- You're only supposed to use the plugin once in your build. If you really want more than one conversion make sure to shade them into different packages
This plugin needs sbt 1.7.x.
Since we generate source code, it should work with any combination of Scala 2.12 / 2.13 / 3 and Scala.js 1.10+
Add to your
addSbtPlugin("org.scalablytyped.converter" % "sbt-converter" % "1.0.0-beta39")
Activate the plugin for a project in your
Setup your npm packages
project.settings( Compile / npmDependencies ++= Seq( "react-router-dom" -> "5.1.2", "@types/react-router-dom" -> "5.1.2" ) )
Note that some packages contain first-party typescript type definitions,
while for others like
react-router-dom we need to get separate
These are originally from DefinitelyTyped.
Version numbers and
@types packages are probably most conveniently found at npmjs.com.
Choose your flavour (optional)
We have put a lot of effort into top-notch interop with two well-known Scala.js react wrapper libraries. If you want to use either make sure to choose the corresponding flavour.
project.settings( // for Slinky web projects stFlavour := Flavour.Slinky, // for Slinky native projects stFlavour := Flavour.SlinkyNative, )
project.settings( stFlavour := Flavour.Japgolly )
Use yarn instead of npm
The plugin checks for updated npm dependencies on each compile, and yarn responds much faster than npm.
Configure scalajs-bundler like this:
project.settings( useYarn := true )
Yarn will need to be present on your system for this to work. You should also check in
How it works
Hopefully everything will work automatically. Change an npm dependency, reimport project, wait, voila.
The plugin taps into the
allDependencies task in sbt, and this has some consequences for how it works.
Whenever the task is evaluated, typically through a
compile or an import into an IDE, the plugin
Runs a customized version of
installNpmDependenciesfrom scalajs-bundler, changed to avoid touching the classpath.
Computes a digest from the resulting
package.jsonfile and of the configuration of the plugin
If we have a stored conversion with the given digest and if all the generated artifacts exist locally, we return those
Otherwise we run converter, compiling only the missing libraries if any. Libraries are also digested by their contents, to avoid unnecessary recompilations.
Importing a build with a configuration the machine has seen and compiled before should be very fast.
Customize the generated code
While optional, it's recommended to have a look at conversion options to see what the possibilities are.
Have a look at Where do I start?