# uip codedapp convert

> Syntax and options for `uip codedapp convert`, which converts an exported VB low-code app (`.uiapp`) into a React and TypeScript coded app on your machine.

`uip codedapp convert` converts an exported Visual Basic (VB) low-code app into a React and TypeScript coded app that you own. The input is the `.uiapp` file that Apps Studio exports for a VB app — a standalone low-code app whose expressions are written in VB, the Apps Studio default. The command accepts `.uiapp` files only.

The result is a Vite, React, and TypeScript project with:

- One component per page
- Typed data access through `@uipath/uipath-typescript`
- A `conversion-report.json` that lists what converted, what did not, and the cause of each gap (`converter`, `source-app`, or `by-design`)

The conversion runs on your machine. It makes no tenant call and needs no [`uip login`](./uip-login.md).

## Prerequisites

The converter binds the app's VB expressions with the Roslyn compiler, which runs on .NET, so the .NET 10 Runtime must be installed on the machine that runs `convert`. The .NET SDK is not needed.

The runtime for each operating system is available from [dotnet.microsoft.com](https://dotnet.microsoft.com/download/dotnet/10.0). Once it is installed, `dotnet --list-runtimes` in a new terminal prints a line that starts with `Microsoft.NETCore.App 10.`. Other .NET versions can stay installed.

Without the runtime, `convert` stops before it reads the file and reports `CONVERT_PREREQUISITE_MISSING`.

### Converter SDK

The converter, `@uipath/codedapp-convert-sdk`, ships with the tool. If the command reports that the converter SDK could not be loaded, for example after an install with `--omit=optional`, `uip tools install codedapp` reinstalls the tool together with the SDK. `uip tools update` does not help here, because the installed tool version is already current.

You can also install the SDK beside the tool with `npm install -g @uipath/codedapp-convert-sdk@beta`, without `-g` for a project-local CLI.

## Synopsis

```
uip codedapp convert <file> [options]
```

## Arguments

| Argument | Description |
|---|---|
| `<file>` | Required. The exported VB low-code app: a `.uiapp` file. |

## Options

| Flag | Description |
|---|---|
| `--out <dir>` | Output directory for the coded app, by default `./<file name>` in the current directory. An empty value is refused instead of treated as omitted. |
| `--force` | Convert into a non-empty directory, for a re-conversion. `uipath.json` and `node_modules` are kept. |
| `--refresh` | Bind every expression again instead of reusing the output directory's bind cache. |

## Output

The coded app goes to `--out`, or to a directory named after the file in your current directory. The output includes:

- `README.md`
- `conversion-report.json`
- `conversion-log.ndjson`
- The `fix-converted-app` skill

## The fix-converted-app skill

The output holds the `fix-converted-app` skill as a skill source, in the same layout as [UiPath/skills](https://github.com/UiPath/skills): `.uipath/agent-skills/skills/fix-converted-app/SKILL.md`. `convert` runs no agent itself. It prints the command that installs the skill under `NextSteps`:

```bash
uip skills install --repo ./.uipath/agent-skills --path .
```

When run from the output directory, the command installs the skill for every coding agent detected on the machine, or for one agent only with `--agent <name>`. Refer to [`uip skills`](./uip-skills.md). The skill then starts from the coding agent, by its name.

The skill reads `conversion-report.json`, works through the issues the report blames on the `converter` by editing the generated code, builds the project to check its work, and writes what it did to `conversion-fixes.md`. It never changes the report or the log. The skill reads the generated code against the export as well as the report, so it can take minutes and can change things the report did not list.

## Examples

```bash
# Convert an export; the coded app lands in ./expense-app
uip codedapp convert ./expense-app.uiapp

# Choose the directory
uip codedapp convert ./expense-app.uiapp --out ./apps/expense

# Re-convert into the same project after a converter update (uipath.json is kept)
uip codedapp convert ./expense-app.uiapp --force --refresh
```

## Data shape (--output json)

A conversion with no gaps:

```json
{
  "Code": "ConvertCompleted",
  "Data": {
    "Path": "./expense-app",
    "Kind": "uiapp",
    "Pages": 3,
    "Files": 58,
    "Report": {
      "Issues": 0,
      "Converter": 0,
      "SourceApp": 0,
      "ByDesign": 0
    }
  }
}
```

A conversion with gaps also carries the skill install command:

```json
{
  "Code": "ConvertCompletedWithGaps",
  "Data": {
    "Path": "./apps/expense",
    "Report": {
      "Issues": 2,
      "Converter": 2,
      "SourceApp": 0,
      "ByDesign": 0
    },
    "Skill": {
      "Install": "uip skills install --repo ./.uipath/agent-skills --path ."
    }
  }
}
```

The examples are trimmed. The full `Data` carries these fields:

| Field | Description |
|---|---|
| `Path` | The directory the coded app was written to. |
| `Kind` | The input type: `uiapp` or `uis`. |
| `Outcome` | `converted`, `converted-with-gaps`, or `cannot-run`. |
| `Pages` | The number of pages converted. |
| `Files` | The number of files written. |
| `Kept` | The existing files the run left in place, such as `uipath.json`. |
| `Expressions` | Counts of expressions: referenced, emitted, exact, and lenient. |
| `Unconverted` | Counts of expressions and event handlers that did not convert. |
| `Blocking` | The number of diagnostics that stopped behavior from converting. |
| `Report` | The path of `conversion-report.json` and its issue counts. |
| `Skill` | The `fix-converted-app` skill: `Path`, `Source`, and `Install`. |
| `NextSteps` | The commands to run next. |

## Results and exit codes

`Result` and `Code` say what the numbers mean, so they, not the counts, are the values to branch on:

| `Result` | `Code` | Exit | Meaning |
|---|---|---|---|
| `Success` | `ConvertCompleted` | `0` | Everything converted. Nothing in the report is blamed on the converter. |
| `Success` | `ConvertCompletedWithGaps` | `0` | The project builds and runs, with gaps: `Report.Converter` is 1 or more, or expressions or event handlers are unconverted. Refer to [The fix-converted-app skill](#the-fix-converted-app-skill). |
| `Failure` | `ConvertOutputCannotRun` | `1` | The project is written but cannot run as it is: a blocking diagnostic stopped behavior from converting, or generated TypeScript does not parse. `Data` still carries the result. |
| `Failure` | `CONVERT_*` | `1` | Nothing was converted. Refer to [Conversion failures](#conversion-failures). |

### Conversion failures

| `Code` | `ErrorCode` | Cause |
|---|---|---|
| `CONVERT_FILE_REQUIRED` | `invalid_argument` | No file was passed. |
| `CONVERT_FILE_NOT_FOUND` | `not_found` | The file does not exist. Apps Studio exports the file. |
| `CONVERT_UNSUPPORTED_TYPE` | `invalid_argument` | The file is not a `.uiapp` export. |
| `CONVERT_NOT_A_DIRECTORY` | `invalid_argument` | The output path exists and is not a directory. |
| `CONVERT_DIR_NOT_EMPTY` | `invalid_argument` | The output directory is not empty, and `--force` was not passed. |
| `CONVERT_OUT_EMPTY` | `invalid_argument` | `--out` was passed an empty value. |
| `CONVERT_SDK_UNAVAILABLE` | `configuration_error` | The converter SDK could not be loaded. Refer to [Prerequisites](#prerequisites). |
| `CONVERT_PREREQUISITE_MISSING` | `configuration_error` | The .NET 10 Runtime is missing. Refer to [Prerequisites](#prerequisites). |
| `CONVERT_INPUT_REJECTED` | `invalid_argument` | The converter could not read the export. |

## Related

- [uip codedapp push](./uip-codedapp-push.md) — upload the converted app to Studio Web.
- [uip codedapp pack](./uip-codedapp-pack.md) — package a built coded app into a `.nupkg`.
- [uip codedapp init](./uip-codedapp-init.md) — start a coded app from a template instead.

## See also

- [Coded Apps tool overview](./uip-codedapp.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)
