Indie pig.
Indie Pig Indie games and experiences.

Back to "What is Kotlin?"

Monday 24th, November 2014

A JavaScript Hello World in Kotlin

This article is at the time of Kotlin 0.9.206, and some parts are likely to be quickly out of date.

Don't be overwhelmed by the number of steps, most of these are common sense, I'm just trying to be thorough.

This article is to get a Hello World, with unit tests, up and running in Kotlin for the browser. At the time of this article, there is only one somewhat outdated tutorial I could find: writing-kotlin-in-the-browser so this is an attempt to fill in some of the gaps.

Step 1: Install IntelliJ

JetBrains will explain how to use Kotlin from the command line, but let's face it, if you're not using an IDE you probably would rather do plain JavaScript.

Download IntelliJ IDEA

This article was written using IntelliJ IDEA 14.

Step 2: Install the Kotlin Plugin

Note: If you are upgrading IDEA and previously had the plugin, be sure to uninstall the Kotlin plugin and get the latest version.

File > Settings > Plugins > Browse Repositories

Step 3: Create a new project

File > New Project

Select Kotlin, Kotlin - JavaScript

Step 4: Copy library files

You should have an empty project now that looks something like this:

Inside the lib folder you should have the kotlin-jslib.jar header files, inside the script folder there should be a runtime kotlin.js file.

Step 5: Create your web deployment directories.

We will need to set some things up so we have a place to export our javascript and html files to run the application.

Create a folder to contain the HTML files and JavaScript output. We'll use the following structure:

Step 6: Copy the kotlin.js file

Copy the kotlin.js file from your scripts folder to your web/js/lib folder.

Step 7: Create a Hello World Kotlin file.

Right click your src directory, New > Kotlin File

Step 8: Print "Hello World"

We need a package-level main function. This is our entry point.

fun main(args: Array<String>) {
	println("Hello world")
}

Step 9: Tell the compiler where to output the hello world.

At this point, we could compile, but we'd have no way to run the application. We need to set up the output path to go to our js/app folder.

File > Project Structure > Project Settings > Modules (Your module) > Paths Tab

Set the output path to your web/js/app folder.

Step 10: Create an HTML file to run.

Create a new file in your web folder called hello.html

<!DOCTYPE html>
<html>
<body>
<script src="js/lib/kotlin.js"></script>
<script src="js/app/KotlinJs.js"></script>
</body>
</html>

Step 11: Create a run configuration

Now we create a run configuration to tell IntelliJ to run your application.

Click the Edit Configurations button

Create a new JavaScript Debug configuration. NOT a Kotlin JavaScript debug configuration, that target is deprecated.

Select the html file we created in Step 10, and add Before Launch: Make

Note: This "Before Launch: Make" option only exists in IDEA 14. For 13, you will either need to run Make manually (Ctrl + F9) then this launch target (Shift + F9), or to create an artifact and then in your JavaScript Debug launch configuration add that artifact as a Before step.

Step 12: Run the application

Run the launch configuration we just made.

At this point IntelliJ will try to install a debugging plugin in your browser if you've never done this before.

Install this extension so we can see logs in the IntelliJ console and debug our application.

Now when we run, we should see a browser notification that we are debugging with IntelliJ.

Optional: The way to disable this notification in Chrome, is go to chrome://flags and enable the silent debugging flag.

If all is well, 3 things should happen, your browser should open up (with a blank page), a .js file should be created in your web/js/app folder, and in the IntelliJ console we should see a "Hello World".

Phew! That was a lot of stuff. But we're not quite done yet!

Step 13: Debugging

What use is a fancy IDE if we can't set breakpoints and debug our errors! Here's how to do that.

We must enable source maps. To do this, go to File > Settings > Build, Execution, Deployment > Compiler > Kotlin Compiler and enable source maps.

Note: At the time of this article incremental compilation (experimental) causes problems. Don't check that.

At this point, we have a Hello World, we're able to set breakpoints, and we can see our output to the console.

There is one more piece that I consider to be critical toward trying out a new language, and that is Unit Testing.


Step 14: Unit tests

Now I am not a Test Driven Development nut. I won't give you my opinions on what are the best frameworks or styles of testing to use, but I do like to write my unit tests alongside my application. I do this mainly because it simply means faster iteration time. I can focus on a single piece of code instead of an entire application.

Before we create a test, we need something simple to test. In your Hello.kt file let's create a simple class.

class Hello {
	fun hello(): String {
		return "hello"
	}
}
 
fun main(args: Array<String>) {
	println("Hello world")
}

Next create a folder named "test", and then mark that directory as a test sources root.

Oops: This doesn't seem to work with the current Kotlin build. For now, set it to a regular sources root instead of test sources root. Hopefully this is fixed soon.

Create a new kotlin file in your test folder, choose "class", and call it "HelloTest".

import org.junit.Test;
import kotlin.test.assertEquals
 
public class HelloTest {
 
	Test fun helloTest(): Unit {
		val hello = Hello();
		assertEquals("hello", hello.hello())
	}
}

Pay close attention to the imports. The "Test" annotation is what tells the test runner which methods are tests, and you must be sure the org.junit.Test class is imported for that to work.

Kotlin should work with many different kinds of test frameworks, but QUnit is the one I've tried. You can read about it here: QUnit JS

Change your html file to include the testing scripts.

<!DOCTYPE html>
<html>
<head>
	<link rel="stylesheet" href="//code.jquery.com/qunit/qunit-1.15.0.css">
</head>
<body>
 
<div id="qunit"></div>
<div id="qunit-fixture"></div>
<script src="//code.jquery.com/qunit/qunit-1.15.0.js"></script>
 
<script src="js/lib/kotlin.js"></script>
<script src="js/app/KotlinJsHelloApp.js"></script>
 
</body>
</html>

Now when you run your JavaScript Debug target you should see QUnit output.


I hope this helps people get started with Kotlin!

KotlinJVM - Hello World

 

Add your comment