1.2.0 -> 2.x migration guide

[armanbilge]

⚠️ Remove CrossVersion.for3Use2_13 ⚠️

As scala-js-dom v2.x publishes a Scala 3 artifact, this setting is no longer necessary. Failing to remove this from your build.sbt will cause your library to become binary-incompatible with other libraries correctly depending on scala-js-dom v2.x.

Big picture

To address the deprecation warnings:

1. Replace imports into the dom.raw.*, dom.experimental.* and dom.crypto.* sub-packages with dom.*. Nearly everything is in dom.* now except for intl and webgl.
2. Use new-based constructors instead of apply-based constructors.

You can also automate some, hopefully the majority, of your migration by running this quick script:

find . -type f -path '*/src/*.scala' -exec perl -pi -e '
  s/\bdom\.(raw|crypto|webworkers)\./dom./;
  s/\bdom\.experimental\.[a-z]+\./dom./;
  s/\bClientRect\b/DOMRect/g;
' {} +

Additional details

Please comment with your notes and tips for a successful migration! For questions/issues with migration, please create an issue instead.

[armanbilge]

Example migration:

import org.scalajs.dom

// Before (deprecated)
val response = dom.experimental.ResponseInit(myStatus, myStatusText, myHeaders)

// After
val response = new dom.ResponseInit {
  status = myStatus
  statusText = myStatusText
  headers = myHeaders
}

Note: this example has been updated to reflect corrections made in v2.1.0. For discussion see #624.

[armanbilge]

See #627 (comment) about new-based constructors.

[yurique]

DOMList now has an implicit conversion to scala.collection.Seq, thus, In order to get a Seq out of a DOMList, the .toSeq method can be used.

(I was using org.scalajs.dom.ext.EasySeq for this purpose before, which no longer exists)

// before
val seqOfFiles = new EasySeq[File](el.ref.files.length, el.ref.files.apply).toSeq
// after
val seqOfFiles = el.ref.files.toSeq

[yurique]

org.scalajs.dom.ext.LocalStorage is gone, instead we have a dom.window.localStorage (same as in native JS API).

• instead of org.scalajs.dom.ext.LocalStorage(key) – use Option(dom.window.localStorage.getItem(key))
• instead of org.scalajs.dom.ext.LocalStorage(key) = newValue – use dom.window.localStorage.setItem(key, newValue)

[yurique]

org.scalajs.dom.NodeList now takes a type parameter – I believe Node can be used in most of the cases: NodeList[Node]

[armanbilge]

👍 yes, dom.Node can be used unless you have a more specific type T <: Node.

[yurique]

JS-native traits that don't have their vars implemented should be initialized as noted above:

val response = new dom.ResponseInit {
  var status = myStatus
  var statusText = myStatusText
  var headers = myHeaders
}

There are traits that have the vars initialized. For example, MutationObserverInit is defined like this:

trait MutationObserverInit extends js.Object {
  var childList: js.UndefOr[Boolean] = js.undefined
  // ...

These are intended to be initialized the following way:

new MutationObserverInit {
  this.childList = someChildList
}

Note that we're not overriding the var in this case, rather we're imperatively re-assigning it in the constructor.

(thanks, Sébastien, for pointing this out!) (see #624)

[armanbilge]

Another note about this: be very careful how you name your variables, to avoid circular references! This recently tripped us up in #633.

[armanbilge]

Update: since v2.1.0 all JS-native traits consistently initialize their vars to js.undefined. So the first example will no longer compile with vars:

val response = new dom.ResponseInit {
- var status = myStatus
- var statusText = myStatusText
- var headers = myHeaders
+ status = myStatus
+ statusText = myStatusText
+ headers = myHeaders
}

Thanks to @yurique for bringing this issue to our attention in #624.

[BalmungSan]

Ajax is deprecated, but you can use Fetch instad.
The usage for GET request should be straightforward, but for POST requests it may be a bit unintuitive; I hope this example helps:

Before

import org.scalajs.dom.ext.Ajax

Ajax.post(
  url = "url",
  headers = Map("header" -> "value", ...),
  data = "body"
)

After

import org.scalajs.dom.{Fetch, HttpMethod, RequestInit}

Fetch.fetch(
  "url",
  new RequestInit {
    method = HttpMethod.POST
    headers = scalajs.js.Dictionary("header" -> "value", ...)
    body = "body"
  }
).toFuture

[phdoerfler]

There used to be a package object org.scalajs.dom.ext in 1.x providing strokePath , where did it go? A full-text search for strokePath in the main branch yields 0 results, was it removed?

[sjrd]

Yes, I'm afraid it was removed. For 2.x we decided to stick to standard DOM APIs, and not add any fancy sugar on top. Use beginPath(), moveTo(), lineTo() and stroke() instead.