You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on May 17, 2023. It is now read-only.
In this hands-on tutorial, we will take a look at how we can use Kotlin/JS in conjunction with the popular framework [React](https://reactjs.org/) to build appealing and maintainable applications for the browser. React lets us build web applications in a modern and well-structured way, focusing on the reusability of components and management of the application state. It is supported by a large ecosystem of community-created materials and components.
3
+
In this hands-on tutorial, we will take a look at how we can use Kotlin/JS with the popular framework [React](https://reactjs.org/) to build a first, modern reactive web app.
4
+
React lets us build web applications quickly, with a focus on component reuse and management of the application state.
5
+
It is supported by a large ecosystem of community-created materials and components.
4
6
5
-
Using Kotlin to write React applications allows us to reuse our knowledge about language paradigms, syntax, and tooling to build front-end applications for modern browsers and make use of Kotlin libraries while leveraging the capabilities of the JavaScript platform and its ecosystem.
7
+
We will get to reuse our knowledge about Kotlin's language paradigms, syntax, and tooling to build front-end applications for modern browsers.
6
8
7
-
During this hands-on, we will learn how to build our first application with Kotlin/JS and React using the `org.jetbrains.kotlin.js` Gradle plugin. We will look at the usual kinds of tasks associated with building a typical, simple React application.
9
+
During this hands-on, we will learn how to build our first application with Kotlin/JS and React.
10
+
We will go through the usual tasks associated with building a typical, simple React application.
8
11
9
-
We will explore how domain-specific languages can be used to help express concepts in a concise and uniform fashion without sacrificing readability, allowing us to write a fully-fledged application completely in Kotlin. We will also learn how to use ready-made components created by the community, make use of external libraries, and how to publish our final application.
12
+
We will explore how [Kotlin's DSLs](https://kotlinlang.org/docs/type-safe-builders.html) can be used to help us write our app completely in Kotlin.
13
+
We will also reuse some ready-made components created by the community, make use of external libraries, and see how to publish our final application.
10
14
11
-
You're expected to have a basic knowledge of Kotlin, and *very basic* knowledge of HTML and CSS. Prior knowledge of the basic concepts behind React may be helpful in understanding some of the sample code, but is not strictly required.
15
+
You're expected to have a basic knowledge of Kotlin, and a basic understanding of HTML and CSS.
16
+
Prior knowledge of the basic concepts behind React is helpful in understanding some of samples, but is not strictly required.
12
17
13
18
### What we are going to build
14
19
15
-
The annual [*KotlinConf*](https://kotlinconf.com/) is the event to visit if you want to learn more about Kotlin and exchange with the community. With 1300 attendees and a ton of workshops and sessions, KotlinConf 2018 offered a wealth of information. Its talks are publicly available on YouTube, so it may be useful for Kotlin aficionados to have an overview of the talks, quickly mark them as *seen* or *unseen*, and watch them all from one page: perfect for a Kotlin-binge-session! That is exactly the goal of *KotlinConf Explorer* – the project that we will create through this hands-on.
20
+
The annual [*KotlinConf*](https://kotlinconf.com/) is the event to visit if you want to learn more about Kotlin and exchange with the community.
21
+
With 1300 attendees and a ton of workshops and sessions, KotlinConf 2018 offered a wealth of information.
22
+
For anyone needing to still catch up, all the videos are available on YouTube!
23
+
24
+
The project that we will create throughout this tutorial - *KotlinConf Explorer* - will allow users to get an overview of the talks, quickly mark them as *seen* or *unseen*, and watch them all from one page: perfect for a Kotlin-binge-session!
You can find the source code of the final application as well as the intermediate steps on the corresponding [GitHub](https://github.com/kotlin-hands-on/web-app-react-kotlin-js-gradle) repository. Each step is available from its own branch, and is linked at the bottom of each corresponding section.
20
29
21
-
Let's start by setting up our development environment and installing the tools we’ll need to get us up and running.
30
+
Let's start by setting up our development environment to get up and running.
Copy file name to clipboardExpand all lines: Building Web Applications with React and Kotlin JS/02_Setting_up.md
+35-30Lines changed: 35 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
To get started, let's make sure we have installed an up-to-date development environment. All we need to get started is:
6
6
7
-
- IntelliJ IDEA (version `2020.3` or above) with the Kotlin plugin (`1.4.30` or above) – [Download/Install](https://www.jetbrains.com/idea/download/)
7
+
- IntelliJ IDEA (version `2021.2` or above) with the Kotlin plugin (`1.5.31` or above) – [Download/Install](https://www.jetbrains.com/idea/download/)
8
8
9
9
10
10
### Setting up the project
@@ -15,43 +15,43 @@ For this tutorial, we have made a starter template available that includes all c
15
15
16
16
The template repository contains a basic Kotlin/JS Gradle project for us to build our project. Because it already contains all dependencies that we will need throughout the hands-on, **you don't need to make any changes to the Gradle configuration.**
17
17
18
-
It is still beneficial to understand what artifacts are being used for the application, so let's have a closer look at our project template and the dependencies and configuration it relies on.
19
-
18
+
It is still beneficial to understand what we'll be using for our app. Let's have a closer look at the project template and the dependencies and configuration it relies on.
20
19
21
20
#### Gradle dependencies and tasks
22
21
23
-
Throughout the hands-on, we will make use of React, some external dependencies, and even some Kotlin-specific libraries. The topics related to each set of dependencies is described in the annotated chapter.
22
+
In this hands-on, use React, some external dependencies, and even some Kotlin-specific libraries.
Because we can't run JavaScript out of nowhere, we also need an HTML page to insert out HTML into. The file `/src/main/resources/index.html` is provided and filled accordingly:
54
+
Kotlin/JS, just like all other JavaScript in the browser, always needs to run inside an HTML page. The template includes some HTML in `/src/main/resources/index.html`:
55
55
56
56
```xml
57
57
<!doctype html>
@@ -67,14 +67,15 @@ Because we can't run JavaScript out of nowhere, we also need an HTML page to ins
67
67
</html>
68
68
```
69
69
70
-
As you can see, we're embedding a JavaScript file called `confexplorer.js`. This is because the Kotlin/JS Gradle plugin will bundle all of our code and its dependencies into a single JavaScript file, which has the same name as our project. (That also means that if you're working in a project you've named `followingAlong`, you need to make sure to embed `followingAlong.js` instead.)
70
+
In this snippet, we're embedding a JavaScript file called `confexplorer.js`.
71
+
The Kotlin/JS Gradle plugin takes care of bundling our whole project and its dependencies into that single JavaScript file, named the same as our project. (If you're working in a project you've named `followingAlong`, make sure to embed `followingAlong.js` instead.)
71
72
72
73
As is typical [JavaScript convention](https://faqs.skillcrush.com/article/176-where-should-js-script-tags-be-linked-in-html-documents), we first load the content of our body (including the `#root` div), and then finally load our scripts, to ensure that all page elements we need have already been loaded by the browser.
73
74
74
-
Now, before we write a proper "Hello, World" with actual markup, we start with a very simple and visual example – a solid colored page. This is just to verify that what we're building is actually reaching the browser and executes fine. For this, we have the file `src/main/kotlin/Main.kt`, filled with the following code snippet:
75
+
The template also starts us out with a simple code example, just to verify that everything is working fine, and we're good to go. The file `src/main/kotlin/Main.kt` contains the following snippet, which just turns the whole page red:
75
76
76
77
```kotlin
77
-
importkotlinx.browser.document
78
+
// . . .
78
79
79
80
funmain() {
80
81
document.bgColor ="red"
@@ -85,45 +86,49 @@ Now, we need to compile, run, and serve our code.
85
86
86
87
### Running the development server
87
88
88
-
The `kotlin.js` Gradle plugin comes by default with support for an embedded `webpack-dev-server`, which allows us to run the application from our IDE without having to manually set up any kind of server.
89
+
The Kotlin/JS Gradle plugin comes by default with support for an embedded `webpack-dev-server`.
90
+
This allows us to run the application from our IDE without having to manually set up any kind of server.
89
91
90
-
We can start the development server by invoking the `run` or `browserDevelopmentRun`(available in `other` directory or `kotlin browser` directory) task from the Gradle tool window inside IntelliJ IDEA:
92
+
We can start the development server by invoking the `run` or `browserDevelopmentRun`task from the Gradle tool window inside IntelliJ IDEA. They are inside the `other` and `kotlin browser` task group, respectively:
91
93
92
94
93
95
94
-
If you would like to run the program from the Terminal instead, you can do so via `./gradlew run`.
96
+
Alternatively, you can run the application in the terminal using `./gradlew run` in the root of the project.
95
97
96
-
Our project is compiled and bundled, and after a few seconds, a browser window should open up that shows a red, blank page – the indication that our code is running fine:
98
+
After our project is compiled and bundled, a browser window pops open and shows us the red, blank page mentioned before, showing that everything's working properly:
97
99
98
100
99
101
100
102
#### Enabling hot reload / continous mode
101
103
102
-
Instead of manually compiling and executing our project every time we want to see the changes we made, we can make use of the _continuous compilation_ mode that is supported by Kotlin/JS. Instead of using the regular `run` command, we instead invoke Gradle in _continuous_ mode.
104
+
Manually compiling and executing our project every time we want to see the changes we made is tedious.
105
+
Instead, we can use the _continuous compilation_ mode supported by Kotlin/JS and Gradle.
106
+
While running in this mode, the compiler will watch for changes we make in our code, automatically recompile, and reload the page while. Let's set it up.
103
107
104
-
Make sure to stop all running development server instances before proceeding.
108
+
(Make sure to stop all running development server instances before proceeding.)
105
109
106
-
From inside IntelliJ IDEA, we can pass the same flag via the _run configuration_. After running the Gradle `run` task for the first time from the IDE, IntelliJ IDEA automatically generates a run configuration for it, which we can edit:
110
+
After running the Gradle `run` task for the first time from the IDE, IntelliJ IDEA automatically generates a run configuration for it, which we can use to turn on continuous compilation:
107
111
108
112
109
113
110
-
In the "Run/Debug Configurations" dialog, we can add the `--continuous` flag to the arguments for the run configuration:
114
+
In the "Run/Debug Configurations" dialog, we add the `--continuous` flag to the arguments for the run configuration:
111
115
112
116
113
117
114
-
After applying the changes to our run configuration, we can use the play button inside IntelliJ IDEA to start our development server back up.
118
+
We then apply the changes to our run configuration.
119
+
After applying the changes to our run configuration, we can use the "Run" button inside IntelliJ IDEA to start our development server back up.
115
120
116
-
If you would like to run the Gradle continous builds from the Terminal instead, you can do so via`./gradlew run --continuous`.
121
+
If you're using the terminal, you can invoke continous mode by running`./gradlew run --continuous`.
117
122
118
-
To test the feature we have just enabled, let's change the color of the page while the Gradle task is running. We could, for example, change it to blue:
123
+
Let's make a change while that task is running! Let's switch `red` to `blue` in our `main` function, and save the change:
119
124
120
125
```kotlin
121
126
document.bgColor ="blue"
122
127
```
123
128
124
-
If everything goes well, a couple seconds after saving our change, the project should be recompiled, and our browser page reloads, reflecting the new hue.
129
+
After a few seconds, the project should be recompiled, and the page automatically reloads, having changed color.
125
130
126
-
During development, feel free to leave the development server running. It will watch for the changes we make in our code, automatically recompile, and reload the page while it is running. If you'd like, you can play around for a bit in this beginning stage, and then continue.
131
+
Feel free to keep the development server running in continuous mode while going through this tutorial. It will watch for the changes we make in our code, and automatically rebuild and reload our project for us.
0 commit comments