| Usage: kotlinc-js <options> <source files> | |
| where advanced options include: | |
| -Xdts-use-unknown-instead-any Export 'dynamic' and 'Any' Kotlin types as 'unknown' TypeScript type (instead of `any`). | |
| -Xenable-extension-functions-in-externals | |
| Enable extension function members in external interfaces. | |
| -Xenable-implementing-interfaces-from-typescript | |
| Enable exporting of Kotlin interfaces to implement them from JavaScript/TypeScript. | |
| -Xenable-suspend-function-exporting | |
| Enable exporting suspend functions to JavaScript/TypeScript. | |
| -Xes-arrow-functions Use ES2015 arrow functions in the JavaScript code generated for Kotlin lambdas. Enabled by default in case of ES2015 target usage | |
| -Xes-classes Let generated JavaScript code use ES2015 classes. Enabled by default in case of ES2015 target usage | |
| -Xes-generators Enable ES2015 generator functions usage inside the compiled code. Enabled by default in case of ES2015 target usage | |
| -Xes-long-as-bigint Compile Long values as ES2020 bigint instead of object. | |
| -Xexport-kdoc Export KDoc entries as JSDoc into the TypeScript declaration files. | |
| -Xgenerate-polyfills Generate polyfills for features from the ES6+ standards. | |
| -Xinteger-division-check Check for division by zero in integer arithmetic and throw ArithmeticException. | |
| -Xir-build-cache Use the compiler to build the cache. | |
| -Xir-generate-inline-anonymous-functions | |
| Lambda expressions that capture values are translated into in-line anonymous JavaScript functions. | |
| -Xir-keep Comma-separated list of fully qualified names not to be eliminated by DCE (if it can be reached), and for which to keep non-minified names. | |
| -Xir-minimized-member-names Minimize the names of members. | |
| -Xir-per-file Generate one .js file per source file. | |
| -Xir-per-module Generate one .js file per module. | |
| -Xir-safe-external-boolean Wrap access to external 'Boolean' properties with an explicit conversion to 'Boolean'. | |
| -Xir-safe-external-boolean-diagnostic={log|exception} | |
| Enable runtime diagnostics when accessing external 'Boolean' properties. | |
| -Xoptimize-generated-js Perform additional optimizations on the generated JS code. | |
| -Xplatform-arguments-in-main-function | |
| JS expression that will be executed in runtime and be put as an Array<String> parameter of the main function | |
| -Xsuspend-lambda-exporting Enable exporting suspend lambdas to JavaScript/TypeScript. | |
| -Xir-dce-dump-reachability-info-to-file=<path> | |
| Dump reachability information collected about declarations while performing DCE to a file. The format will be chosen automatically based on the file extension. Supported output formats include JSON for .json, a JS const initialized with a plain object containing information for .js, and plain text for all other file types. | |
| -Xir-dump-declaration-ir-sizes-to-file=<path> | |
| Dump the IR size of each declaration into a file. The format will be chosen automatically depending on the file extension. Supported output formats include JSON for .json, a JS const initialized with a plain object containing information for .js, and plain text for all other file types. | |
| -Xwasm Use the WebAssembly compiler backend. | |
| The option is deprecated since Kotlin 2.4.0. It will be removed in one of the future releases. Use kotlinc-wasm or the KotlinWasmCompiler class instead to compile to WebAssembly. | |
| -Xwasm-IC-generate-unchanged-modules | |
| Regenerate unchanged modules in multimodule IC. | |
| -Xwasm-debug-friendly Avoid optimizations that can break debugging. | |
| -Xwasm-debug-info Add debug info to the compiled WebAssembly module. | |
| -Xwasm-debugger-custom-formatters | |
| Generates devtools custom formatters (https://firefox-source-docs.mozilla.org/devtools-user/custom_formatters) for Kotlin/Wasm values | |
| -Xwasm-disable-array-range-checks-safe-elimination | |
| Disable bounds check elimination for provably-safe array accesses in for-loops. Only effective when -Xwasm-enable-array-range-checks is also enabled. | |
| -Xwasm-enable-array-range-checks | |
| Turn on range checks for array access functions. | |
| -Xwasm-enable-asserts Turn on asserts. | |
| -Xwasm-enable-tail-calls Emit WebAssembly tail call instructions (return_call / return_call_indirect). | |
| -Xwasm-generate-closed-world-multimodule | |
| Compile modules in multi-module closed-world mode using module passed in `-include` argument as main module | |
| -Xwasm-generate-dwarf Generate DWARF debug information. | |
| -Xwasm-generate-wat Generate a .wat file. | |
| -Xwasm-included-module-only Compile only a module passed using `-include` option. | |
| -Xwasm-internal-local-variable-prefix | |
| Prefix to use for internally generated local variables. | |
| -Xwasm-kclass-fqn Enable support for 'KClass.qualifiedName'. | |
| -Xwasm-no-jstag Don't use WebAssembly.JSTag for throwing and catching exceptions | |
| -Xwasm-source-map-include-mappings-from-unavailable-sources | |
| Insert source mappings from libraries even if their sources are unavailable on the end-user machine. | |
| -Xwasm-target={wasm-js|wasm-wasi} | |
| Set up the Wasm target (wasm-js or wasm-wasi). | |
| -Xwasm-use-new-exception-proposal | |
| Use an updated version of the exception proposal with try_table. | |
| -Xwasm-use-stack-switching-proposal | |
| Compile Kotlin Coroutines with WebAssembly Stack Switching Proposal | |
| -Xwasm-use-traps-instead-of-exceptions | |
| Use traps instead of throwing exceptions. | |
| -Xcache-directory=<path> Path to the cache directory. | |
| -Xenable-advanced-optimizations | |
| Enable experimental advanced optimization passes (e.g. effect analysis). | |
| -Xfriend-modules=<path> Paths to friend modules. | |
| -Xfriend-modules-disabled Disable internal declaration export. | |
| -Xgenerate-dts Generate a TypeScript declaration .d.ts file alongside the JS file. | |
| -Xinclude=<path> Path to an intermediate library that should be processed in the same manner as source files. | |
| -Xir-dce Perform experimental dead code elimination. | |
| -Xir-dce-print-reachability-info | |
| Print reachability information about declarations to 'stdout' while performing DCE. | |
| -Xir-dce-runtime-diagnostic={log|exception} | |
| Enable runtime diagnostics instead of removing declarations when performing DCE. | |
| -Xir-module-name=<name> Specify the name of the compilation module for the IR backend. | |
| -Xir-per-module-output-name Add a custom output name to the split .js files. | |
| -Xir-produce-js Generate a JS file using the IR backend. | |
| -Xir-produce-klib-dir Generate an unpacked klib into the parent directory of the output JS file. | |
| The option is deprecated since Kotlin 2.4.20. It will be removed in one of the future releases. Use '-nopack' instead to determine if a packed klib file will be produced. Setting this argument to something other than `null` overrides the value from '-nopack'. | |
| -Xir-produce-klib-file Generate a packed klib into the directory specified by '-ir-output-dir'. | |
| The option is deprecated since Kotlin 2.4.20. It will be removed in one of the future releases. Producing a packed klib is now the default behavior. The '-nopack' argument can be used instead to determine if a packed klib file will be produced. Setting this argument to something other than `null` overrides the value from '-nopack'. | |
| -Xir-property-lazy-initialization | |
| Perform lazy initialization for properties. | |
| -Xstrict-implicit-export-types Generate strict types for implicitly exported entities inside d.ts files. | |
| -Xklib-abi-version=<version> Specify the custom ABI version to be written in KLIB. This option is intended only for tests. | |
| Warning: This option does not affect KLIB ABI. Neither allows it making a KLIB backward-compatible with older ABI versions. | |
| The only observable effect is that a custom ABI version is written to KLIB manifest file. | |
| -Xklib-duplicated-unique-name-strategy={deny|allow-all-with-warning|allow-first-with-warning} | |
| Klib dependencies usage strategy when multiple KLIBs has same `unique_name` property value. | |
| -Xklib-enable-signature-clash-checks | |
| Enable signature uniqueness checks. | |
| -Xklib-ir-inliner={intra-module|full|disabled|default} | |
| Set the mode of the experimental IR inliner on the first compilation stage. | |
| - `intra-module` mode enforces inlining of the functions only from the compiled module | |
| - `full` mode enforces inlining of all functions (from the compiled module and from all dependencies) | |
| Warning: This mode will trigger setting the `pre-release` flag for the compiled library. | |
| - `disabled` mode completely disables the IR inliner | |
| - `default` mode lets the IR inliner run in `intra-module`, `full` or `disabled` mode based on the current language version | |
| -Xklib-relative-path-base Relativize all the paths stored in a klib using the given path prefixes. | |
| The supplied prefixes should be absolute paths to the directories containing the source code files. | |
| Note: The prefixes are applied in the same order as they are passed in this CLI argument. | |
| -Xklib-zip-file-accessor-cache-limit | |
| Maximum number of klibs that can be cached during compilation. Default is 64. | |
| -Xpartial-linkage={enable|disable} | |
| Enables partial linkage mode. | |
| The option is deprecated since Kotlin 2.4.0. It will be removed in one of the future releases. The partial linkage engine is always turned on. If you want to adjust the compile-time log level for partial linkage, use -Xpartial-linkage-loglevel. | |
| -Xpartial-linkage-loglevel={silent|info|warning|error} | |
| Define the compile-time log level for partial linkage. | |
| -Xskip-library-special-compatibility-checks | |
| Skip library compatibility checks for stdlib and kotlin.test library. | |
| -Xallow-any-scripts-in-source-roots | |
| Allow compiling scripts along with regular Kotlin sources. | |
| -Xallow-condition-implies-returns-contracts | |
| Allow contracts that specify a limited conditional returns postcondition. | |
| -Xallow-contracts-on-more-functions | |
| Allow contracts on some operators and accessors, and allow checks for erased types. | |
| -Xallow-holdsin-contract Allow contracts that specify a condition that holds true inside a lambda argument. | |
| -Xallow-kotlin-package Allow compiling code in the 'kotlin' package, and allow not requiring 'kotlin.stdlib' in 'module-info'. | |
| -Xallow-pre-17-runtime-jdk Temporarily allow running Kotlin compiler with JDK older than JDK 17. This option will not work starting Kotlin 2.5.20-Beta1. See https://jb.gg/kotlin-compiler-jdk-17-migration for more details. | |
| -Xallow-reified-type-in-catch Allow 'catch' parameters to have reified types. | |
| -Xallow-returns-result-of Allows to use `returnsResultOf()` in `contract {}` block of function body. This contract provides additional information for return value checker. Enabling this feature will force compiler to produce pre-release binaries, because this functions with this contract cannot be read correctly by Kotlin 2.3 and lower. | |
| -Xannotation-default-target=first-only|first-only-warn|param-property | |
| Change the default annotation targets for constructor properties: | |
| -Xannotation-default-target=first-only: use the first of the following allowed targets: '@param:', '@property:', '@field:'; | |
| -Xannotation-default-target=first-only-warn: same as first-only, and raise warnings when both '@param:' and either '@property:' or '@field:' are allowed; | |
| -Xannotation-default-target=param-property: use '@param:' target if applicable, and also use the first of either '@property:' or '@field:'; | |
| default: 'param-property' in language version 2.4+, 'first-only-warn' in language versions 2.2 & 2.3, 'first-only' in version 2.1 and before. | |
| -Xannotation-target-all Enable experimental language support for @all: annotation use-site target. | |
| -Xcallable-references-to-contextual | |
| Enable callable references to contextual declarations. | |
| -Xcheck-phase-conditions Check pre- and postconditions of IR lowering phases. | |
| -Xcollection-literals Enable experimental language support for collection literals. | |
| -Xcommon-sources=<path> Sources of the common module that need to be compiled together with this module in multiplatform mode. | |
| They should be a subset of sources passed as free arguments. | |
| -Xcompanion-blocks Enables companion blocks. | |
| -Xcompanion-blocks-and-extensions | |
| Enables companion blocks and extensions. | |
| -Xcompiler-plugin=<path1>,<path2>[=<optionName>=<value>,<optionName>=<value>] | |
| Register a compiler plugin. | |
| -Xcompiler-plugin-order=<pluginId1>><pluginId2> | |
| Specify an execution order constraint for compiler plugins. | |
| Order constraint can be specified using the 'pluginId' of compiler plugins. | |
| The first specified plugin will be executed before the second plugin. | |
| Multiple constraints can be specified by repeating this option. Cycles in constraints will cause an error. | |
| -Xconsistent-data-class-copy-visibility | |
| The effect of this compiler flag is the same as applying @ConsistentCopyVisibility annotation to all data classes in the module. See https://youtrack.jetbrains.com/issue/KT-11914 | |
| -Xcontext-parameters Enable experimental context parameters. | |
| -Xcontext-sensitive-resolution Enable experimental context-sensitive resolution. | |
| -Xdata-flow-based-exhaustiveness | |
| Enable `when` exhaustiveness improvements that rely on data-flow analysis. | |
| -Xdetailed-perf Enable more detailed performance statistics (Experimental). | |
| For Native, the performance report includes execution time and lines processed per second for every individual lowering. | |
| For WASM and JS, the performance report includes execution time and lines per second for each lowering of the first stage of compilation. | |
| Additionally enables measurements for User and CPU time for all targets. Note that this could cause performance degradation on Linux | |
| machines, so use this mode with caution. | |
| -Xdisable-default-scripting-plugin | |
| Don't enable the scripting plugin by default. | |
| -Xdisable-ir-checkers=<checker1>,<checker2> | |
| A list of IR checkers to disable, specified by a simple name of the checker class. A name of an annotation can also be used to match all tagged checkers. | |
| Only has effect if '-Xverify-ir' is not 'none'. | |
| -Xdisable-phases Disable backend phases. | |
| -Xdo-not-normalize-nan-values-in-const-context | |
| Disables `NormalizeNaNValuesInConstContext` language feature.` | |
| -Xdont-sort-source-files Disable automatic sorting of source files. | |
| -Xdont-warn-on-error-suppression | |
| Don't report warnings when errors are suppressed. This only affects K2. | |
| -Xdump-directory Dump the backend state into this directory. | |
| -Xdump-fqname Dump the declaration with the given FqName. | |
| -Xdump-perf=<path> Dump detailed performance statistics to the specified file in plain text, JSON or markdown format (it's detected by the file's extension). | |
| Also, it supports the placeholder `*` and directory for generating file names based on the module being compiled and the current time stamp. | |
| Example: `path/to/dir/*.log` creates logs like `path/to/dir/my-module_2025-06-20-12-22-32.log` in plain text format, `path/to/dir/` creates logs like `path/to/dir/my-log_2025-06-20-12-22-32.json`. | |
| -Xeager-lambda-analysis Enable eager analysis of lambda bodies to improve overload resolution by the lambda's return type. | |
| -Xenable-additional-ir-checkers=<checker1>,<checker2> | |
| A list of IR checkers to enable, specified by a simple name of the checker class. | |
| It may only be used with specific checkers that are not enabled by default, and which are prepared to be enabled this way. Only has effect if '-Xverify-ir' is not 'none'. | |
| -Xenable-incremental-compilation | |
| Enable incremental compilation. | |
| -Xescaping-functions=<+|-><fq.name> | |
| Add (+) or remove (-) a callable whose functional arguments are analyzed for escaping mutable variables. Callables are specified by their fully qualified name. | |
| -Xexpect-actual-classes 'expect'/'actual' classes (including interfaces, objects, annotations, enums, and 'actual' typealiases) are in Beta. | |
| Kotlin reports a warning every time you use one of them. You can use this flag to mute the warning. | |
| -Xexplicit-api={strict|warning|disable} | |
| Force the compiler to report errors on all public API declarations without an explicit visibility or a return type. | |
| Use the 'warning' level to issue warnings instead of errors. | |
| -Xexplicit-backing-fields Enable experimental language support for explicit backing fields. | |
| -Xexplicit-context-arguments Enable explicit passing of context arguments using named argument syntax. | |
| -Xfir-aggressive-pruning Enable or disable FirAggressivePruningProcessor, which prunes unreachable private members during body resolve. | |
| -Xfragment-dependency=<fragment name>:<path> | |
| Declare common klib dependencies for the specific fragment. | |
| This argument is required for any HMPP module except the platform leaf module: it takes dependencies from -cp/-libraries. | |
| The argument should be used only if the new compilation scheme is enabled with -Xseparate-kmp-compilation | |
| -Xfragment-friend-dependency=<fragment name>:<path> | |
| Declare common klib friend dependencies for the specific fragment. | |
| This argument can be specified for any HMPP module except the platform leaf module: it takes dependencies from the platform specific friend module arguments. | |
| The argument should be used only if the new compilation scheme is enabled with -Xseparate-kmp-compilation | |
| -Xfragment-refines=<fromModuleName>:<onModuleName> | |
| Declare that <fromModuleName> refines <onModuleName> with the dependsOn/refines relation. | |
| -Xfragment-sources=<fragment name>:<path> | |
| Add sources to a specific fragment of a multiplatform compilation. | |
| -Xfragments=<fragment name> Declare all known fragments of a multiplatform compilation. | |
| -Xfull-value-classes Enable experimental language support for full value classes. | |
| -Xheader-mode Enable header compilation mode. | |
| In this mode, the compiler produces class files that only contain the 'skeleton' of the classes to be | |
| compiled but the method bodies of all the implementations are empty. This is used to speed up parallel compilation | |
| build systems where header libraries can be used to replace downstream dependencies for which we only need to | |
| see the type names and method signatures required to compile a given translation unit. Inline functions are still kept | |
| with bodies. | |
| -Xheader-mode-type={any|compilation} | |
| Generates output based on what it is used for: | |
| -Xheader-mode-type=compilation: Skips the IR generation for modules that don't have inline functions. | |
| -Xheader-mode-type=any: Can be used for any downstream dependency which doesn't require linking. | |
| -Xintrinsic-const-evaluation Enables `IntrinsicConstEvaluation` language feature.` | |
| -Xlist-phases List backend phases. | |
| -Xlocal-type-aliases Enable experimental language support for local type aliases. | |
| -Xmetadata-klib Produce a klib that only contains the metadata of declarations. | |
| -Xmetadata-version Change the metadata version of the generated binary files. | |
| -Xmulti-dollar-interpolation Enable experimental multi-dollar interpolation. | |
| The option is deprecated since Kotlin $ABI_VERSION$. It will be removed in one of the future releases. It enables the features that are already on by default in every supported language version. | |
| -Xmulti-platform Enable language support for multiplatform projects. | |
| -Xname-based-destructuring=only-syntax|name-mismatch|complete | |
| Enables the following destructuring features: | |
| -Xname-based-destructuring=only-syntax: Enables syntax for positional destructuring with square brackets and the full form of name-based destructuring with parentheses; | |
| -Xname-based-destructuring=name-mismatch: Reports warnings when short form positional destructuring of data classes uses names that don't match the property names; | |
| -Xname-based-destructuring=complete: Enables short-form name-based destructuring with parentheses; | |
| -Xnested-type-aliases Enable experimental language support for nested type aliases. | |
| -Xno-inline Disable method inlining. | |
| -Xnon-local-break-continue Enable experimental non-local break and continue. | |
| The option is deprecated since Kotlin $ABI_VERSION$. It will be removed in one of the future releases. It enables the features that are already on by default in every supported language version. | |
| -Xphases-to-dump Dump the backend's state both before and after these phases. | |
| -Xphases-to-dump-after Dump the backend's state after these phases. | |
| -Xphases-to-dump-before Dump the backend's state before these phases. | |
| -Xphases-to-validate Validate the backend's state both before and after these phases. | |
| -Xphases-to-validate-after Validate the backend's state after these phases. | |
| -Xphases-to-validate-before Validate the backend's state before these phases. | |
| -Xplugin=<path> Load plugins from the given classpath. | |
| -Xprint-configuration Print compiler configuration. | |
| -Xprofile-phases Profile backend phases. | |
| -Xrender-internal-diagnostic-names | |
| Render the internal names of warnings and errors. | |
| -Xreport-all-warnings Report all warnings even if errors are found. | |
| -Xreport-output-files Report the source-to-output file mapping. | |
| -Xreport-perf Report detailed performance statistics. | |
| -Xreturn-value-checker={check|full|disable|default} | |
| Set improved unused return value checker mode. Use 'check' to run checker only and use 'full' to also enable automatic annotation insertion. 'default' mode is based on the current language version: Since Kotlin 2.5, checker is enabled by default. | |
| -Xrich-errors Enable experimental language support for Rich Errors. | |
| -Xseparate-kmp-compilation Enables the separated compilation scheme, in which common source sets are analyzed against their own dependencies | |
| -Xskip-metadata-version-check Allow loading classes with bad metadata versions and pre-release classes. | |
| -Xskip-prerelease-check Allow loading pre-release classes. | |
| -Xstdlib-compilation Enables special features which are relevant only for stdlib compilation. | |
| -Xstrict-equality-for-structural-classes | |
| Report warnings on inapplicable equalities with data, value, and enum classes. | |
| -Xsuppress-version-warnings Suppress warnings about outdated, inconsistent, or experimental language or API versions. | |
| -Xuse-fir-ic Compile using frontend IR internal incremental compilation. | |
| The option is deprecated since Kotlin $ABI_VERSION$. It will be removed in one of the future releases. | |
| -Xuse-fir-lt Compile using the LightTree parser with the frontend IR. | |
| The option is deprecated since Kotlin 2.4.20. It will be removed in one of the future releases. The light tree mode is enabled by default, and it will become the only available mode in one of the future releases. | |
| -Xverbose-phases Be verbose while performing the given backend phases. | |
| -Xverify-ir={none|warning|error} | |
| IR verification mode (no verification by default). | |
| -Xwarning-level=<WARNING_NAME>:(error|warning|disabled) | |
| Set the severity of the given warning. | |
| - `error` level raises the severity of a warning to error level (similar to -Werror but more granular) | |
| - `disabled` level suppresses reporting of a warning (similar to -nowarn but more granular) | |
| - `warning` level overrides -nowarn and -Werror for this specific warning (the warning will be reported/won't be considered as an error) | |
| -Xwhen-guards Enable experimental language support for when guards. | |
| The option is deprecated since Kotlin $ABI_VERSION$. It will be removed in one of the future releases. It enables the features that are already on by default in every supported language version. | |
| Advanced options are non-standard and may be changed or removed without any notice. | |
| OK |