---
name: kmp-wizard
description: Generate a new Kotlin Multiplatform (KMP) project for Android, iOS, desktop, web and/or server with one HTTP request to the official JetBrains KMP wizard (kmp.jetbrains.com, kmp.new). Use when asked to create, scaffold or start a new KMP or Compose Multiplatform project.
---

# Kotlin Multiplatform Wizard

The wizard at https://kmp.jetbrains.com (https://kmp.jetbrains.com.cn in Mainland China) generates projects with a single GET request that returns a ZIP archive. Call it with `curl`; no browser, JavaScript, cookies or API key needed.

## Steps

1. **Choose the targets and build system** from the user's request, using the [targets table](#targets). When the user names only "KMP" or "Compose Multiplatform", use what the web wizard defaults to: Android + iOS with shared Compose UI, Gradle, tests included.
2. **Choose a project name and ID** that pass the [validation rules](#parameters), e.g. `GroceryList` and `com.example.grocerylist`.
3. **Download the project**:

   ```sh
   curl -fsSL -G https://kmp.jetbrains.com/generateKmtProject \
     --data-urlencode 'name=GroceryList' \
     --data-urlencode 'id=com.example.grocerylist' \
     --data-urlencode 'spec={"template_id":"kmt","targets":{"android":{"ui":["compose"]},"ios":{"ui":["compose"]}},"include_tests":true}' \
     -o GroceryList.zip
   unzip GroceryList.zip    # creates ./GroceryList/
   ```

   `-G` with `--data-urlencode` sends a GET with URL-encoded parameters. On a non-200 response, drop `-f` to read the error message in the body and fix the request.
4. **Verify the modules.** Every requested target has its module directory, at the project root or under `app/`:

   ```sh
   find GroceryList -maxdepth 2 -type d \( -name androidApp -o -name iosApp -o -name desktopApp -o -name webApp -o -name server \)
   ```

   This step is done when each requested target appears in the output. A missing one means its `spec` entry was wrong (see [Pitfalls](#pitfalls)).
5. **Build and run** with the commands in the generated `README.md`.

## Parameters

`GET /generateKmtProject` (no trailing slash):

| Parameter | Required | Value |
|---|---|---|
| `name` | yes | Project name; also names the ZIP and its top-level directory. Starts with a Latin letter; only Latin letters, digits, spaces, `_` and `-`. Must not be (case-insensitive, spaces ignored) `project`, `iosApp`, `androidApp`, `composeApp`, `desktopApp`, `server`, `shared`, `webApp`, `sharedUI` or `sharedLogic`. |
| `id` | yes | Kotlin package and Android application ID, e.g. `com.example.myapp`. Two or more `.`-separated segments, each starting with a lowercase Latin letter and containing only lowercase Latin letters, digits and `_`. Does not start with `kotlin`; no segment is a Java keyword (`new`, `class`, `int`, `package`, …). |
| `spec` | yes | JSON project description (below), URL-encoded. |
| `locale` | no | Language of the sample UI strings: `en-us` (default), `de-de`, `es-es`, `fr-fr`, `ja-jp`, `ko-kr`, `pt-br`, `ru-ru`, `zh-cn`. |

## spec

```json
{
  "template_id": "kmt",
  "build_system": "gradle",
  "include_tests": true,
  "targets": {
    "android": { "ui":     ["compose"] },
    "ios":     { "ui":     ["compose"] },
    "desktop": { "ui":     ["compose"] },
    "web":     { "ui":     ["compose"] },
    "server":  { "engine": ["ktor"] }
  },
  "android_project_spec": { "min_android_sdk": 24 }
}
```

| Field | Required | Value |
|---|---|---|
| `template_id` | yes | Always `"kmt"`. |
| `targets` | yes | Only the targets you want, at least one. Each target takes its option from the table below with an array of exactly one variant. |
| `build_system` | no | `"gradle"` (default) or `"kotlin"` (Kotlin Toolchain, early access). |
| `include_tests` | no | Adds sample tests. Default `false`. |
| `android_project_spec` | no | Only with the `android` target. `min_android_sdk`: integer from 24 to 37. |

### Targets

| Target | Option | Variant | Result | Module |
|---|---|---|---|---|
| `android` | `ui` | `compose` | Compose Multiplatform UI | `androidApp` |
| `ios` | `ui` | `compose` | UI shared via Compose Multiplatform | `iosApp` |
| `ios` | `ui` | `swiftui` | Native SwiftUI, shares only logic (Gradle only) | `iosApp` |
| `desktop` | `ui` | `compose` | Compose Multiplatform UI (JVM) | `desktopApp` |
| `web` | `ui` | `compose` | UI shared via Compose Multiplatform (Wasm) | `webApp` |
| `web` | `ui` | `react` | Native React UI, shares only logic (Gradle only) | `webApp` |
| `server` | `engine` | `ktor` | Ktor server | `server` |

With `"build_system": "kotlin"` the project builds with the bundled `./kotlin` wrapper instead of `./gradlew`.

## Pitfalls

The server answers `400` with a readable `text/plain` message for invalid names and IDs, malformed or unknown JSON keys, target and variant names, no targets, out-of-range `min_android_sdk`, and variants the build system does not support. A missing `name`, `id` or `spec` gives `404`, and so does a trailing slash on the path. An unknown `locale` gives a generic `400 … Can't transform call to resource`.

Two mistakes still return `200`, which step 4 catches:

- A target with another target's option, e.g. `"android": {"engine": ["ktor"]}`, is left out of the project.
- An option with several variants uses only one of them.

The web form also sends a `buildSystem` query parameter; the server takes the build system from `spec.build_system` only.

## Other endpoints

- `GET /config`: JSON with the default project name and ID, the available targets and variants, and the ready-made templates.
- `GET /template/download/{id}`: redirects to the ZIP of a ready-made template listed in `/config`, e.g. `curl -fsSL -o template.zip https://kmp.jetbrains.com/template/download/KMP-App-Template`.