In this tutorial we guide you through the process of setting up a web application with: - ScalaJS on the front-end - Scala (akka-http) on the back-end - Shared code between the front and back-end (isomorphism) You'll build it from the ground-up and we keep things as simple as possible. You will need a web browser (duh) and sbt installed (https://www.scala-sbt.org/), any version higher than 0.13.16 will do (we are using 1.1.6) ### Create the project Download the directory structure and [scalajs-crossproject-tutorial.tar.gz](/downloads/blog/scalajs-crossproject-tutorial.tar.gz) Extract it somewhere on your computer and notice the following directory structure:


scala-series/
├── index.html
├── project
│   ├── build.properties
│   └── plugins.sbt
├── front-end
│   └── src
│       └── main
│           └── scala
├── back-end
│   └── src
│       └── main
│           └── scala
└── shared
    └── src
        └── main
            └── scala

Only the following files have contents: - `index.html` a empty html page - `project/build.properties` the version number of sbt (1.1.6) ### Front-end We start by quickly getting scalajs up and running. First add the scalajs plugin to your `project/plugins.sbt`: ```scala addSbtPlugin("org.scala-js" % "sbt-scalajs" % "0.6.23") ``` Let's define our project inside our build file: ```scala lazy val frontEnd = (project in file("front-end")) .enablePlugins(ScalaJSPlugin) .settings( scalaVersion := "2.12.6", scalaJSUseMainModuleInitializer := true, libraryDependencies ++= Seq( "org.scala-js" %%% "scalajs-dom" % "0.9.2", "com.typesafe.play" %%% "play-json" % "2.6.0", ) ) ``` For those less familiar with scalajs: - We are enabling the scalajs plugin you added to the plugins of this project - we are using `scalaJSUseMainModuleInitializer` as we want to build a front-end application as apposed to a scalajs/javascript library - We are adding `scalajs-dom` so that we can used the DOM api using types - Later on we will be using `play-json`, we are just already defining it like we did for the back-end Cool, now let's define a application 'demo.fe.SampleFrontendApp' ```scala import org.scalajs.dom import org.scalajs.dom.Event object SampleFrontendApp { def main(args: Array[String]): Unit = { dom.window.addEventListener("load",initApplication) } def initApplication(e: Event) = { println("initialising application…") displayTitle("The Americans") displayTitle("Vinyl") } def displayTitle(title: String) = dom.document.getElementById("titles") .insertAdjacentHTML("beforeend",s"

$title

") --- ``` So we are registering an `onload` event handler in which we log to the console and we display two series titles using `displayTitle`. This helper function adds an `li` to a `ul` element that we will add to our HTML page later. Again we are just making something visible so we can quickly get everything working so that we add "complexity" to the application. Let's compile the scalajs application using sbt (and keep watching the files for recompilation) ```shell $ sbt ~frontEnd/fastOptJS ``` This should produce a javascript file named `front-end/target/scala-2.12/frontend-fastopt.js`. Brilliant let's then now change the page so that we can test our scalajs code ### The Page Open the `index.html` . You should already find a html5 template (created with emmet). First we add some content to the page including our `ul` element with id `titles`: ```html

Series

``` Now include our compiled javascript to the page (inside the `head` element) ```html … ``` You should be able to open your html page inside a browser and notice the titles are shown. Also notice the log message in your browser's development console. That works, so let's now work on our backend ### The backend For the back-end we will be using - `akka-actor`, `akka-http` and `akka-slf4j` - `akka-http-circe` and `akka-http-play-json` later on for the json marshalling "", Let's define the project inside our 'build.sbt': ```scala lazy val backEnd = (project in file("back-end")) .settings( resolvers += Resolver.bintrayRepo("hseeberger", "maven"), libraryDependencies ++= Seq( "com.typesafe.akka" %% "akka-actor" % "2.5.11", "com.typesafe.akka" %% "akka-http" % "10.1.0", "de.heikoseeberger" %% "akka-http-circe" % "1.20.0", "de.heikoseeberger" %% "akka-http-play-json" % "1.20.0", "com.typesafe.akka" %% "akka-slf4j" % "2.5.11", ) ) ``` We will place the actual akka-http route inside a trait named `demo.be.SeriesService`. Create this trait and define a route: ```scala trait SeriesService { lazy val seriesApi = path("api" / "series") { respondWithHeaders(`Access-Control-Allow-Origin`.*) { get { complete("McMafia") } } } --- ``` We will change the route later, but we are just trying to get things rolling as quick as possible. For those who are not familiar with akka-http: - We are using the akka-http DSL to define a *route* - When a request comes in rules (in the form of *directives*) determine what will be returned - In our case we have a match for a URI path `/api/series` - Any http request send to that uri will have a CORS header allowing any host to use our endpoint - When the request method is a http GET, we reply with the text "hello friend" A quick note on the CORS header allowing any host: You would normally never do that, but in our case we will test our application by just opening a html file from the filesystem. Normally you would allow just the host/port used to serve your web resources. We can now define our application. Create a new object named `demo.be.SampleServiceApp` and make it a Scala application by extending `App` plus mixin our `SeriesService` trait ```scala object SampleServiceApp extends App with SeriesService { --- ``` We then define the necessary implicits and start our server with our route rules: ```scala implicit val system = ActorSystem("my-system") implicit val materializer = ActorMaterializer() implicit lazy val ex: ExecutionContext = system.dispatcher Http().bindAndHandle(seriesApi, "0.0.0.0", 3000) onComplete { case Success(b) => println(s"server is running ${b.localAddress} ") case Failure(e) => println(s"there was an error starting the server $e") --- ``` This will open port 3000 on all local IP addresses and use our `seriesApi` route to service requests. Run your application using sbt ```shell $ sbt backEnd/run ``` Quickly test your endpoint by sending a GET request to http://localhost:3000/api/series either in your browser or using curl ```shell $ curl http://localhost:3000/api/series McMafia ``` ### Use our endpoint So time to update our front-end code and make a XHR request to our server. Add a method `getData` to make the XHR request using scalajs-dom's extension [Ajax.get](https://scala-js.github.io/scala-js-dom/#Extensions) ```scala def getData = Ajax.get("http://localhost:3000/api/series") .map(_.responseText) ``` We can then use this in our `initApplication` method ```scala import scala.concurrent.ExecutionContext.Implicits.global getData.onComplete{ case Success(v)=>displayTitle(v) case Failure(e)=>println(s"oops: $e") --- ``` Upon successful completion we display the title and in the event of a failure we write to the console. You are most likely still running the triggered execution (`sbt ~frontEnd/fastOptJS`) so you should just have to refresh your browser and you should see the series your server is sending. Top! time to add some json and a shared scala model representing a series. ### The Cross Platform Project This is where it will become really cool. We are going to define a cross project using [sbt-crossproject](https://github.com/portable-scala/sbt-crossproject) for our model classes. The `sbt-crossproject` project allows "Cross-Compiling Scala.js, JVM and Native". Add the required plugin to your `projects/plugins` (in this case we need cross-compiling for JS and the JVM) ```scala addSbtPlugin("org.portable-scala" % "sbt-scalajs-crossproject" % "0.4.0") ``` We can now define a JS/JVM cross project for our shared model: ```scala lazy val shared = crossProject(JSPlatform, JVMPlatform) .crossType(CrossType.Pure) .settings( libraryDependencies ++= Seq( "com.typesafe.play" %% "play-json" % "2.6.0", ) ) ``` The `crossType` needs explanation. This setting determines the source tree layout of the cross project. We are using `Pure` which means there will be no directories for platform-specific code. All the code will be placed in the `src` folder and is considered "shared" between scalajs and the jvm compilation. Another setting would be `Pure` which creates source directories such as `js`, `jvm` and `shared`. We have no platform-specific code, so only need a single `src` folder. Next we can define platform specific sbt *Projects* and add those as dependencies to our front- and back-end projects: ```scala lazy val sharedJVM = shared.jvm lazy val sharedJS = shared.js lazy val frontEnd = project .dependsOn(sharedJS) … lazy val backEnd = project .dependsOn(sharedJVM) … ``` Pretty cool, no? Let's define our model classes next. ### Json Model classes Within the `shared` project add a `demo.shared.Series` case class ```scala case class Series(id: String, title: String) ``` We will now define json support for our model. We have already added the dependencies to our projects. As you might have noticed we will use Play's [Json support](https://www.playframework.com/documentation/2.6.x/ScalaJson). We have also added `akka-http-json` and `akka-http-play-json` so that we can use play-json with akka-http. The reason we are using play-json and not akka's own json support is to use one json configuration for both the front and back-end (akka json does not support scalajs) This means we can define our marshaller inside the shared project! Awesome (it is really). Again inside the `shared` project add a trait named `demo.shared.JsonSupport` and define the `Format` implicit for our `Series` case class: ```scala import play.api.libs.json.Json trait JsonSupport { implicit val SeriesFormat = Json.format[Series] --- ``` Next we need to change the back- and front-ends. ### Change the Back-end We start with the back-end. Open the `demo.be.SeriesService` and mixin our `JsonSupport` plus the `PlayJsonSupport` so that akka-http can use Play's json support: ```scala import demo.shared.JsonSupport import de.heikoseeberger.akkahttpplayjson.PlayJsonSupport import demo.shared.Series trait SeriesService extends JsonSupport with PlayJsonSupport { … --- ``` Then just change the response value to return a sequence of `Series` (which will be marshaled into a json array) ```scala get { complete(Seq(Series("8219","Sense8"), Series("9214","Better Call Saul"))) --- ``` If you are still running the previous server, make sure you stop it and recompile/run your new version ```shell $ sbt backEnd/run ``` Quickly test your updated endpoint either in your browser or using curl ```shell $ curl http://localhost:3000/api/series [ { "id" : "8219", "title" : "Sense8" }, { "id" : "9214", "title" : "Better Call Saul" } ] ``` Time to update the front-end ### Update the front-end Make sure you restart the triggered execution as we have updated the build file ```shell $ sbt ~frontEnd/fastOptJS ``` Then open your `demo.fe.SampleFrontendApp` and mixin our json support class: ```scala import demo.shared.{JsonSupport, Series} object SampleFrontendApp extends JsonSupport { --- ``` Then change the `getData` method to parse (`Json.parse`) and unmarshal (`as[Seq[Series]]`) the response from our service call: ```scala def getData : Future[Seq[Series]] = Ajax.get("http://localhost:3000/api/series") .map(_.responseText) .map(Json.parse(_)) .map(_.as[Seq[Series]]) ``` As a final step change the `initApplication` and call `displayTitle` for each series returned ```scala getData.onComplete{ case Success(v)=>v.foreach(s=>displayTitle(s.title)) case Failure(e)=>println(s"oops: $e") --- ``` Refresh your page and "Wubba Lubba dub-dub, it works!" (well in excitement and not because you are in pain) You can find the solution of this tutorial on [github](https://github.com/edc4it/scalajs-crossproject-tutorial)