https://github.com/Kotlin/kotlin-frontend-plugin

Gradle Kotlin (http://kotlinlang.org) plugin for frontend development
https://github.com/Kotlin/kotlin-frontend-plugin

gradle karma kotlin npm webpack

Last synced: 9 days ago
JSON representation

Gradle Kotlin (http://kotlinlang.org) plugin for frontend development

• Host: GitHub
• URL: https://github.com/Kotlin/kotlin-frontend-plugin
• Owner: Kotlin
• License: apache-2.0
• Archived: true
• Created: 2016-11-17T19:58:16.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2020-04-23T11:02:13.000Z (over 4 years ago)
• Last Synced: 2024-08-01T01:30:49.503Z (3 months ago)
• Topics: gradle, karma, kotlin, npm, webpack
• Language: Kotlin
• Homepage:
• Size: 544 KB
• Stars: 565
• Watchers: 45
• Forks: 69
• Open Issues: 86
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-kotlin-multiplatform - kotlin-frontend-plugin (official) - ~~Gradle plugin for frontend development.~~ (Libraries / Build & Development Tools)
• awesome-kotlin - kotlin-frontend-plugin - Gradle Kotlin (http://kotlinlang.org) plugin for frontend development (Libraries)
• awesome-list - kotlin-frontend-plugin
• trackawesomelist - Kotlin/kotlin-frontend-plugin (⭐563) - Gradle Kotlin plugin for frontend development. (Recently Updated / [Oct 28, 2024](/content/2024/10/28/README.md))

README

        
# kotlin-frontend-plugin  [ ![Download](https://api.bintray.com/packages/kotlin/kotlin-eap/kotlin-frontend/images/download.svg) ](https://bintray.com/kotlin/kotlin-eap/kotlin-frontend/_latestVersion) [![TeamCity (simple build status)](https://img.shields.io/teamcity/http/teamcity.jetbrains.com/s/KotlinTools_KotlinFrontendPlugin_Build.svg)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinFrontendPlugin_Build)

## THIS PLUGIN IS DEPRECATED

Kotlin/JS plugin contains features of `kotlin-frontend-plugin`.  

For setting up project with Kotlin/JS Gradle Plugin, please follow  

https://kotlinlang.org/docs/reference/js-project-setup.html

***

Gradle plugin for Kotlin frontend development

The plugin provides an easy way to gather Maven and npm dependencies, pack bundles (via [webpack](https://webpack.github.io/)) and test a frontend application using [Karma](https://karma-runner.github.io/1.0/index.html). By default the plugin generates all required configs for webpack, karma and manages the corresponding daemons.

By using Gradle continuous build, you also can get hot module replacement feature (apply code changes in browser on the fly). See corresponding [section below](#hot-module-replacement).

# Howto

### Configure Gradle project

First of all you have to apply plugin `org.jetbrains.kotlin.frontend` and setup Kotlin:

```gradle

buildscript {

    ext.kotlin_version = '1.3.21'

    repositories {

        jcenter()

        maven {

            url "https://dl.bintray.com/kotlin/kotlin-eap"

        }

    }

    dependencies {

        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"

        classpath "org.jetbrains.kotlin:kotlin-frontend-plugin:0.0.45"

    }

}

// apply plugin

apply plugin: 'org.jetbrains.kotlin.frontend'

// apply kotlin2js

apply plugin: 'kotlin2js'

// configure kotlin compiler

compileKotlin2Js {

    kotlinOptions.metaInfo = true

    kotlinOptions.outputFile = "$project.buildDir.path/js/${project.name}.js"

    kotlinOptions.sourceMap = true

    kotlinOptions.moduleKind = 'commonjs'

    kotlinOptions.main = "call"

}

```

### Setup npm dependencies

All frontend plugin settings are applied in `kotlinFrontend` section:

```

kotlinFrontend {

    npm {

        dependency "style-loader" // production dependency

        devDependency "karma"     // development dependency

    }

}

```

### webpack bundler

To create a webpack bundle (for both packaging and running the dev server):

```

kotlinFrontend {

    webpackBundle {

        bundleName = "main"

    }

}

```

### Complete example

See [examples/frontend-only/build.gradle](examples/frontend-only/build.gradle) for a full example.

# Building and running

To run dev server (that also will build kotlin sources):

`gradlew run`

To run tests:

- run `gradlew tests` to build the tests and start the Karma daemon

- open `http://localhost:9876` to run the tests in your browser using Karma

To pack the bundle:

`gradle bundle`

To stop running webpack and Karma daemons:

`gradle stop`

# webpack

webpack configuration: 

```

kotlinFrontend {

    webpackBundle {

        bundleName = "main"

        sourceMapEnabled = true | false   // enable/disable source maps 

        contentPath = file(...) // a file that represents a directory to be served by dev server)

        publicPath = "/"  // web prefix

        host = "localhost" // dev server host

        port = 8088   // dev server port

        proxyUrl = "" | "http://...."  // URL to be proxied, useful to proxy backend webserver

        stats = "errors-only"  // log level

    }

}

```

dev server log is located at `build/logs/webpack-dev-server.log`

config file is generated at `build/webpack.config.js`

## webpack configuration customization

To customize webpack configuration, you can apply additional scripts by placing them in the directory `webpack.config.d`. The scripts will be appended to the end of config script. Use number prefix to change order (it is very similar to UNIX rc.d config directories)

Sample structure:

- [DIR] webpack.config.d

  - css.js

  - minify.js

  - 10-apply-ealier.js

  - 20-apply-later.js

# Karma

Karma configuration:

```

kotlinFrontend {

    karma {

        port = 9876

        runnerPort = 9100

        reporters = listOf("progress") 

        frameworks = listOf("qunit") // for now only qunit works as intended

        preprocessors = listOf("...")

    }

}

```

This will generate a config file located at `build/karma.conf.js`.

Note that for your tests to run correctly with webpack their module type must be defined as well:

```

compileTestKotlin2Js {

    kotlinOptions.metaInfo = true

    kotlinOptions.moduleKind = 'commonjs'

}

```

If you would like to use a custom `karma.config.js` then specify it using `customConfigFile`:

```

kotlinFrontend {

    karma {

        customConfigFile = "myKarma.conf.js"

    }

}

```

Your custom config file will be copied to the build folder and renamed to `karma.config.js`.

karma log is located at `build/logs/karma.log`

# Hot module replacement

Webpack provides ability to apply code changes on the fly with no page reload (if possible). For reference see [Webpack Hot Module Replacement documentation](https://webpack.js.org/concepts/hot-module-replacement/)

Webpack does a lot of work for you however to get it working well most likely you have to implement state save and restore functionality via webpack's API. See [HMR.kt](examples/frontend-only/src/main/kotlin/test/hello/HMR.kt) for corresponding Kotlin external declarations for webpack API and [main.kt](examples/frontend-only/src/main/kotlin/test/hello/main.kt) for sample save/load.

Briefly at module load accept HMR feature and listen for disposal

```kotlin

module.hot?.let { hot ->

    hot.accept() // accept hot reload

    

    hot.dispose { data -> // listen for disposal events

        data.my-fields = [your application state] // put your state in the 'data' object

    }

}

```

To get previously saved state at module load use `module.hot?.data`

```kotlin

    module.hot?.data?.let { data -> // if we have previous state then we are in the middle of HMR

        myRestoreFunction(data) // so get state from the 'data' object

    }

```

Finally use Gradle continuous build with run task to get live replacement every time you change your code.

```

gradlew -t run

```