@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-coded-apps/assets/templates/web-app-template.md

@@ -2,27 +2,29 @@
 
 Ready-to-use boilerplate for a new UiPath Coded Web App (Vite + React + TypeScript + Tailwind) using the `@uipath/uipath-typescript` SDK. Replace `{{PLACEHOLDER}}` values with the answers gathered in the workflow at [../../references/create-web-app.md](../../references/create-web-app.md).
 
+**Both Q6 paths share the same Tailwind toolchain and SDK initialization pattern.** The SDK is instantiated with `new UiPath()` (no config) — `clientId`, `scope`, `orgName`, `tenantName`, `baseUrl`, and `redirectUri` are read at runtime from `<meta name="uipath:*">` tags. During local dev the `@uipath/coded-apps-dev` Vite plugin injects those tags from `uipath.json` (committed); the UiPath platform injects them in production.
+
+Files are grouped below by path. When a file differs between the two paths, its variants appear as `Q6 = no (bare Tailwind)` / `Q6 = yes (apollo-wind)` subsections; a single block means the file is shared verbatim. The only real divergence is the component layer: Q6 = yes adds `@uipath/apollo-wind` components, Apollo design tokens, and a light/dark theme toggle; Q6 = no leaves bare Tailwind so you bring your own component library.
+
+The substitution table in [Step 4.5](../../references/create-web-app.md#45--write-project-files-from-templates) says which subsection to use per path.
+
 ---
 
 ## `vite.config.ts`
 
-`base: './'` is **always required** — the platform handles URL routing; the app must use relative asset paths. The `path-browserify` alias and `global: 'globalThis'` define are needed by the SDK in the browser.
+Shared by both paths. `base: './'` is **always required** — the platform handles URL routing; the app must use relative asset paths. The `uipathCodedApps()` plugin reads `uipath.json` and injects `<meta name="uipath:*">` tags during local dev, so `new UiPath()` (no config) sees the same values in dev that the platform injects in production.
 
 ```typescript
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
+import { uipathCodedApps } from '@uipath/coded-apps-dev/vite'
 
 export default defineConfig({
-  plugins: [react()],
   base: './',
-  define: {
-    global: 'globalThis',
-  },
-  resolve: {
-    alias: {
-      path: 'path-browserify',
-    },
-  },
+  plugins: [
+    react(),
+    uipathCodedApps(),
+  ],
   optimizeDeps: {
     include: ['@uipath/uipath-typescript'],
   },
@@ -35,50 +37,26 @@ Do not add `server.proxy` — it interferes with the OAuth callback and asset re
 
 ## `uipath.json`
 
-Project-root config consumed by the `uip codedapp` CLI for deployment and by the Vite plugin for local dev meta-tag injection. Keep in sync with `.env` if scopes or client ID change.
+Shared by both paths. Project-root config consumed by the `uip codedapp` CLI for deployment and by the `uipathCodedApps()` Vite plugin for local-dev meta-tag injection. **Single source of truth for the SDK config** — no `.env`, and the plugin does not read `.uipath/`.
 
 ```json
 {
+  "clientId": "{{CLIENT_ID}}",
   "scope": "{{SCOPES}}",
-  "clientId": "{{CLIENT_ID}}"
+  "orgName": "{{ORG_NAME}}",
+  "tenantName": "{{TENANT_NAME}}",
+  "baseUrl": "{{BASE_URL}}",
+  "redirectUri": "http://localhost:5173"
 }
 ```
 
----
-
-## `.env`
-
-OAuth env vars consumed by `src/App.tsx` via `import.meta.env`. **No redirect URI env var** — the SDK computes it at runtime as `window.location.origin + window.location.pathname`.
-
-```
-VITE_UIPATH_CLIENT_ID={{CLIENT_ID}}
-VITE_UIPATH_SCOPE={{SCOPES}}
-VITE_UIPATH_ORG_NAME={{ORG_NAME}}
-VITE_UIPATH_TENANT_NAME={{TENANT_NAME}}
-VITE_UIPATH_BASE_URL={{BASE_URL}}
-```
-
-`{{BASE_URL}}` values: `https://api.uipath.com` (cloud) · `https://staging.api.uipath.com` (staging) · `https://alpha.api.uipath.com` (alpha)
-
----
-
-## `.env.example`
-
-Committed to the repo as a placeholder for new clones. No substitutions.
-
-```
-VITE_UIPATH_CLIENT_ID=
-VITE_UIPATH_SCOPE=
-VITE_UIPATH_ORG_NAME=
-VITE_UIPATH_TENANT_NAME=
-VITE_UIPATH_BASE_URL=https://api.uipath.com
-```
+The SDK reads `redirectUri` from the `uipath:redirect-uri` meta tag. Locally the plugin injects that tag from the `redirectUri` field above (the Vite dev URL). In production the platform injects every `<meta name="uipath:*">` tag itself, so these committed values only drive local dev. To change any value, edit this file. To set the redirect URI in code instead, pass it to the constructor — `new UiPath({ redirectUri: window.location.origin + window.location.pathname })` — which takes precedence over the meta tag; the templates omit it and rely on the tag.
 
 ---
 
 ## `src/hooks/useAuth.tsx`
 
-`AuthProvider` + `useAuth` hook. Handles PKCE callback detection on return from login, exposes `login()` / `logout()` for the UI, and tracks auth state. The OAuth config comes in via the `<AuthProvider>`'s `config` prop, which `App.tsx` supplies from `import.meta.env`. No substitutions in this file.
+Shared by both paths. `AuthProvider` + `useAuth` hook. Handles PKCE callback detection on return from login, exposes `login()` / `logout()` for the UI, and tracks auth state. The SDK is instantiated with `new UiPath()` (no config) — it reads `clientId`, `scope`, `orgName`, `tenantName`, `baseUrl`, and `redirectUri` at runtime from the `<meta name="uipath:*">` tags injected by `@uipath/coded-apps-dev` (in dev) or by the platform (in production). No substitutions in this file.
 
 Create the `src/hooks/` directory if it does not exist before writing.
 
@@ -86,7 +64,6 @@ Create the `src/hooks/` directory if it does not exist before writing.
 import React, { useState, useEffect, useRef, createContext, useContext } from 'react';
 import type { ReactNode } from 'react';
 import { UiPath, UiPathError } from '@uipath/uipath-typescript/core';
-import type { UiPathSDKConfig } from '@uipath/uipath-typescript/core';
 
 interface AuthContextType {
   isAuthenticated: boolean;
@@ -99,11 +76,14 @@ interface AuthContextType {
 
 const AuthContext = createContext<AuthContextType | undefined>(undefined);
 
-export const AuthProvider: React.FC<{ children: ReactNode; config: UiPathSDKConfig }> = ({ children, config }) => {
+export const AuthProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
   const [isAuthenticated, setIsAuthenticated] = useState(false);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
-  const [sdk] = useState<UiPath>(() => new UiPath(config));
+  // `new UiPath()` reads clientId/orgName/tenantName/baseUrl/scope/redirectUri
+  // from <meta name="uipath:*"> tags. The uipathCodedApps() Vite plugin
+  // injects them locally from uipath.json; the platform injects them in prod.
+  const [sdk] = useState<UiPath>(() => new UiPath());
   const didInit = useRef(false);
 
   useEffect(() => {
@@ -183,22 +163,71 @@ export const useAuth = () => {
 
 ---
 
+## `postcss.config.js`
+
+### Q6 = no (bare Tailwind)
+
+```js
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+    autoprefixer: {},
+  },
+}
+```
+
+### Q6 = yes (apollo-wind)
+
+Apollo-wind ships its own PostCSS config — re-export it directly so the app stays in lockstep with the design system.
+
+```js
+import apolloWindPostcss from '@uipath/apollo-wind/postcss'
+
+export default apolloWindPostcss
+```
+
+> **Why no `tailwind.config.js`?** On both paths, all Tailwind configuration (theme tokens, `@source` paths, dark-mode trigger) lives directly in `src/index.css`.
+
+---
+
+## `src/index.css`
+
+Overwrite the file Vite generated.
+
+### Q6 = no (bare Tailwind)
+
+A single `@import` pulls in Tailwind's base, components, and utilities. Customize theme tokens (colors, fonts, spacing) inline via `@theme { … }` per the Tailwind docs.
+
+```css
+@import "tailwindcss";
+```
+
+### Q6 = yes (apollo-wind)
+
+Imports apollo-wind's Tailwind source (base + utilities + Apollo tokens + `.dark` overrides), then tells Tailwind where to scan for utility classes. Apollo-wind components live under `node_modules/@uipath/apollo-wind/dist` and Tailwind skips `node_modules` by default — the `@source` directive opts that path back in so the components' utility classes (e.g. the Dialog's `p-6 gap-4`) actually get generated.
+
+```css
+/* Tailwind base + utilities, Apollo design tokens, light/dark overrides. */
+@import '@uipath/apollo-wind/tailwind.css';
+
+/* Tailwind skips node_modules — opt apollo-wind back in so its components'
+   utility classes are emitted. The second line scans this app's own files. */
+@source '../node_modules/@uipath/apollo-wind/dist';
+@source './';
+```
+
+---
+
 ## `src/App.tsx`
 
 Wraps app content in `<AuthProvider>` and renders a sign-in screen until the user is authenticated. Overwrite the file Vite generated. No substitutions.
 
+### Q6 = no (bare Tailwind)
+
+Bare HTML + Tailwind utility classes — bring your own component library to replace the buttons/cards as needed.
+
 ```tsx
 import { AuthProvider, useAuth } from './hooks/useAuth';
-import type { UiPathSDKConfig } from '@uipath/uipath-typescript/core';
-
-const authConfig: UiPathSDKConfig = {
-  clientId: import.meta.env.VITE_UIPATH_CLIENT_ID,
-  orgName: import.meta.env.VITE_UIPATH_ORG_NAME,
-  tenantName: import.meta.env.VITE_UIPATH_TENANT_NAME,
-  baseUrl: import.meta.env.VITE_UIPATH_BASE_URL,
-  redirectUri: window.location.origin + window.location.pathname,
-  scope: import.meta.env.VITE_UIPATH_SCOPE,
-};
 
 function AppContent() {
   const { isAuthenticated, isLoading, error, login, logout } = useAuth();
@@ -242,7 +271,7 @@ function AppContent() {
 
 function App() {
   return (
-    <AuthProvider config={authConfig}>
+    <AuthProvider>
       <AppContent />
     </AuthProvider>
   );
@@ -251,47 +280,195 @@ function App() {
 export default App;
 ```
 
----
+### Q6 = yes (apollo-wind)
 
-## `tailwind.config.js`
+Renders an apollo-wind sign-in card while unauthenticated, then a minimal authenticated shell with a `<ThemeToggle>` + `Sign out` in the header.
 
-```js
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
-  theme: { extend: {} },
-  plugins: [],
+```tsx
+import { LayoutDashboard, LogOut, ShieldCheck } from 'lucide-react'
+import { Alert, AlertDescription } from '@uipath/apollo-wind/components/ui/alert'
+import { Button } from '@uipath/apollo-wind/components/ui/button'
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@uipath/apollo-wind/components/ui/card'
+import { Spinner } from '@uipath/apollo-wind/components/ui/spinner'
+import { Toaster } from '@uipath/apollo-wind/components/ui/sonner'
+import { AuthProvider, useAuth } from './hooks/useAuth'
+import { ThemeToggle } from './components/Theme'
+
+function AppContent() {
+  const { isAuthenticated, isLoading, login, logout, error } = useAuth()
+
+  if (isLoading) {
+    return (
+      <div className="flex h-screen items-center justify-center">
+        <Spinner label="Initializing UiPath SDK…" showLabel />
+      </div>
+    )
+  }
+
+  if (!isAuthenticated) {
+    return (
+      <div className="flex min-h-screen items-center justify-center bg-background p-4">
+        <Card className="w-full max-w-sm">
+          <CardHeader className="items-center text-center">
+            <div className="mb-2 flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+              <ShieldCheck className="h-6 w-6" />
+            </div>
+            <CardTitle>Welcome</CardTitle>
+            <CardDescription>
+              Sign in with your UiPath account to continue.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            {error && (
+              <Alert variant="destructive">
+                <AlertDescription>{error}</AlertDescription>
+              </Alert>
+            )}
+            <Button onClick={login} className="w-full">
+              Sign in with UiPath
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex h-screen flex-col overflow-hidden bg-background text-foreground">
+      <header className="flex items-center justify-between gap-4 border-b px-4 py-3 sm:px-6">
+        <div className="flex min-w-0 items-center gap-2">
+          <LayoutDashboard className="h-5 w-5 shrink-0 text-primary" />
+          <h1 className="truncate text-base font-semibold">My App</h1>
+        </div>
+        <div className="flex items-center gap-2">
+          <ThemeToggle />
+          <Button variant="ghost" size="sm" onClick={logout}>
+            <LogOut className="h-4 w-4" />
+            <span className="hidden sm:inline">Sign out</span>
+          </Button>
+        </div>
+      </header>
+      <main className="min-h-0 flex-1 p-6">Your app content here</main>
+      <Toaster />
+    </div>
+  )
+}
+
+export default function App() {
+  return (
+    <AuthProvider>
+      <AppContent />
+    </AuthProvider>
+  )
 }
 ```
 
 ---
 
-## `postcss.config.js`
+## `src/components/Theme.tsx` (Q6 = yes only)
 
-```js
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
+Wraps the app in `next-themes` and exposes a tiny Sun/Moon `<ThemeToggle>` button. `attribute="class"` toggles the `.dark` class on `<html>` so apollo-wind's built-in dark tokens take over. Place this file at `src/components/Theme.tsx`; create the directory if it does not exist.
+
+```tsx
+import { Moon, Sun } from 'lucide-react'
+import { ThemeProvider, useTheme } from 'next-themes'
+import type { ReactNode } from 'react'
+import { Button } from '@uipath/apollo-wind/components/ui/button'
+
+/** Wraps the app in next-themes with a `.dark` class on <html>. */
+export function AppThemeProvider({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+      {children}
+    </ThemeProvider>
+  )
+}
+
+/** Sun/Moon button — cycles light ↔ dark. */
+export function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme()
+  const next = resolvedTheme === 'dark' ? 'light' : 'dark'
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(next)}
+      aria-label={`Switch to ${next} mode`}
+      title={`Switch to ${next} mode`}
+    >
+      <Sun className="h-4 w-4 dark:hidden" />
+      <Moon className="hidden h-4 w-4 dark:block" />
+    </Button>
+  )
 }
 ```
 
 ---
 
-## `src/index.css`
+## `src/main.tsx` (Q6 = yes only)
 
-Overwrite the file Vite generated.
+Wrap `<App>` in `<AppThemeProvider>` so the theme is available before any apollo-wind component mounts. Overwrite Vite's default `main.tsx`. (The Q6 = no path keeps Vite's generated `main.tsx` unchanged.)
 
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+```tsx
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+import { AppThemeProvider } from './components/Theme'
+
+createRoot(document.getElementById('root')!).render(
+  <AppThemeProvider>
+    <App />
+  </AppThemeProvider>,
+)
 ```
 
+> The yes path intentionally does not import `StrictMode`. The OAuth `code` is single-use; the `didInit` guard in `useAuth` already prevents the double-invoke, so adding `StrictMode` provides no extra safety here. If you need StrictMode for other reasons, leave the guard in place.
+
+---
+
+## Common apollo-wind imports (Q6 = yes only)
+
+Reach for these primitives instead of styling raw HTML. Each import is a single subpath under `@uipath/apollo-wind/components/ui/<name>`:
+
+| Need | Component | Import path |
+|------|-----------|-------------|
+| Action buttons | `Button` | `@uipath/apollo-wind/components/ui/button` |
+| Containers | `Card`, `CardHeader`, `CardContent`, `CardTitle`, `CardDescription`, `CardFooter` | `@uipath/apollo-wind/components/ui/card` |
+| Modals | `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter` | `@uipath/apollo-wind/components/ui/dialog` |
+| Side panels | `Sheet`, `SheetContent`, `SheetHeader`, `SheetTitle` | `@uipath/apollo-wind/components/ui/sheet` |
+| Inline status | `Alert`, `AlertDescription`, `AlertTitle` | `@uipath/apollo-wind/components/ui/alert` |
+| Toasts | `Toaster` + `toast()` | `@uipath/apollo-wind/components/ui/sonner` |
+| Tags / chips | `Badge` | `@uipath/apollo-wind/components/ui/badge` |
+| Loading | `Spinner`, `Skeleton` | `@uipath/apollo-wind/components/ui/spinner`, `…/skeleton` |
+| Tabs | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | `@uipath/apollo-wind/components/ui/tabs` |
+| Forms | `Input`, `Textarea`, `Checkbox`, `Select`, `Label` | `@uipath/apollo-wind/components/ui/<name>` |
+| Empty states | `EmptyState` | `@uipath/apollo-wind/components/ui/empty-state` |
+| Pickers | `Popover` + `Command` primitives | `@uipath/apollo-wind/components/ui/popover`, `…/command` |
+
+> **Combobox caveat.** Apollo-wind ships a `Combobox` wrapper, but its `CommandItem` is keyed by `value={item.value}` (the id). cmdk filters by `value`, so typing a label finds nothing. When you need name-based search, compose `Popover` + `Command` directly and set `value={item.label}` on each `CommandItem`.
+
+### Semantic Apollo design tokens
+
+Use the semantic CSS variables, not raw colors — they automatically flip in `.dark` mode. Common ones (Tailwind reads them via `bg-background`, `text-foreground`, etc.):
+
+- `--color-background` / `--color-foreground` — page surface + text
+- `--color-card` / `--color-card-foreground` — cards/panels
+- `--color-primary` / `--color-primary-foreground` — primary actions
+- `--color-muted` / `--color-muted-foreground` — secondary text/surfaces
+- `--color-border` — dividers (use `var(--color-border)` directly when the token is needed inside non-Tailwind CSS, e.g. AG Grid theming)
+- `--color-destructive` / `--color-destructive-foreground` — errors
+
+Avoid `hsl(var(--border))`-style references — apollo-core defines `--border` as a CSS shorthand (`1px solid #...`), not a bare color, so wrapping it in `hsl()` produces invalid CSS. Use `var(--color-border)` instead.
+
 ---
 
-## Optional: Router base path
+## Optional: Router base path (both paths)
 
 Only add this if the app uses a client-side router. Set the basename/base to `getAppBase()` — it reads the `uipath:app-base` meta tag injected by the platform at runtime and falls back to `'/'` locally, so it is safe to use unconditionally.