uipath-coded-apps

# UiPath Coded Apps Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps using the `uip codedapp` CLI and `@uipath/uipath-typescript` SDK. ## When to Use This Skill - User wants to **build, debug, or deploy** a UiPath Coded Web App or Coded Action App - User asks about `uip codedapp` commands, `.uipath/` directory, `app.config.json`, or `action-schema.json` - User wants to **scaffold** a new React/Vue frontend for UiPath Cloud or an Action Center form - User wants to embed the **Document Understanding Validation Station** widget for human review of DU extraction results - User wants to **push/pull source** between local and Studio Web - User wants to use the `@uipath/uipath-typescript` SDK from a coded app - User wants to run the **full pipeline** (build → pack → publish → deploy) - User wants to **generate an agent-monitoring / analytics dashboard** from a natural-language description — e.g. "show agent health, error rates, invocation volume, latency, active agents, KPIs, governance metrics, or consumption trends" - User says "build/create/generate a dashboard", describes metrics to visualize, or asks for an agent observability, operations, or cost view ## App Types | Type | Description | Key Difference | |------|-------------|----------------| | **Coded Web App** | React/Vue/other frontend hosted on UiPath CDN | User-facing app accessed via a URL | | **Coded Action App** | React form wired to UiPath Action Center | Rendered inside human task reviews in Maestro/Agent workflows | > **Two lifecycles, two scaffolding entry points.** > > - **Standalone coded app**: scaffold with `npx create-vite@latest` (see [create-web-app.md](references/create-web-app.md) / [create-action-app.md](references/create-action-app.md)). No `project.uiproj` / `webAppManifest.json` — those are solution-membership artefacts and standalone apps don't need them. Deploy via `uip codedapp pack` → `uip codedapp publish` (`-t Action` for action apps) → `uip codedapp deploy`. This is the classic single-app lifecycle covered by the rest of this skill. > - **In-solution coded app**: run `uip codedapp init` from **inside a `.uipx` solution**. Init writes `project.uiproj` (`ProjectType: "AppV2"`) + `webAppManifest.json`, nests runtime + build artefacts under `source/dist/`, auto-registers the project as `Type: "AppV2"` in the `.uipx`, and emits `resources/solution_folder/app/{Coded,CodedAction}/`. From then on the app is part of the solution — `uip solution pack` bundles its `.nupkg` and `uip solution deploy run` provisions it in the deployment folder. **Do not** run `uip codedapp pack` / `publish` / `deploy` on a coded app that's already registered in `.uipx` — that bypasses the solution's deploy config (external client ID, routing name, action schema) and double-registers the package. `uip solution projects add` / `uip solution projects import` register existing AppV2 folders too, reading `webAppManifest.config.isActionApp` to pick the `Coded` / `CodedAction` subType. For the solution-side lifecycle see [/uipath:uipath-solution](/uipath:uipath-solution). > > **`uip codedapp init` is for solutions only.** It is not the scaffolding entry point for a standalone coded app — use `create-vite` for that. ## Critical Rules 1. **Identify the app type before doing anything else.** Ask as a structured choice (Rule 18): **Coded Web App** — custom frontend deployed to UiPath Cloud · **Coded Action App** — form for Action Center human task reviews. The two paths diverge on scaffolding, redirect URI, and publish flag — do not guess. 2. **Always check login status first.** Run `uip login status --output json` before any cloud command. If not logged in, run `uip login`. 3. **Never skip the build step.** Run `npm run build` after scaffolding (to verify the scaffold compiles) and again before `pack` or `push` (to produce the deployable `dist/`). Verify `dist/` exists each time. 4. **Pack → Publish → Deploy order is required.** Each step depends on the previous one producing its output. 5. **Bump the version for re-publish.** If the same version already exists in Orchestrator, publish will fail. 6. **Action apps require `-t Action` on publish.** Run `uip codedapp publish -t Action` (not the default `Web` type). 7. **Never handle access tokens manually.** Do not pass, print, parse, source, or set cached access tokens. Use `uip login` and supported `uip codedapp` commands; the CLI manages authentication. 8. **Base URL must use the API subdomain.** `https://api.uipath.com` not `https://cloud.uipath.com`. See the table below. 9. **`vite.config.ts` must always set `base: './'`.** The platform handles URL routing — apps must use relative asset paths. Do not use a routing name or a sub-path here. 10. **Use `getAppBase()` from `@uipath/uipath-typescript` for any absolute URL constructed at runtime** — router basename, image `src`, `fetch` paths. Deployed apps mount at a non-root prefix; `/`-rooted paths work locally but 404 after deploy. Vite's `base: './'` only fixes import-time references. 11. **`uip codedapp deploy` must run non-interactively.** Pass the folder key as `--folder-key <GUID>` (or as `UIPATH_FOLDER_KEY=<GUID>` env-var prefix — either works). The interactive folder picker fails in non-TTY contexts (CI, agent shells). If the user provides a folder **name**, resolve it to a key with `uip or folders list --output json` and match on the `Name` field (output rows are `{ Key, Name, Path, Description, Type, ParentKey }`). A **personal workspace** is the row with `Type == "Personal"` — resolve its `Key` the same way. To deploy into a **new** folder, create it first with `uip or folders create "<NAME>" --output json` and read `Data.Key`. The `uip or ...` commands require the Orchestrator tool — install once via `uip tools install @uipath/orchestrator-tool` (check first with `uip tools list`). 12. **Guard against text overflow in every UI.** See [patterns.md](references/patterns.md) "Preventing Text Overflow". 13. **Inspect the DF schema before writing analytics, filters, or seeds.** Run `uip df entities get <ENTITY_ID> --output json` to inspect fields and types. At runtime, use `entities.getById(<id>)` from the app's authenticated session. DF doesn't behave like a typical RDBMS; see [sdk/data-fabric.md](references/sdk/data-fabric.md) "Anti-shapes & gotchas". 14. **Every list call returns ONE page — even with no options. There is no "give me everything" path.** Applies to `getAll`, `getAllRecords`, `queryRecordsById`, `getFileMetaData`, etc. `getAll()` with no options does NOT return all rows; the SDK sends no `pageSize` and the **server** applies its own cap, wrapped in a misleadingly-named `NonPaginatedResponse`. To list every row from a source that may exceed the cap, you MUST loop the cursor: `while (page.hasNextPage) { page = await getAll({ cursor: page.nextCursor }) }` and accumulate `items`. Reading `result.items.length` after a single call is almost always a bug. See [sdk/pagination.md](references/sdk/pagination.md). 15. **Tables of dynamic data must paginate, not dump all rows in one scroll.** Page size 25–50 with next/prev/page-number controls and a "Showing X–Y of Z" summary. Top-N + "see all" is acceptable for explicitly summary panels (e.g., "Top 10 oldest"). Infinite-scroll-of-N-rows is unusable for operational dashboards. Applies to any table backed by any service (DF entities, Tasks, Jobs, Conversations, Process Instances, etc.). See [patterns.md](references/patterns.md) "Tabular Data". 16. **When adding any new SDK method call, verify the configured OAuth scope already includes the required scope** — both dashboards and web apps read the `scope` key from `uipath.json`. Write operations, action methods (`Jobs.stop`, `Tasks.complete`, `ProcessInstances.cancel`, etc.), or first use of a new service typically need broader scopes than read-only flows. Mismatched scopes fail silently with `401` / `403` on the first call. See [oauth-scopes.md](references/oauth-scopes.md) for scope bundles and the per-method lookup protocol (the per-method table ships inside the SDK package at `node_modules/@uipath/uipath-typescript/docs/oauth-scopes.md`). 17. **Never call `sdk.initialize()` in an action app.** That is web-app-only — it starts a PKCE OAuth redirect. Action apps run in Action Center's iframe with a host-injected session: construct `new UiPath()` (no args) and use it directly. See [create-action-app.md](references/create-action-app.md) `src/uipath.ts`. 18. **Never make the user type magic phrases.** Whenever you ask the user to pick between known options (app type, build/edit/deploy intent, OAuth setup, deploy pinning), present a **structured choice** via the host coding agent's native question tool (selectable options) when one exists. Mechanics: one option per choice with a short bold label + one-line description of what picking it does; put the recommended option **first** and suffix its label "(Recommended)"; keep to **at most 4 options** (reserve one slot for an escape option like *Make changes* / *Cancel* when applicable). If there are 5+ candidates, or the host agent has no question tool, render a plain numbered list instead and accept the number or the option label as the answer. A free-text reply must always remain valid (e.g. a plan-change request) and takes precedence over the options. **Exception — never put a question in the same response as a long output:** plan-approval gates are free-text by design (the plan ends with "confirm or tell me what to change"); structured questions fire only on later, short turns. See `references/dashboards/plugins/build/impl.md`. 19. **Never guess SDK method signatures — read the installed types.** The authoritative reference for method names, parameters, return types, and usage examples is `node_modules/@uipath/uipath-typescript/dist/<subpath>/index.d.ts` (full JSDoc; matches the installed SDK version exactly). Before calling a service you have not used in this session, Read its `.d.ts`. If `node_modules` is absent, run the install step first — the app cannot build without it. The `references/sdk/*.md` files deliberately do NOT list signatures; they cover only scopes, calling conventions, and traps the types cannot express. See [references/sdk/imports.md](references/sdk/imports.md) for the missing-capability protocol. **Boundary: read the `.d.ts`, never the compiled bundle.** `dist/*.mjs` / `*.js` is minified implementation, not API — reading it dead-ends. A grep with no output **confirms absence**; treat a genuine gap as unsupported (use the documented alternative) rather than escalating the search into the bundle. ## Disambiguation — Apps vs Dashboards **Route directly to Apps workflow** (sections below) when you see: `web app`, `action app`, `codedapp`, `app.config.json`, `action-schema.json`, `scaffold app`, `deploy app`, `pack`, `publish`, `push`, `pull`, `debug app` **Route directly to [references/dashboards/CAPABILITY.md](references/dashboards/CAPABILITY.md) when you see:** `dashboard`, `analytics`, `KPI`, `metrics`, `Insights`, `observability`, `admin console`, `report`, `chart`, `trend`, `governance report`, `agent metrics` **When intent is ambiguous** — ask "Which fits your goal?" as a structured choice (Rule 18): | Option | Description | |--------|-------------| | **Build or modify a Web App / Action App** | Scaffold a UI, form, or app that deploys to Automation Cloud | | **Generate a dashboard** | Analytics or admin view from a natural-language description | ## Task Navigation | I want to... | Read this | |---|---| | **Create a new Coded Web App** | [references/create-web-app.md](references/create-web-app.md) | | **Create a new Coded Action App** | [references/create-action-app.md](references/create-action-app.md) | | **Debug auth or config issues** | [references/debug.md](references/debug.md) | | **Push/pull code to Studio Web** | [references/file-sync.md](references/file-sync.md) | | **Package and deploy** | [references/pack-publish-deploy.md](references/pack-publish-deploy.md) | | **Full CLI command reference** | [references/commands-reference.md](references/commands-reference.md) | | **Embed the DU Validation Station widget** | [references/widgets/validation-station.md](references/widgets/validation-station.md) | | **OAuth scopes for SDK services** | [references/oauth-scopes.md](references/oauth-scopes.md) | | **SDK: Import paths & subpath exports** | [references/sdk/imports.md](references/sdk/imports.md) | | **SDK: Assets, Queues, Buckets, Processes, Jobs, Attachments** | [references/sdk/orchestrator.md](references/sdk/orchestrator.md) | | **SDK: Data Fabric (Entities, ChoiceSets)** | [references/sdk/data-fabric.md](references/sdk/data-fabric.md) | | **SDK: Maestro (Processes, Cases)** | [references/sdk/maestro.md](references/sdk/maestro.md) | | **SDK: Action Center (Tasks)** | [references/sdk/action-center.md](references/sdk/action-center.md) | | **SDK: Conversational Agent** | [references/sdk/conversational-agent.md](references/sdk/conversational-agent.md) | | **SDK: Agent Feedback** | [references/sdk/feedback.md](references/sdk/feedback.md) | | **SDK: Pagination** | [references/sdk/pagination.md](references/sdk/pagination.md) | | **SDK: Agents & Agent Memory (Insights RTM)** | [references/sdk/agents.md](references/sdk/agents.md) | | **SDK: Agent Traces (Insights RTM)** | [references/sdk/traces.md](references/sdk/traces.md) | | **SDK: Governance — policy evaluations (Insights API)** | [references/sdk/governance.md](references/sdk/governance.md) | | **SDK: Agent Governance Decisions — runtime compliance (Insights RTM)** | [references/sdk/governance-traces.md](references/sdk/governance-traces.md) | | **UI Patterns (polling, BPMN, HITL, text overflow, table pagination)** | [references/patterns.md](references/patterns.md) | | **Generate an admin dashboard from NLP** | [references/dashboards/CAPABILITY.md](references/dashboards/CAPABILITY.md) | ## CLI Setup ```bash # Install the UiPath CLI (run once) npm install -g @uipath/cli # Install the coded apps tool uip tools install @uipath/codedapp-tool # Install the Orchestrator tool (needed to resolve folder name → key for deploy) uip tools install @uipath/orchestrator-tool # Verify both are installed uip tools list # Resolve uip if not on PATH UIP=$(command -v uip 2>/dev/null || npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip $UIP --version ``` Authenticate before any cloud command: ```bash uip login status --output json # check if logged in uip login # interactive OAuth (opens browser) uip login --authority https://alpha.uipath.com # non-production environments # Client-credentials (headless/CI) — MUST include Apps.Read Apps.Write or publish's # "Registering coded app" step fails with 401 even though package upload succeeds. # OR.Default alone is NOT sufficient — it covers Orchestrator but not the Apps service. uip login \ --client-id <id> \ --client-secret <secret> \ --organization <org> \ --tenant <tenant> \ --scope "OR.Folders OR.Execution OR.Administration Apps.Read Apps.Write" \ --authority https://alpha.uipath.com # omit --authority for production ```