Fork me on GitHub

JSweet Candies

A JSweet candy is a Maven artifact that corresponds to a library/framework/API that you can include in your JSweet project to build JavaScript applications. A candy contains well-typed Java declarations, which are conceptually similar to header files in C (*.h files). Library declarations imply no runtime and are “only” used to ensure typing and the correct use of external JavaScript libraries at compile time. Candies are of two different kinds:

  • A regular candy: a bridge to an existing JavaScript library/framework/API. For instance: Backbone, Angular, JQuery, Nodejs, and Cordova are all JSweet candies. A special candy is the jsweet-core candy, which contains the core JavaScript APIs (jsweet.lang package), and the DOM APIs (jsweet.dom).
  • A J4TS candy: a JSweet implementation of a Java library/framework/API. J4TS candies are part of the J4TS project, which is initially a fork of the GWT’s JRE emulation (dropping the emulation part).

When using Maven, from Java, you can simply include any JavaScript library by adding a dependency to the corresponding candy.

Where to find candies?

Anyone can build a new candy. However, there are places where to find already-made candies.

Library kind Link Description
JavaScript Releases Releases for the automatically generated candies from DefinitelyTyped. This is the main source of candies so far. You will find most common JavaScript APIs out there. Maven group: org.jsweet.candies.
Snapshots Snapshots for the automatically generated candies from DefinitelyTyped. To be used when wanting to take advantage of latest JSweet innovations. Maven group: org.jsweet.candies.
Github/jsweet-candies In this space, you will find all manually-written candies. Manually-written candies can expose better APIs to complex frameworks because the automatic API translator may not be as human-friendly as a programmer. Maven group: org.jsweet.candies.ext.
Java Github/j4ts In this space, you will find all JSweet implementations for Java APIs. These will help the programmers to share Java code between a Java server and a WEB client. They can also help to port legacy Java applications to the WEB. Maven group: org.jsweet.candies.j4ts.
How to use
  • To find a candy for a JavaScript library, go to the release or snapshot candy page.
  • Use ctrt+f to find a candy in the page and follow the link to the candy versions. You will find a Maven dependency that you can copy-paste into your pom.xml. Also, if you clik on the small API icon, you will go to the automatically generated online Javadoc.
  • If the library you are looking for is not in the list, you can try the JSweet Candies organization on Github.
  • If you are looking for a candy for a Java library/API, go to the J4TS organization on Github.
  • If you cannot find the libary anywhere, consider writing the candy yourself (it’s not that hard), if you need some help or want to share the candy officially, please don’t hesitate to contact us.

How to create/update your own candies

Creating your own candy is quite straightforward. When creating a candy for an existing API, all you need to do it to bridge that API with well-typed Java declarations (similarly to *.h header files in C). In JSweet, you just need to declare your variables/functions/classes in a def.libname package so that JSweet understands that it is an API bridge. Declarations in the def package contain no implementations and all methods are native methods. They are compile-time entities, which are used by the compiler to ensure typing.

Note that in your JSweet project, you can create your own bridges on the fly just by creating a def package. Once you want to share these bridges with several projects, you may want to package them as actual candies (Maven artifacts). To get started, you can clone the following template, which contains a basic API bridge example packaged with Maven: jsweet-candy-js-quickstart.

Although it is simple to write your own bridges, it can be quite boring to rewrite all the APIs for a given library. JSweet provides an online API translator that can give you a head start when translating API from TypeScript definition files (*.d.ts). A TypeScript definition file contains declarations, exactly like JSweet declarations in the def package, and can be automatically translated to Java.

Finally, when writing a program with JSweet, you may want to share it with other JSweet programs, or even with TypeScript and JavaScript program. The jsweet-candy-quickstart project provides a basic template to get started packaging and publishing such projects.

JSweet Maven repositories

All official JSweet candies (from all sources listed in this page) are available from our Maven Artifactory: http://repository.jsweet.org/artifactory. You can perform advanced search to find candies and other JSweet artifacts through the Artifactory WEB GUI.

Within our Maven Artifactory, you will get the release and the snapshot repositories. You you must include these repositories in your pom.xml before declaring dependencies.

<project>
        ...
	<repositories>
		<repository>
			<id>jsweet-central</id>
			<name>libs-release</name>
			<url>http://repository.jsweet.org/artifactory/libs-release-local</url>
		</repository>
		<repository>
			<snapshots />
			<id>jsweet-snapshots</id>
			<name>libs-snapshot</name>
			<url>http://repository.jsweet.org/artifactory/libs-snapshot-local</url>
		</repository>
	</repositories>
        ...
</project>

Understanding candies versioning

A stable release can be used with corresponding releases of the candies. By using released candies for a given transpiler stable version, you can rely on the fact that candies will not change. You can confidently use them in long term projects.

A candy (JS library) release for transpiler release 1.2.0 is called: libname-x.y.z-1.2.0-yyyyMMdd, where x.y.z is the version of the candy and yyyyMMdd is the date at which the candy was released. Candies for stable releases will be released when necessary, but far less often as snapshots versions.

To keep being updated every day for a given candy, you should use the snapshot version of the candy: libname-x.y.z-SNAPSHOT, which follows the TSD updates on a daily basis. There is no warranty that a snapshot version keeps being compatible with a transpiler stable release, so it is advised to update the transpiler on a regular basis (or to use the latest transpiler snapshot) when wanting to follow the TSD modifications on a daily basis.

Note on 0.0.0 candy versions

Some TSD libraries do not have any version number but instead have a version called latest. In that case, the JSweet candy version is 0.0.0, which means latest.