ご参考になれば、ぜひ X（@utanesuke_papa）をフォローしてください。UiPath の技術情報や AI 実装に関する話題を、できるだけ早くお届けしています。

近年、UiPathはRPAにとどまらず、API連携(特にAI関連)や外部システムとの統合など、より柔軟な活用が広がっています。そうした中で注目されているのが UiPath TypeScript SDK（UiPath TS SDK） です。

UiPath TS SDKは、Node.jsフレームワークを用いたモダンなWebアプリケーション開発を可能にする軽量なツールキットです。
プロセスポータルや監視ダッシュボードなどのアプリケーションを構築し、UiPathの各種サービスとシームレスに接続できます。Node.jsおよびブラウザ環境の両方に対応しており、LLM支援開発（vibe coding）との親和性が高い点も特長です。

公式ドキュメントは公開されていますが、全体像や構成イメージを把握するにはやや分かりづらい部分もあります。

本シリーズでは、図解を交えながら導入から実装までを段階的に解説します。また、手順どおりに進める中で発生したエラーとその回避方法についても紹介します。

第1回となる今回は「環境構築とセットアップ手順」 として、UiPath TypeScript SDKを利用するための前提環境と初期設定を整理します。これから導入を検討している方の最初の一歩となる内容です。

1. 前提条件

インストールを始める前に、現在の環境が以下の条件を満たしているか確認してください。

Node.js: 20.x 以上
npm: 8.x 以上
TypeScript: 4.5 以上
作業場所の推奨: OneDrive 同期によるファイルロックを避けるため、デスクトップや C ドライブ直下のローカルフォルダ（例: C:\uipath-dev）で行うことを強く推奨します。

Node.js と npm のインストール

npmはNode.jsに同梱されているため、Node.jsをインストールすればnpmも同時に利用可能になります。

LTS（推奨版） をダウンロード(※ 本記事では 20.x 以上を推奨します。)

インストーラー(例：node-v24.13.1-x64.msi)を実行し、基本的には「Next」を連打でOKですが、以下の点だけ確認してください：

Destination Folder: デフォルト（C:\Program Files\nodejs\）のままで問題ありません。
Custom Setup: 全てにチェックが入っている（特に Add to PATH）ことを確認してください。
Tools for Native Modules: 「Automatically install the necessary tools...」というチェックボックスが表示されたら、チェックを入れずに進めても大丈夫です（後で必要になったら入れられますし、これを入れると完了まで時間がかかります）。

インストール確認

PowerShell（またはコマンドプロンプト）を開き、以下を実行します。

node -v
npm -v

それぞれバージョンが表示されれば成功です。

PS C:\Users\admin_1> node -v
v24.13.1
PS C:\Users\admin_1> npm -v
11.8.0

TypeScript のインストール

そのままPowerShellで、npm install -g typescriptを実行します。次に、tsc -vコマンドでインストール確認します。
以下のように、バージョンが表示されれば問題ありません。

PS C:\Users\admin_1> tsc -v
Version 5.9.3

2. UiPath TypeScript SDK インストール手順

以下は、UiPath TypeScript SDK を新規プロジェクトに導入するための最小手順です。前述の通りに、C:\uipath-devで作業します。

① 作業用フォルダを作成

順番に以下のコマンドを実行：

mkdir my-uipath-project
cd my-uipath-project

実行結果：

PS C:\UiPath-Dev> mkdir my-uipath-project

    ディレクトリ: C:\UiPath-Dev

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2026/02/22     11:37                my-uipath-project


PS C:\UiPath-Dev> cd my-uipath-project

② Node.js プロジェクトを初期化

以下のコマンドを実行：

npm init -y

実行結果：

PS C:\UiPath-Dev\my-uipath-project> npm init -y
Wrote to C:\UiPath-Dev\my-uipath-project\package.json:

{
  "name": "my-uipath-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs"
}

③ TypeScript 関連パッケージをインストール（開発用）

以下のコマンドを実行：

npm install typescript ts-node @types/node --save-dev

実行結果：

PS C:\UiPath-Dev\my-uipath-project> npm install typescript ts-node @types/node --save-dev

added 20 packages, and audited 21 packages in 6s
found 0 vulnerabilities

④ UiPath TypeScript SDK をインストール

以下のコマンドを実行：

npm install @uipath/uipath-typescript

実行結果：

PS C:\UiPath-Dev\my-uipath-project> npm install @uipath/uipath-typescript

added 17 packages, and audited 38 packages in 15s
1 package is looking for funding
  run `npm fund` for details

found 0 vulnerabilities

※ これが公式ページで2回書かれているコマンドですが、実際にはここで1回だけ実行すれば十分です。

⑤ TypeScript 設定ファイルを作成

以下のコマンドを実行：

npx tsc --init

実行結果：

PS C:\UiPath-Dev\my-uipath-project> npx tsc --init

Created a new tsconfig.json
                                                                                                                     TS
You can learn more at https://aka.ms/tsconfig
PS C:\UiPath-Dev\my-uipath-project>

3. 設定ファイルの修正 (JSON)

補足
以下の設定は公式ドキュメントには記載されていません。
実際にNode.js 24系環境でセットアップを行った際に発生したエラーを回避するために、筆者が検証のうえ整理した内容です。

インストール直後の状態では、Node.js 24系環境でモジュール関連のエラーが発生する場合があります。
そのため、エラーになる場合は以下の 2つのファイルを修正してください。

① package.json の修正
"type": "module" を追加します。

{
  "name": "my-uipath-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "type": "module",// ← これを追加
  "scripts": {
  ...},
  ...
}

② tsconfig.json の修正
"types": ["node"] を指定し、環境設定を最適化します。

...
    "module": "nodenext",
    "target": "esnext",
    "types": ["node"],// ← [] から変更
...

インストール後の確認 (Verification)

正しくインストールと設定が完了したか、以下の２つステップで確認します。

① コマンドで確認

ターミナルで以下のコマンドを打ち、バージョン番号が表示されるか確認してください。

npm list @uipath/uipath-typescript

実行結果：

PS C:\UiPath-Dev\my-uipath-project> npm list @uipath/uipath-typescript
my-uipath-project@1.0.0 C:\UiPath-Dev\my-uipath-project
`-- @uipath/uipath-typescript@1.1.0

② 最小限のコードで疎通確認

フォルダ内に check.ts を作成し、中身を以下にして実行します。

import { UiPath } from '@uipath/uipath-typescript/core';
console.log("✅ SDK の読み込みに成功しました。");

実行コマンド:

npx ts-node --esm check.ts

実行結果：

PS C:\UiPath-Dev\my-uipath-project> npx ts-node --esm check.ts
✅ SDK の読み込みに成功しました。
(node:692) [DEP0180] DeprecationWarning: fs.Stats constructor is deprecated.
(Use `node --trace-deprecation ...` to show where the warning was created)
PS C:\UiPath-Dev\my-uipath-project>

結果: 「✅ SDK の読み込みに成功しました。」と表示されれば、環境構築は完璧です！

4.認証情報の準備

UiPath TypeScript SDK を利用して Orchestrator や Automation Cloud 上の API を呼び出すには、適切な認証情報の設定が必要です。公式ドキュメントでは、主に OAuth 認証 と Secret（トークン）ベースの認証 がサポートされています。

1. OAuth 2.0 認証の場合(推奨)

外部アプリケーションを UiPath Cloud に登録し、Client ID / Redirect URI / Scope を指定して認証フローを実行します。
この方式では sdk.initialize() の呼び出しが必須で、OAuth の初期化プロセスが完了するまで待つ必要があります。

UiPath Cloud Portal にログインし、「管理」 → 「外部アプリケーション」メニューを開く
「アプリケーションを追加」をクリック

以下のように以下の情報を設定：
- Name：任意のアプリ名
- Redirect URI：開発用のコールバック URL（例: http://localhost:5173/callback）
- Scopes：必要なアクセス権限

保存後、発行されるClient IDがSDK に渡すので、メモに控えてください。

2.Secret（シークレット）ベース認証の場合

Orchestrator の個人用アクセストークン（PAT）などの トークンを直接指定して認証します。
SDK インスタンス生成時にトークンを渡せば、自動で初期化され使用できます（initialize() 呼び出し不要）。

UiPath Cloud Portal にログインし、「プロファイル」 → 「個人用アクセストークン」メニューを開く
「トークンを作成」をクリックし、トークン名と有効期限、必要なスコープを設定して作成

生成された PAT はトークンとして SDK に渡すので、メモに控えてください。

3. 補足：認証方式選びの目安

認証方式	利点	適用例
Secret（PAT）	実装が簡単・トークン管理のみ	バックエンド定期処理
OAuth	安全性が高くユーザインタラクション対応	Web アプリケーション

また、動作確認のポイント：

認証方式	initialize()	ブラウザ起動	用途
Secret（PAT）	不要	なし	バックエンド処理向け
OAuth	必須	あり	Webアプリ向け

5. SDK への設定と認証実行サンプル(Secret（PAT）認証の場合)

プロジェクトフォルダ内に、次のファイルを作成します。

test-auth-SecretAuth.ts

test-auth-SecretAuth.ts

import { UiPath } from '@uipath/uipath-typescript';
import { Assets } from '@uipath/uipath-typescript/assets';

async function start() {
    // Client IDを省き、シークレットのみで構成
    const sdk = new UiPath({
		baseUrl: 'https://cloud.uipath.com/',
		orgName: 'uta_test',
		tenantName: 'DefaultTenant',
        secret: 'rt_******YOUR_PAT******'
    });

    try {
        // Assetsサービスを呼び出し（内部で自動初期化を試みます）
        const assets = new Assets(sdk);
        const allAssets = await assets.getAll();
        
        console.log('✅ Authentication successful!');
        console.log(`Found ${allAssets.items?.length ?? 0} assets`);

    } catch (error: any) {
        console.error('❌ Authentication failed:');
        console.error(error.message);
    }
}

start();

※ Secret認証では initialize() の呼び出しは不要です。

Secret認証の確認

npx ts-node --esm .\test-auth-SecretAuth.ts

実行結果が以下の通りに、成功にOrchestrator側のアセットを取得できました。

PS C:\UiPath-Dev\my-uipath-project> npx ts-node --esm .\test-auth-SecretAuth.ts
(node:5740) [DEP0180] DeprecationWarning: fs.Stats constructor is deprecated.
(Use `node --trace-deprecation ...` to show where the warning was created)
✅ Authentication successful!
Found 34 assets
PS C:\UiPath-Dev\my-uipath-project>

6. SDK への設定と認証実行サンプル(OAuth認証の場合)

フォルダ作成 → Viteプロジェクト作成

以下のコマンドを実行：

mkdir uipath-oauth-sample
cd uipath-oauth-sample

npm create vite@latest . -- --template vanilla-ts

実行結果が以下の通り(そのままデフォルト設定でOK)

PS C:\my-uipath-project\uipath-oauth-sample> npm create vite@latest . -- --template vanilla-ts
Need to install the following packages:
create-vite@8.3.0
Ok to proceed? (y)

> my-uipath-project@1.0.0 npx
> create-vite . --template vanilla-ts

│
◇  Use Vite 8 beta (Experimental)?:
│  No
│
◇  Install with npm and start now?
│  Yes
│
◇  Scaffolding project in C:\Users\jun.li\OneDrive-UiPath\00.Study\01.Codex\Typescript\my-uipath-project\uipath-oauth-sample...       
│
◇  Installing dependencies with npm...

added 15 packages, and audited 16 packages in 15s

5 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
│
◇  Starting dev server...

> uipath-oauth-sample@0.0.0 dev
> vite


  VITE v7.3.1  ready in 1376 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

http://localhost:5173/をクリックして、以下の画面が表示されます。

以下のコマンドを継続実行：

npm install

UiPath TypeScript SDK をインストール

npm install @uipath/uipath-typescript

CORS回避のため proxy を追加（重要）

CORS Issues:

プロジェクト直下（package.json と同じ階層）に vite.config.ts を作成して、以下を貼り付け：

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    proxy: {
      // orgName と同じパスを proxy（私の場合 uta_test）
      '/uta_test': {
        target: 'https://cloud.uipath.com',
        changeOrigin: true,
        secure: true,
      },
    },
  },
});

なぜこの設定が必要か？

ローカル開発環境では、ブラウザのCORS制限によりAPIリクエストがブロックされる場合があります。

この設定では、Viteの開発サーバーにローカルプロキシを作成し、UiPath CloudへのAPIリクエストを中継することで、CORS問題を回避しています。

OAuthサンプルコードを作成

src/main.ts を以下に丸ごと置き換えます：

main.ts

import { UiPath } from '@uipath/uipath-typescript/core';
import { Assets } from '@uipath/uipath-typescript/assets';

const oauthConfig = {
  // ★ proxy を使うので localhost を baseUrl にする
  baseUrl: window.location.origin,
  orgName: 'uta_test',
  tenantName: 'DefaultTenant',
  clientId: 'fa6850e3-be12-****************',
  redirectUri: 'http://localhost:5173/callback',
  scope: 'OR.Assets',
};

const sdk = new UiPath(oauthConfig);

async function run() {
  const path = window.location.pathname;

  // callbackに戻ってきたとき：OAuthを完了→Assets取得
  if (path === '/callback') {
    document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
      <h2>OAuth callback processing...</h2>
      <p>認証完了後、ここでトークンを確定します。</p>
    `;

    try {
      if (sdk.isInOAuthCallback()) {
        sdk.completeOAuth();
      }

      const assets = new Assets(sdk);
      const allAssets = await assets.getAll();

      document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
        <h2>✅ OAuth Authentication successful!</h2>
        <p>Found ${allAssets.items?.length ?? 0} assets</p>
        <p><a href="/">トップに戻る</a></p>
      `;
    } catch (e: any) {
      document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
        <h2>❌ API call failed</h2>
        <pre>${(e?.message ?? e).toString()}</pre>
        <p><a href="/">トップに戻る</a></p>
      `;
    }
    return;
  }

  // 通常画面：ログイン開始
  document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
    <h2>UiPath TypeScript SDK OAuth Demo</h2>
    <button id="login">Login with UiPath (OAuth)</button>
    <pre id="log"></pre>
  `;

  const log = (msg: string) => {
    const el = document.getElementById('log')!;
    el.textContent += msg + '\n';
  };

  document.getElementById('login')!.addEventListener('click', async () => {
    try {
      log('▶ initialize() start');
      await sdk.initialize();
      log('✅ initialize() done (browser will redirect to callback)');
    } catch (e: any) {
      log('❌ initialize() failed');
      log((e?.message ?? e).toString());
    }
  });
}

run();

起動（重要：proxy反映のため再起動が必要）

npm run dev

ブラウザで認証（ここからが “完走”）

http://localhost:5173/ を開く
Login with UiPath (OAuth) をクリック (図1)
UiPath Cloud のログイン/許可画面が出る → 許可 (図２)
http://localhost:5173/callback に戻る (図３)

図１:

図２（認証成功）:

図３（認証成功、Orchestrator側からのAsset取得成功）：

最後に

今回は、UiPath TypeScript SDK を利用するための 環境構築から認証・疎通確認まで を一通り実施しました。

特に、

Node.js / TypeScript 環境の整備
SDK の導入と設定ファイルの調整
Secret（PAT）認証での動作確認
OAuth 認証 + Vite + proxy による CORS 回避
実際の Assets 取得確認

までを通して、「実際に動く状態」まで到達すること をゴールに解説しました。

公式ドキュメントだけでは分かりづらい部分や、Node.js 24系での設定差異、ブラウザ実行時の CORS 問題など、実際に手を動かしてみないと気づきにくいポイントも多くあります。本記事が、それらの回避のヒントになれば幸いです。

ここまで完了すれば、UiPath TypeScript SDK を用いた開発の土台は整いました。