From 2d52822850ef658b80278bee9ed89cf460a9427c Mon Sep 17 00:00:00 2001 From: Adam <897017+aSemy@users.noreply.github.com> Date: Tue, 3 Oct 2023 09:46:23 +1300 Subject: [PATCH] chore: update js-project-setup.md (#3688) * type, `in` -> `is` * update: update js-project-setup.md --------- Co-authored-by: Andrey Polyakov --- docs/topics/js/js-project-setup.md | 130 +++++++++++++++-------------- 1 file changed, 68 insertions(+), 62 deletions(-) diff --git a/docs/topics/js/js-project-setup.md b/docs/topics/js/js-project-setup.md index 983f3bec11a..4c6eca9b5a7 100644 --- a/docs/topics/js/js-project-setup.md +++ b/docs/topics/js/js-project-setup.md @@ -30,7 +30,7 @@ plugins { -The Kotlin/JS Gradle plugin lets you manage aspects of your project in the `kotlin` section of the build script. +The Kotlin Multiplatform Gradle plugin lets you manage aspects of your project in the `kotlin {}` block of the build script: ```groovy kotlin { @@ -38,7 +38,7 @@ kotlin { } ``` -Inside the `kotlin` section, you can manage the following aspects: +Inside the `kotlin {}` block, you can manage the following aspects: * [Target execution environment](#execution-environments): browser or Node.js * [Project dependencies](#dependencies): Maven and npm @@ -55,35 +55,39 @@ Kotlin/JS projects can target two different execution environments: * Browser for client-side scripting in browsers * [Node.js](https://nodejs.org/) for running JavaScript code outside of a browser, for example, for server-side scripting. -To define the target execution environment for a Kotlin/JS project, add the `js` section with `browser {}` or `nodejs {}` -inside. +To define the target execution environment for a Kotlin/JS project, add the `js {}` block with `browser {}` or `nodejs {}` +inside: ```groovy kotlin { js { browser { } - binaries.executable() + binaries.executable() } -} +} ``` The instruction `binaries.executable()` explicitly instructs the Kotlin compiler to emit executable `.js` files. This is the default behavior when using the current Kotlin/JS compiler, but the instruction is explicitly required if you are working with the [Kotlin/JS IR compiler](js-ir-compiler.md), or have set `kotlin.js.generate.executable.default=false` -in your `gradle.properties`. In those cases, omitting `binaries.executable()` will cause the compiler to only generate -Kotlin-internal library files, which can be used from other projects, but not run on their own. (This is typically faster -than creating executable files, and can be a possible optimization when dealing with non-leaf modules of your project.) +in the `gradle.properties` file. In those cases, omitting `binaries.executable()` will cause the compiler to only generate +Kotlin-internal library files, which can be used from other projects, but not run on their own. + +> This is typically faster than creating executable files, +> and can be a possible optimization when dealing with non-leaf modules of your project. +> +{type="tip"} -The Kotlin/JS plugin automatically configures its tasks for working with the selected environment. +The Kotlin Multiplatform plugin automatically configures its tasks for working with the selected environment. This includes downloading and installing the required environment and dependencies for running and testing the application. This allows developers to build, run, and test simple projects without additional configuration. For projects targeting -Node.js, there are also an option to use an existing Node.js installation. Learn how to [use pre-installed Node.js](#use-pre-installed-node-js). +Node.js, there is also an option to use an existing Node.js installation. Learn how to [use pre-installed Node.js](#use-pre-installed-node-js). ## Dependencies Like any other Gradle projects, Kotlin/JS projects support traditional Gradle [dependency declarations](https://docs.gradle.org/current/userguide/declaring_dependencies.html) -in the `dependencies` section of the build script. +in the `dependencies {}` block of the build script: @@ -106,8 +110,8 @@ dependencies { -The Kotlin Multiplatform Gradle plugin also supports dependency declarations for particular source sets in the `kotlin` section -of the build script. +The Kotlin Multiplatform Gradle plugin also supports dependency declarations for particular source sets in the `kotlin {}` block +of the build script: @@ -142,8 +146,10 @@ kotlin { -Please note that not all libraries available for the Kotlin programming language are available when targeting JavaScript: -Only libraries that include artifacts for Kotlin/JS can be used. +> Not all libraries available for the Kotlin programming language are available when targeting JavaScript: +> only libraries that include artifacts for Kotlin/JS can be used. +> +{type="note"} If the library you are adding has dependencies on [packages from npm](#npm-dependencies), Gradle will automatically resolve these transitive dependencies as well. @@ -151,12 +157,12 @@ these transitive dependencies as well. ### Kotlin standard libraries The dependencies on the [standard library](https://kotlinlang.org/api/latest/jvm/stdlib/index.html) -is added automatically. The version of the standard library is the same as the version of the `kotlin-multiplatform` plugin. +are added automatically. The version of the standard library is the same as the version of the Kotlin Multiplatform plugin. The [`kotlin.test`](https://kotlinlang.org/api/latest/kotlin.test/) API is available for multiplatform tests. When you create a multiplatform project, the Project Wizard automatically adds test dependencies to all the source sets. -If you didn't use the Project Wizard to create your project, you can add the dependencies manually: +If you don't use the Project Wizard to create your project, you can add the dependencies manually: @@ -166,7 +172,7 @@ kotlin { sourceSets { val commonTest by getting { dependencies { - implementation(kotlin("test")) // This brings all the platform dependencies automatically + implementation(kotlin("test")) // Brings all the platform dependencies automatically } } } @@ -181,7 +187,7 @@ kotlin { sourceSets { commonTest { dependencies { - implementation kotlin("test") // This brings all the platform dependencies automatically + implementation kotlin("test") // Brings all the platform dependencies automatically } } } @@ -196,11 +202,11 @@ kotlin { In the JavaScript world, the most common way to manage dependencies is [npm](https://www.npmjs.com/). It offers the biggest public repository of JavaScript modules. -The Kotlin Multiplatform Gradle plugin lets you declare npm dependencies in the Gradle build script, analogous to how you would +The Kotlin Multiplatform Gradle plugin lets you declare npm dependencies in the Gradle build script, just how you declare any other dependencies. To declare an npm dependency, pass its name and version to the `npm()` function inside a dependency declaration. -You can also specify one or multiple version range based on [npm's semver syntax](https://docs.npmjs.com/misc/semver#versions). +You can also specify one or multiple version ranges based on [npm's semver syntax](https://docs.npmjs.com/misc/semver#versions). @@ -223,16 +229,16 @@ dependencies { -The plugin uses the [Yarn](https://yarnpkg.com/lang/en/) package manager to download and install NPM dependencies. +The plugin uses the [Yarn](https://yarnpkg.com/lang/en/) package manager to download and install npm dependencies. It works out of the box without additional configuration, but you can tune it to specific needs. Learn how to [configure Yarn in Kotlin Multiplatform Gradle plugin](#yarn). Besides regular dependencies, there are three more types of dependencies that can be used from the Gradle DSL. To learn more about when each type of dependency can best be used, have a look at the official documentation linked from npm: -- [devDependencies](https://docs.npmjs.com/files/package.json#devdependencies), via `devNpm(...)`, -- [optionalDependencies](https://docs.npmjs.com/files/package.json#optionaldependencies) via `optionalNpm(...)`, and -- [peerDependencies](https://docs.npmjs.com/files/package.json#peerdependencies) via `peerNpm(...)`. +* [devDependencies](https://docs.npmjs.com/files/package.json#devdependencies), via `devNpm(...)`, +* [optionalDependencies](https://docs.npmjs.com/files/package.json#optionaldependencies) via `optionalNpm(...)`, and +* [peerDependencies](https://docs.npmjs.com/files/package.json#peerdependencies) via `peerNpm(...)`. Once an npm dependency is installed, you can use its API in your code as described in [Calling JS from Kotlin](js-interop.md). @@ -243,7 +249,7 @@ The Kotlin/JS plugin provides a `jsRun` task that lets you run pure Kotlin/JS pr For running Kotlin/JS projects in the browser, this task is an alias for the `browserDevelopmentRun` task (which is also available in Kotlin multiplatform projects). It uses the [webpack-dev-server](https://webpack.js.org/configuration/dev-server/) to serve your JavaScript artifacts. -If you want to customize the configuration used by `webpack-dev-server`, for example adjust the port the server runs on, +If you want to customize the configuration used by `webpack-dev-server`, for example, adjust the port the server runs on, use the [webpack configuration file](#webpack-bundling). For running Kotlin/JS projects targeting Node.js, use the `jsRun` task that is an alias for the `nodeRun` task. @@ -282,8 +288,8 @@ The plugin also provides useful testing features, for example: * Test run results in the console For running browser tests, the plugin uses [Headless Chrome](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md) -by default. You can also choose other browser to run tests in, by adding the corresponding entries inside the `useKarma` -section of the build script: +by default. You can also choose another browser to run tests in, by adding the corresponding entries inside the `useKarma {}` +block of the build script: ```groovy kotlin { @@ -320,7 +326,7 @@ Please note that the Kotlin Multiplatform Gradle plugin does not automatically i that are available in its execution environment. If you are executing Kotlin/JS tests on a continuous integration server, for example, make sure that the browsers you want to test against are installed. -If you want to skip tests, add the line `enabled = false` to the `testTask`. +If you want to skip tests, add the line `enabled = false` to the `testTask {}`: ```groovy kotlin { @@ -342,7 +348,7 @@ To run tests, execute the standard lifecycle `check` task: ./gradlew check ``` -To specify environment variables used by your Node.js test runners (for example, to pass external information to your tests, or to fine-tune package resolution), use the `environment` function with a key-value pair inside the `testTask` block in your build script: +To specify environment variables used by your Node.js test runners (for example, to pass external information to your tests, or to fine-tune package resolution), use the `environment()` function with a key-value pair inside the `testTask {}` block in your build script: ```groovy kotlin { @@ -359,13 +365,13 @@ kotlin { ### Karma configuration The Kotlin Multiplatform Gradle plugin automatically generates a Karma configuration file at build time which includes your settings -from the [`kotlin.js.browser.testTask.useKarma` block](#test-task) in your `build.gradle(.kts)`. You can find +from the [`kotlin.js.browser.testTask.useKarma {}` block](#test-task) in your `build.gradle(.kts)`. You can find the file at `build/js/packages/projectName-test/karma.conf.js`. To make adjustments to the configuration used by Karma, place your additional configuration files inside a directory called `karma.config.d` in the root of your project. All `.js` configuration files in this directory will be picked up and are automatically merged into the generated `karma.conf.js` at build time. -All karma configuration abilities are well described in Karma's [documentation](https://karma-runner.github.io/5.0/config/configuration-file.html). +All Karma configuration abilities are well described in Karma's [documentation](https://karma-runner.github.io/5.0/config/configuration-file.html). ## webpack bundling @@ -373,7 +379,7 @@ For browser targets, the Kotlin/JS plugin uses the widely known [webpack](https: ### webpack version -The Kotlin/JS plugin uses webpack %webpackMajorVersion%. +The Kotlin Multiplatform plugin uses webpack %webpackMajorVersion%. If you have projects created with plugin versions earlier than 1.5.0, you can temporarily switch back to webpack %webpackPreviousMajorVersion% used in these versions by adding the following line @@ -386,10 +392,10 @@ kotlin.js.webpack.major.version=4 ### webpack task The most common webpack adjustments can be made directly via the -`kotlin.js.browser.webpackTask` configuration block in the Gradle build file: -- `outputFileName` - the name of the webpacked output file. It will be generated in `/build/dist/` after +`kotlin.js.browser.webpackTask {}` configuration block in the Gradle build file: +* `outputFileName` - the name of the webpacked output file. It will be generated in `/build/dist/` after an execution of a webpack task. The default value is the project name. -- `output.libraryTarget` - the module system for the webpacked output. Learn more about [available module systems for +* `output.libraryTarget` - the module system for the webpacked output. Learn more about [available module systems for Kotlin/JS projects](js-modules.md). The default value is `umd`. ```groovy @@ -399,7 +405,7 @@ webpackTask { } ``` -You can also configure common webpack settings to use in bundling, running, and testing tasks in the `commonWebpackConfig` +You can also configure common webpack settings to use in bundling, running, and testing tasks in the `commonWebpackConfig {}` block. ### webpack configuration file @@ -410,10 +416,10 @@ at the build time. It is located in `build/js/packages/projectName/webpack.confi If you want to make further adjustments to the webpack configuration, place your additional configuration files inside a directory called `webpack.config.d` in the root of your project. When building your project, all `.js` configuration files will automatically be merged into the `build/js/packages/projectName/webpack.config.js` file. -To add a new [webpack loader](https://webpack.js.org/loaders/), for example, add the following to -a `.js` file inside the `webpack.config.d`: +For example, To add a new [webpack loader](https://webpack.js.org/loaders/), add the following to +a `.js` file inside the `webpack.config.d` directory: -> In this case, the configuration object presented in the `config` global object. You need to modify it in your script. +> In this case, the configuration object is the `config` global object. You need to modify it in your script. > {type="note"} @@ -429,7 +435,7 @@ capabilities are well described in its [documentation](https://webpack.js.org/co ### Building executables -For building executable JavaScript artifacts through webpack, the Kotlin/JS plugin contains the `browserDevelopmentWebpack` +For building executable JavaScript artifacts through webpack, the Kotlin Multiplatform Gradle plugin contains the `browserDevelopmentWebpack` and `browserProductionWebpack` Gradle tasks. * `browserDevelopmentWebpack` creates development artifacts, which are larger in size, but take little time to create. @@ -455,7 +461,7 @@ The Kotlin Multiplatform Gradle plugin also provides support for webpack's [CSS] the [webpack configuration files](#webpack-bundling) that are used to build your project, the most commonly used settings are available directly from the `build.gradle(.kts)` file. -To turn on CSS support in your project, set the `cssSupport.enabled` option in the Gradle build file in the `commonWebpackConfig` +To turn on CSS support in your project, set the `cssSupport.enabled` option in the Gradle build file in the `commonWebpackConfig {}` block. This configuration is also enabled by default when creating a new project using the wizard. @@ -487,7 +493,7 @@ browser { -Alternatively, you can add CSS support independently for `webpackTask`, `runTask`, and `testTask`. +Alternatively, you can add CSS support independently for `webpackTask {}`, `runTask {}`, and `testTask {}`: @@ -549,13 +555,13 @@ an unconfigured project, such as `Module parse failed: Unexpected character '@' You can use `cssSupport.mode` to specify how encountered CSS should be handled. The following values are available: -- `"inline"` (default): styles are added to the global `