Writing a UI Application

This guide walks you through developing, building, and deploying a UI application plugin for Vertesia.

UI applications are React-based plugins that extend the Vertesia Studio interface with custom user experiences focused on specific use cases and business processes.

Vertesia provides a collection of reusable React components (via @vertesia/ui) to facilitate UI development, along with built-in authentication handling, allowing you to focus on your application's business logic rather than infrastructure and tooling concerns.

Prerequisites

• An application manifest created and installed in your Vertesia project
• Node.js and pnpm (or npm)

Creating Your Plugin

Initialize the Project

Use the @vertesia/create-plugin package to scaffold your plugin:

npm init @vertesia/plugin

You will be prompted for:

• Package manager: npm or pnpm
• Plugin name: Must match the name from your app manifest (kebab-case)
• Plugin version: Semantic version (e.g., 1.0.0)
• Description: Optional description
• Isolation strategy: shadow (recommended) or css

Project Structure

src/
├── app.tsx          # Main app component with router
├── plugin.tsx       # Plugin entry point for Vertesia integration
├── routes.tsx       # Application route definitions
├── pages.tsx        # Page components
└── main.tsx         # Dev mode entry point

Development

Start the development server:

pnpm dev

The app runs at https://localhost:5173 with hot module replacement.

Building

pnpm build

Deployment

To make your plugin accessible from the Vertesia Studio app portal, you must deploy it to a publicly accessible hosting provider (Vercel, Netlify, Cloudflare Pages, etc.).

Example: Deploying to Vercel

As an example, here's how to deploy your plugin to Vercel, a practical option with a generous free tier:

# Install Vercel CLI
npm i -g vercel

# Login
vercel login

# Deploy to production
vercel --prod

Update the App Manifest

After deployment, update your app manifest's ui.src to point to your deployed URL.

Important: The ui.src must point to the plugin JavaScript file at /lib/plugin.js in your deployment.

You can do this via the Vertesia CLI:

vertesia apps update my-app --manifest '{
  "name": "my-app",
  "title": "My App",
  "description": "A sample app",
  "publisher": "your-org",
  "private": true,
  "status": "beta",
  "ui": {
    "src": "https://your-app.vercel.app/lib/plugin.js",
    "isolation": "shadow"
  }
}'

Replace https://your-app.vercel.app with your actual deployment URL, keeping the /lib/plugin.js path.

Or through the UI in Settings > Available Apps.