Scala-TS

Logo

Simple tool which can generate TypeScript from Scala

View the Project on GitHub scala-ts/scala-ts

Scala-TS

Scala-TS is a simple tool which generates TypeScript types from Scala types, to easily integrate REST-ful Scala backends and TypeScript frontends.

See release notes

Usage

Scala-TS can be used as a SBT plugin (recommended) or as a Scala compiler plugin, to handle generate TypeScript on Scala compilation.

Akka HTTP & Svelte example

Scala-TS is not Scala.js; Scala.js is a great tool to port Scala code to JavaScript, so it can be executed as any JS functions, whereas Scala-TS is focused on transpiling only data model types (so the frontend itself is coded in TypeScript, not in Scala).

Input Scala:

package scalats.docs

case class Incident(id: String, message: String)

Generated TypeScript:

export interface Incident {
  id: string;
  message: string;
}

// Can be used...
const incident: Incident = {
  id: 'id',
  message: 'A message'
}

See examples

More:

SBT plugin

Scala-TS can be used as a SBT plugin. It can be set up by adding to project/plugins.sbt:

addSbtPlugin("io.github.scala-ts" % "sbt-scala-ts" % "0.5.7")

Additionally, the plugin can be enabled per project.

// Not enabled by default
enablePlugins(TypeScriptGeneratorPlugin)

The TypeScript files are generated at compile-time.

sbt compile

By default, the TypeScript generation is executed in directory target/scala-ts/src_managed (see sourceManaged in scalatsOnCompile in configuration).

See SBT plugin settings

See SBT examples on GitHub

Compiler plugin

Scala-TS can also be configured as a Scalac compiler plugin using the following options.

The plugin.conf is a HOCON file that define the generator settings (see example.

See compiler settings

Type reference

Scala-TS can emit TypeScript for different kinds of Scala types declaration (see examples).

Scala TypeScript
Case class Interface
Sealed family Interface
Enumeration Enum
Value class Inner value

Scala-TS support the following scalar types for the members/fields in the transpiled declaration.

Scala TypeScript
Boolean boolean
Byte, Double, Float, Int, Long, Short number
BigDecimal, BigInt, BigInteger number
String, UUID string
Date, Instant, Timestamp Date
LocalDate, LocalDateTime Date
ZonedDateTime, OffsetDateTime Date
List, Seq, Set (any collection) ReadonlyArray
Map[K, V] (K as key type, V as value type) { [key: K]: V }
(A, B) (Tuple2 with A as first type) [A, B]
Tuple3[A, B, C] (similar for other tuple types) [A, B, C]
Either[L, R] (L on left, R on right) L | R

Option

By default, according the setting optionToNullable, Option values are generated as omitable TypeScript fields (T | undefined) or as nullable fields.

// For Option[String]
export interface Example {
  ifOptionToNullable?: string | undefined,
  otherwise: string | nullable
}

Extensions

Additionnally to the Scala-TS SBT plugin, some extensions are provided.

idonttrustlikethat

A SBT plugin extension is provided to generate TypeScript idonttrustlikethat validators, and derived types.

This can be configured by first configuring sbt-scala-ts-idtlt to the project/plugins.sbt (instead of base sbt-scala-ts).

addSbtPlugin("io.github.scala-ts" % "sbt-scala-ts-idtlt" % 0.5.7)

Then in the build.sbt is can be configured as below.

enablePlugins(TypeScriptIdtltPlugin) // Required as disabled by default

Example: Scala case class

package scalats.docs.idtlt

import java.time.LocalDate

case class Bar(
  name: String,
  age: Int,
  amount: Option[BigInt],
  updated: LocalDate,
  created: LocalDate
)

It generates the following TypeScript validators and types.

import * as idtlt from 'idonttrustlikethat';

// Validator for InterfaceDeclaration Bar
export const idtltBar = idtlt.object({
  created: idtlt.isoDate,
  updated: idtlt.isoDate,
  amount: idtlt.number.optional(),
  age: idtlt.number,
  name: idtlt.string,
});

export const idtltDiscriminatedBar = idtlt.intersection(
  idtltBar,
  idtlt.object({
    '_type': idtlt.literal('Bar')
  })
);

// Deriving TypeScript type from Bar validator
export type Bar = typeof idtltBar.T;

See demo with idonttrustlikethat