Fork me on GitHub

Getting started

Step 1: Install (or check that you have installed) Git, Node.js and Maven (commands git, node, npm and mvn should be in your path). Java JDK 8 is required (check the version with java -version).

Step 2: Clone the jsweet-quickstart project from Github

> git clone https://github.com/cincheo/jsweet-quickstart.git
(for older versions only (v1.x)) > git checkout v1

Step 3: Run the transpiler to generate the JavaScript code

> cd jsweet-quickstart
> mvn generate-sources

Step 4: Check out the result in your browser

> firefox webapp/index.html

Step 5: Edit the project and start programming

  • Checkout the examples to see various use cases
  • Read the following sections to learn more about candies and how to use them and generate bundles
  • Refer to the language specifications to know more about programming with JSweet
  • Eclipse users: install the Eclipse plugin to get inline error reporting, build-on-save, and easy configuration UI

Candies

A JSweet candy is a Maven artifact that corresponds to a Java/JavaScript library/framework/API, which you can use in your JSweet application simply by adding a dependency to it in your pom.xml.

All you need to know about using existing candies (or creating your own) is summarized here.

Run your programs for the WEB

Candies are just typed definitions required for Java compilation (pure APIs). So, when running your program in a browser, you must not forget to include the JavaScript bundles that correspond to the candies you are using.

When having a lot of files in a program, it is useful to create a bundle so that you don’t need to include your files one by one. Also bundling your programs will take care of the dependencies and avoid the problem of referencing a class or a variable that has not been defined yet. To enable JSweet bundling, you just need to set the bundle option to true in your pom.xml. Check out the Maven plugin documentation for more information on available options.

<project ...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.jsweet</groupId>
        <artifactId>jsweet-maven-plugin</artifactId>
        <version>2.0.0-rc1</version>
        <configuration>
           <sourceMap>true</sourceMap>
           <outDir>target/js</outDir>
           <targetVersion>ES3</targetVersion>
           <!-- bundle your JS automatically -->
           <bundle>true</bundle>
           <!-- end of bundle configuration -->
        </configuration>
        ...
      </plugin>
...

Finally, you can use an external bundler, such as Browserify, to create bundles. Bundlers usually require the use of modules (for instance Browserify works with commonjs modules). See the next section to learn how to build your application with modules.

Run with Node.js

To launch your application with Node.js, you just need to use the module option, and select the commonjs module kind. Our candy repository contains all basic node packages (node, http, express, …), which are ready to use and just need to be included in your pom.xml. To run your application with node (assuming that you do not use the DOM and that you have installed the right packages with npm), just type the command line:

> node path/to/Main.js

Where Main.js is the entry point of your program, i.e. the module that corresponds to the Java class where the main method is defined.

Transpiler options

JSweet transpiler provides the following options. You can modify your pom.xml to tune way your files are transpiled.

Name Type Values Default
targetVersion enum ES3, ES5, ES6 ES3
module enum The module kind (none, commonjs, amd, system or umd). none
outDir string JS files output directory target/js
tsOut string Specify where to place generated TypeScript files. target/ts
tsOnly boolean Do not compile the TypeScript output (let an external TypeScript compiler do so). false
includes string[] Java source files to be included
excludes string[] Source files to be excluded
bundle boolean Bundle up all the generated code in a single file, which can be used in the browser. The bundle files are called ‘bundle.ts’, ‘bundle.d.ts’, or ‘bundle.js’ depending on the kind of generated code. NOTE: bundles are not compatible with any module kind other than ‘none’. false
sourceMap boolean Generate source map files for the Java files, so that it is possible to debug Java files directly with a debugger that supports source maps (most JavaScript debuggers). true
sourceRoot string Specify the location where debugger should locate Java files instead of source locations. Use this flag if the sources will be located at run-time in a different location than that at design-time. The location specified will be embedded in the sourceMap to direct the debugger where the source files will be located.
encoding string Force the Java compiler to use a specific encoding (UTF-8, UTF-16, …). UTF-8
noRootDirectories boolean Skip the root directories (i.e. packages annotated with @jsweet.lang.Root) so that the generated file hierarchy starts at the root directories rather than including the entire directory structure. false
enableAssertions boolean Java ‘assert’ statements are transpiled as runtime JavaScript checks. false
verbose boolean Turn on all levels of logging. false
jdkHome string Set the JDK home directory to be used to find the Java compiler. If not set, the transpiler will try to use the JAVA_HOME environment variable. Note that the expected JDK version is greater or equals to version 8. ${java.home}
declaration boolean Generate the d.ts files along with the js files, so that other programs can use them to compile. false
dtsOut string Specify where to place generated d.ts files when the declaration option is set (by default, d.ts files are generated in the JavaScript output directory – next to the corresponding js files). outDir
candiesJsOut string Specify where to place extracted JavaScript files from candies.
ingoreDefinitions boolean Ignore definitions from def.* packages, so that they are not generated in d.ts definition files. If this option is not set, the transpiler generates d.ts definition files in the directory given by the tsout option. false
factoryClassName string Use the given factory to tune the default transpiler behavior.
header file A file that contains a header to be written at the beginning of each generated file. If left unspecified, JSweet will generate a default header.
workingDir directory The directory JSweet uses to store temporary files such as extracted candies. JSweet uses ‘.jsweet’ if left unspecified.
disableSinglePrecisionFloats boolean By default, for a target version >=ES5, JSweet will force Java floats to be mapped to JavaScript numbers that will be constrained with ES5 Math.fround function. If this option is true, then the calls to Math.fround are erased and the generated program will use the JavaScript default precision (double precision). false
JSweet version 2 is now available!