@uipath/packager-tool-functions

UiPath solution packager plugin for ProjectType.Function. Used by Studio Web to build and pack JS/TS and Python Functions projects.

Architecture

Studio Web publish (JS/TS)
  → FunctionsTool.buildAsync()        ← this package
    → buildJsFunctionsPackage()       ← src/js (thin wrapper)
      → buildFunctionsPackage()       ← @uipath/coded-functions-js-packager

Studio Web publish (Python)
  → FunctionsTool.buildAsync()        ← this package
    → buildPyFunctionsPackage()       ← src/py (local implementation)

CLI: uip functions pack (JS/TS)
  → uipath-functions pack             ← @uipath/uipath-functions CLI
    → buildFunctionsPackage()         ← same shared library

CLI: uip functions pack (Python)
  → uipath pack                       ← Python CLI subprocess

How it works

FunctionsTool implements ProjectTool for ProjectType.Function. On buildAsync:

1. Detects language from uipath.json functions map (.ts/.js/.mjs → javascript, .py → python); fallback: pyproject.toml presence → python.
2. JS/TS: delegates to buildFunctionsPackage(fs, options) from @uipath/coded-functions-js-packager (externally-published library, shared with the uipath-functions CLI).
3. Python: delegates to the local buildPyFunctionsPackage(fs, options) implementation in src/py/.

Language detection

| Signal | Result | |---|---| | uipath.json functions map extension .ts/.js/.mjs | javascript | | uipath.json functions map extension .py | python | | pyproject.toml present | python (fallback) | | Neither | javascript (default) |

Python build pipeline

buildPyFunctionsPackage produces a fully-formed nupkg content folder from the Python project sources. Pipeline:

1. Validate inputs — requires uipath.json and entry-points.json at the project root. Throws a readable error if either is missing.
2. Copy source files to content/, filtered by EXCLUDED_NAMES (agent.json, project.uiproj, bindings.json, entry-points.json, OS metadata) and EXCLUDED_DIRECTORIES (virtualenvs, caches, editor dirs, VCS dirs). bindings.json and entry-points.json are excluded because the packager re-emits canonical versions — see steps 3 and 5.
3. Normalize content/entry-points.json — reads the source file and rewrites it with:
   • Canonical $schema (https://cloud.uipath.com/draft/2024-12/entry-point) and $id (entry-points.json).
   • Per-entry uniqueId — backfilled with crypto.randomUUID() when the source is missing it.
   • Per-entry type — defaults to "function" when missing.
   • All other fields (filePath, input, output, etc.) are passed through.
4. Write content/operate.json — $schema = operate, contentType = "function", targetRuntime = "python", main = first entry-point's filePath, projectId = the platform-assigned storage id.
5. Write content/bindings_v2.json — uses the source bindings.json if present and parseable; otherwise emits the default { $schema, version: "2.0", resources: [] }.
6. Write content/package-descriptor.json — registers operate.json, entry-points.json, and bindings.json (the latter pointing at content/bindings_v2.json).

Expected source-project shape

The upstream tool (uipath init / Function Builder MFE) is responsible for producing a valid source layout before this packager runs. In particular:

• uipath.json.functions — map of entrypoint key → "<file>.py:<python-function>" (the runtime uses this to resolve the function body).
• entry-points.json — each entry's filePath must equal the functions-map key. The packager will fill in uniqueId and type: "function" if they're missing, but nothing can recover the real function-name mapping — that lives in uipath.json.functions.
• The Python function must take exactly one parameter typed as a dataclass, Pydantic model, or annotated class; the UiPath runtime calls func(input) with a single argument and converts the input dict into that type.

Project structure

src/
├── functions-tool.ts         # ProjectTool implementation (language detection, build/pack lifecycle)
├── functions-tool-factory.ts # Factory for the tool loader
├── js/                       # JS/TS build path (delegates to @uipath/coded-functions-js-packager)
├── py/                       # Python build path
│   ├── build-py-functions-package.ts
│   ├── constants.ts          # All Python-packager constants (schemas, file names, exclusions)
│   └── index.ts
├── types.ts                  # BuildPackageOptions, Language enum, labels
└── index.ts

Development

bun install
bun run build        # bun build → dist/ (ESM, browser target)
bun run test         # vitest
bun run lint         # biome check