@vertesia/create-plugin 0.79.1 → 0.80.0-dev-20251118

package/README.md

@@ -1,100 +1,105 @@
-# @vertesia/create-agent
+# @vertesia/create-plugin
 
-This package is scaffolding a vertesia agent project.
-Vertesia agents are used to deploy custom workflows to Vertesia cloud.
+This package scaffolds Vertesia plugin projects. Use it to create either:
 
-Visit https://vertesiahq.com for more information about Vertesia.
+- **Web Application Plugins**: React-based web applications that extend Vertesia Studio
+- **Agent Tool Server**: Custom agent tools accessible via API endpoints
 
-## Requirements:
-1. docker (with buildx support) installed locally.
-2. vertesia CLI application. The CLI will be automatically installed when initializing the agent project if you didn't installed it previously.
+Visit <https://vertesiahq.com> for more information about Vertesia.
 
-## Initialize a Vertesia agent project
+## What Can You Create?
 
-Run the command line command:
+### Web Application Plugin (UI Extensions)
 
-```
-npm init @vertesia/agent
-```
-
-Follow the instructions on screen. You need to define an organization and a name for your agent. The organization must be unique inside Vertesia and is usually the name of your Vertesia organization account. The agent name is identifying the project in your organization.
+Vertesia web plugins are React-based web application that can be embedded into the Vertesia Studio interface. They allow you to create custom user experiences focused on specific use cases and business processes, while seamlessly leveraging all the vertesia platform features.
 
-The generated project is a typescript project and is using [Temporal](https://temporal.io/) as the workflow system.
+### Agent Tool Server
 
-You can implement your own workflows and activities anywhere in the src/ directory or even in a dependency project. The only requirement is that you need to export the workflows and the activities from the `src/workflow.ts` and `src/activities.ts` files.
-These generated files are containing a "Hello world!" workflow and activity as an example that you should remove and export your own definitions.
+An Agent Tool Server extends the capabilities of AI agents in Vertesia. It allows you to:
 
+- Create custom tools that agents can use
+- Integrate with external APIs and services
+- Organize tools into logical collections
+- Expose tools via REST API endpoints
+- Support authentication and context-aware execution
 
-## Developing your agent workflows / activities.
+## Prerequisites
 
-Export your temporal workflows `from src/workflows.ts` and your activities from `src/activities.ts`
+Before creating a plugin project, you need:
 
-## Test locally the workflows.
+- Node.js and pnpm (or npm)
+- Vertesia CLI
+- An application manifest declared in Vertesia
 
-There are two ways to test the agent worker:
+### Declaring Your Web Application Plugin in Vertesia
 
-1. Using `npm start`. This will start the worker in your terminal.
-2. Using `vertesia agent run` from your project root. This will run the agent worker in side the docker image you previously built. See the [Build](build-the-agent-docker-image) section.
+Before you can develop and integrate your web application plugin with Vertesia, you must declare an application manifest in the Vertesia platform using the Vertesia CLI.
 
-**Important Note:** All `vertesia agent` commands must be executed in the agent project root.
+#### Install the Vertesia CLI
 
-## Debugging locally the workflows.
+If not already done, install the Vertesia CLI and create a profile:
 
-You can debug the workflows by replaying them locally using the temporal replayer that you can found in  `src/debug-replayer.ts`.
-
-See https://docs.temporal.io/develop/typescript/debugging for more information
+```bash
+npm install -g @vertesia/cli
+vertesia profiles create
+```
 
-## Packaging and publishing your Vertesia agent
+### Create the App Manifest
 
-When the workflows are working you will want to publish the agent to Vertesia.
-The agent should be packaged as a docker image and then published to the Vertesia cloud.
+Create the app manifest using the Vertesia CLI:
 
-### Build the agent docker image
+```bash
+vertesia apps create --manifest '{
+  "name": "my-app",
+  "title": "My App",
+  "description": "A sample app",
+  "publisher": "your-org",
+  "private": true,
+  "status": "beta"
+}' --install
+```
 
-When you are ready to test the agent image you can built it using `vertesia agent build` from you project root.
+The `--install` flag will automatically install the app and grant permissions to the creator.
 
-This will build a docker image tagged as `your-organization/your-agent-name:latest`.
-This image is only useable to test locally. You cannot push it to Vertesia.
+**Important**: The `name` field from your manifest (e.g., `my-app`) is what you'll use as your plugin name in the next step.
 
-### Releasing the agent docker image
+## Initialize a Plugin Project
 
-When you already to push your agent to Vertesia you must first create a version using the following command:
+Run the initialization command:
 
-```
-vertesia agent release <version>
+```bash
+npm init @vertesia/plugin
+# or
+pnpm create @vertesia/plugin
 ```
 
-The version must be in the `major.minor.patch[-modifier]` format. \
-Examples: `1.0.0`, `1.0.0-rc1`.
+You will be prompted to choose a template and provide configuration:
 
-This command is creating a new docker tag `your-organization/your-agent-name:version` from the `latest` image tag.
+### Prompts
 
-### Publishing the agent docker image to Vertesia
+1. **Template type**: Choose between:
+   - **Web application plugin**: For UI extensions
+   - **Agent tool server**: For custom agent tools
+2. **Package manager**: Choose between npm or pnpm
+3. **Plugin name**: Use kebab-case (e.g., my-plugin or my-tools)
+4. **Plugin version**: Semantic version (e.g., 1.0.0)
+5. **Description**: Optional description of your plugin
 
-Versioned images (using the `release` command) can be published to Vertesia. This can be done using the following command:
+### Web Application Plugin Specific
 
-```
-vertesia agent publish <version>
-```
+If you select the **Web application plugin** template, you'll also be asked:
 
-where the version is the version of the image tag you want to publish.
+1. **Isolation strategy**:
+   - **Shadow DOM**: Fully isolated plugin using Shadow DOM (recommended)
+   - **CSS-only isolation**: Lighter isolation using CSS scope, but may have style conflicts
 
-You can also only push the image to vertesia without deploying the agent by using the `--push-only` flag:
+## Working with Plugins
 
-```
-vertesia agent publish <version> --push-only
-```
-
-The you can deploy an agent that you previously uploaded to Vertesia by using the command:
-
-```
-vertesia agent publish <version> --deploy-only
-```
+After creating your project, see the README file in the generated project for comprehensive development instructions.
 
-## Managing agent versions
+## Support
 
-You can see the docker image versions you created using the following command:
+For issues, questions, or feature requests:
 
-```
-vertesia agent versions
-```
+- [GitHub Issues](https://github.com/vertesia/composableai/issues)
+- [Documentation](https://docs.vertesiahq.com/)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vertesia/create-plugin",
-    "version": "0.79.1",
+    "version": "0.80.0-dev-20251118",
     "description": "Initialize a Vertesia plugin package",
     "type": "module",
     "bin": {
@@ -22,7 +22,8 @@
     ],
     "scripts": {
         "eslint": "eslint './src/**/*.{jsx,js,tsx,ts}'",
-        "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && tsc --build",
+        "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && pnpm run typecheck:templates && tsc --build",
+        "typecheck:templates": "tsc --noEmit --project templates/tool/tsconfig.json",
         "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
     },
     "dependencies": {
@@ -32,6 +33,17 @@
     "devDependencies": {
         "@types/hasbin": "^1.2.2",
         "@types/node": "^22.5.0",
-        "typescript": "^5.7.2"
+        "typescript": "^5.7.2",
+        "hono": "^4.10.3",
+        "@hono/node-server": "^1.19.5",
+        "@llumiverse/common": "workspace:*",
+        "@vertesia/client": "workspace:*",
+        "@vertesia/common": "workspace:*",
+        "@vertesia/tools-sdk": "workspace:*"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/vertesia/composableai.git",
+        "directory": "packages/create-plugin"
     }
 }

package/templates/tool/.env.example

@@ -0,0 +1,6 @@
+# Environment variables for your tool collections
+
+# Add any API keys or configuration here
+# Example:
+# OPENAI_API_KEY=your-api-key-here
+# WEATHER_API_KEY=your-weather-api-key

package/templates/tool/.vscode/launch.json

@@ -21,4 +21,4 @@
             }
         }
     ]
-}
+}

package/templates/tool/README.md

@@ -1,31 +1,190 @@
-# Vertesia tools plugin
+# Tool Collections
 
-This plugin is exposing tools to vertesia. The tools as exposed on an external webs erver providing two endpoints:
-1. `GET /` - show tool descriptions
-2. `POST /` - execute a tool given an execution payload.
+This project contains custom tool collections for Vertesia.
 
-Note that when deployed on vercel the endpoints are:
+## Project Structure
 
-1. `GET /api`
-2. `POST /api`
+```txt
+src/
+├── collections/           # Tool collections
+│   ├── example/          # Example collection
+│   │   ├── icon.svg.ts   # Collection icon
+│   │   ├── index.ts      # Collection definition
+│   │   └── weather/      # Weather tool
+│   │       ├── manifest.ts     # Tool schema/metadata
+│   │       └── WeatherTool.ts  # Tool implementation
+│   └── index.ts          # Export all collections
+├── server.ts             # Hono server with collection endpoints
+└── index.ts              # Main exports
+```
+
+## Development
+
+Start the development server:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+The server will be available at `http://localhost:5174/api`
+
+### API Endpoints
 
-The payload used when executing a tool must conform to the following interface:
+- `GET /api` - List all collections
+- `GET /api/{collection}` - Get collection metadata and tool definitions
+- `POST /api/{collection}` - Execute a tool in the collection
 
-```ts
-interface ToolExecutionPayload<ParamsT extends Record<string, any>> {
-    context: {
-        serverUrl: string,
-        storeUrl: string,
-        apikey: string
+### Testing the API
+
+Get the example collection tools:
+
+```bash
+curl http://localhost:5174/api/example
+```
+
+Execute the weather tool:
+
+```bash
+curl -X POST http://localhost:5174/api/example \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+  "tool_use": {
+    "id": "test-123",
+    "tool_name": "weather",
+    "tool_input": {
+      "location": "New York, NY"
     }
-    vars: Record<string, any>,
-    tool_input: ParamsT,
-    tool_name: string,
+  }
+}'
+```
+
+## Creating New Tools
+
+### 1. Create a new tool in an existing collection
+
+1. Create a new directory under `src/collections/example/` (e.g., `my-tool/`)
+2. Create `manifest.ts` with your tool's schema
+3. Create `MyTool.ts` with the implementation
+4. Add the tool to `src/collections/example/index.ts`
+
+### 2. Create a new collection
+
+1. Create a new directory under `src/collections/` (e.g., `my-collection/`)
+2. Create `icon.svg.ts` with an SVG icon
+3. Create `index.ts` to define the collection
+4. Add your tools in subdirectories
+5. Export the collection in `src/collections/index.ts`
+
+## Authentication
+
+Tools receive authentication context through the `ToolExecutionContext` parameter:
+
+```typescript
+export async function myTool(
+    payload: ToolExecutionPayload<MyToolParams>,
+    context: ToolExecutionContext
+) {
+    // Access the decoded JWT token
+    const userId = context.payload.sub;
+    
+    // Get a Vertesia client instance
+    const client = await context.getClient();
+    
+    // Your tool logic here
+    return {
+        is_error: false,
+        content: "Tool result"
+    };
 }
 ```
 
-To launch the tools server you can start the vite dev server using `pnpm dev`.
+## Building for Production
+
+Build the project:
+
+```bash
+pnpm build
+```
+
+This creates an optimized build in the `dist/` directory.
+
+## Deployment
+
+Your Agent Tool Server can be deployed to various platforms. The server is built with Hono, which supports multiple runtimes including Node.js, Vercel Edge Functions, Cloudflare Workers, AWS Lambda, and more.
+
+For detailed guides on deploying to different platforms, visit the [Hono documentation](https://hono.dev/docs/). The documentation provides comprehensive examples for various deployment targets and runtimes.
+
+### Deploying to Vercel (Example)
+
+This section demonstrates deploying to Vercel as an example, since Vercel offers a generous free tier and simple deployment process. The project includes `api/index.ts` which serves as the entry point for Vercel deployment using the Hono Vercel adapter. Vercel automatically detects and configures the Edge Function.
+
+#### Setup
+
+Install the Vercel CLI globally:
+
+```bash
+npm i -g vercel
+```
+
+#### Deployment Steps
+
+1. **Login to Vercel**:
+
+    ```bash
+    vercel login
+    ```
+
+2. **Deploy to preview**:
+
+    ```bash
+    vercel
+    ```
+
+    This will create a preview deployment and provide you with a URL to test your tool server.
+
+3. **Deploy to production**:
+
+    ```bash
+    vercel --prod
+    ```
+
+Your tool server will be available at `https://your-project.vercel.app/api`
+
+For more information, visit the [Vercel CLI documentation](https://vercel.com/docs/cli).
+
+#### Verify Your Deployment
+
+Test that your server is responding correctly:
+
+```bash
+curl https://your-project.vercel.app/api
+```
+
+You should see a JSON response with the API information and available endpoints.
+
+#### Configure Your Tool Server in Vertesia
+
+After deploying to Vercel, update your app manifest to point to the deployed URL using the vertesia CLI:
+
+```bash
+vertesia apps update <appId> --manifest '{
+  "name": "my-app",
+  "title": "My App",
+  "description": "A sample app",
+  "publisher": "your-org",
+  "private": true,
+  "status": "beta",
+  "tool_collections": [
+    "https://your-app.vercel.app/api/example"
+  ],
+}'
+```
+
+Replace `appId` by the actual ID and `https://your-app.vercel.app` with your actual Vercel deployment URL.
 
-If you want to **debug** and add breakpoints in the code you must run the vite dev server from VSCode by running the `Debug Tools Server` launch configuration.
+## Learn More
 
-Vercel deployment is supported by wrapping the `hono` server using a vercel adapter.
+- [Vertesia Documentation](https://docs.vertesiahq.com)
+- [Tool SDK Reference](https://github.com/vertesia/composableai/tree/main/packages/tools-sdk)

package/templates/tool/gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+
+node_modules/
+
+# Build output
+
+dist/
+lib/
+\*.tsbuildinfo
+
+# Environment
+
+.env
+.env.local
+
+# IDE
+
+.vscode/
+.idea/
+_.swp
+_.swo
+
+# OS
+
+.DS_Store
+Thumbs.db

package/templates/tool/rollup.config.js

@@ -0,0 +1,30 @@
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import resolve from '@rollup/plugin-node-resolve';
+
+export default {
+    input: './dist/server.js',
+    output: {
+        file: './dist/bundle.js',
+        format: 'es',
+        sourcemap: false
+    },
+    plugins: [
+        resolve({
+            preferBuiltins: true,
+            exportConditions: ['node']
+        }),
+        commonjs(),
+        json()
+    ],
+    external: [
+        // Keep these as external dependencies
+        'hono',
+        'jose',
+        'dotenv',
+        '@vertesia/client',
+        '@vertesia/common',
+        '@vertesia/tools-sdk',
+        '@hono/node-server'
+    ]
+};

package/templates/tool/src/collections/example/icon.svg.ts

@@ -0,0 +1,6 @@
+// Simple SVG icon for the collection
+// You can replace this with your own icon
+export const icon = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="10"/>
+  <path d="M12 6v6l4 2"/>
+</svg>`;

package/templates/tool/src/collections/example/index.ts

@@ -0,0 +1,14 @@
+import { ToolCollection } from "@vertesia/tools-sdk";
+import { icon } from "./icon.svg.js";
+import { WeatherTool } from "./weather/WeatherTool.js";
+
+export const ExampleCollection = new ToolCollection({
+    name: "example",
+    title: "Example Tools",
+    description: "A collection of example tools to get you started",
+    icon,
+    tools: [
+        WeatherTool
+        // Add more tools here
+    ]
+});

package/templates/tool/src/collections/example/weather/WeatherTool.ts

@@ -0,0 +1,32 @@
+import type { Tool, ToolExecutionPayload, ToolExecutionContext } from "@vertesia/tools-sdk";
+import manifest from "./manifest.js";
+import { ToolResultContent } from "@vertesia/common";
+
+interface WeatherToolParams {
+    location: string;
+}
+
+// Tool implementation function
+export async function weather(
+    payload: ToolExecutionPayload<WeatherToolParams>,
+    context: ToolExecutionContext
+) {
+    const { location } = payload.tool_use.tool_input!;
+
+    console.log(`Caller: ${context.payload.user_id}`);
+    
+    // Simulate fetching weather data
+    // In a real implementation, you would call a weather API here
+    // You can use context.getClient() to access Vertesia services if needed
+    
+    return {
+        is_error: false,
+        content: `The current weather in ${location} is sunny with a temperature of 75°F.`
+    } satisfies ToolResultContent;
+}
+
+// Export the complete tool with manifest and implementation
+export const WeatherTool = {
+    ...manifest,
+    run: weather
+} satisfies Tool<WeatherToolParams>;

package/templates/tool/src/collections/example/weather/manifest.ts

@@ -0,0 +1,16 @@
+import { ToolDefinition } from "@vertesia/tools-sdk";
+
+export default {
+    name: "weather",
+    description: "Get the current weather for a given location.",
+    input_schema: {
+        type: "object",
+        properties: {
+            location: {
+                type: "string",
+                description: "The location to get the weather for, e.g., 'New York, NY'."
+            }
+        },
+        required: ["location"]
+    },
+} satisfies ToolDefinition;

package/templates/tool/src/collections/index.ts

@@ -0,0 +1,7 @@
+import { ExampleCollection } from "./example/index.js";
+
+// Export all your tool collections here
+export const collections = [
+    ExampleCollection
+    // Add more collections as you create them
+];

package/templates/tool/src/index.ts

@@ -1,6 +1,5 @@
-import { ToolRegistry } from '@vertesia/agent-sdk';
-import { WeatherTool } from "./tools/WeatherTool.js";
+// Export collections for use in other modules or for programmatic access
+export { collections } from "./collections/index.js";
 
-export const registry = new ToolRegistry([
-    WeatherTool
-]);
+// Export server as default for deployment
+export { default } from "./server.js";

package/templates/tool/src/server.ts

@@ -1,19 +1,71 @@
-import { Hono } from 'hono';
-import { registry } from "./index.js";
-import { cors } from 'hono/cors'
-
-const app = new Hono();
-app.get("/", cors({ origin: '*', allowMethods: ['GET'] }))
-app.post('/', async (c) => {
-    const data = await c.req.json();
-    const r = await registry.execute(data)
-    return c.json({
-        response: r
+import { ToolCollection } from "@vertesia/tools-sdk";
+import { Context, Hono } from "hono";
+import { cors } from "hono/cors";
+import { collections } from "./collections/index.js";
+import { HTTPException } from "hono/http-exception";
+
+function createServer(collections: ToolCollection[], prefix = '/api') {
+    prefix = prefix.trim();
+    const app = new Hono();
+
+    // Add CORS middleware globally
+    app.use('*', cors({ origin: '*', allowMethods: ['GET', 'POST', 'OPTIONS'] }));
+
+    // Add base API route
+    app.get(prefix, (c) => {
+        return c.json({
+            message: 'Tool Collections API',
+            version: '1.0.0',
+            endpoints: {
+                collections: collections.map(col => `${prefix}/${col.name}`)
+            }
+        });
+    });
+
+    // Create endpoints for tool collections
+    for (const col of collections) {
+        app.route(`${prefix}/${col.name}`, createCollectionEndpoints(col));
+    }
+
+    // Global error handler
+    app.onError((err, c) => {
+        if (err instanceof HTTPException) {
+            return c.json({
+                error: err.message,
+            }, err.status);
+        }
+        console.error('Uncaught Error:', err);
+        return c.json({
+            error: 'Internal Server Error',
+        }, 500)
     })
-})
 
-app.get('/', (c) => {
-    return c.json(registry.getDefinitions())
-});
+    return app;
+}
+
+const server = createServer(collections);
+
+export default server;
+
+/**
+ * Create endpoints for a tool collection
+ */
+function createCollectionEndpoints(coll: ToolCollection) {
+    const endpoint = new Hono();
+
+    // POST endpoint to execute tools
+    endpoint.post('/', (c: Context) => {
+        return coll.execute(c);
+    });
+
+    // GET endpoint to retrieve collection metadata and tool definitions
+    endpoint.get('/', (c) => {
+        return c.json({
+            title: coll.title || coll.name,
+            description: coll.description,
+            tools: coll.getToolDefinitions()
+        });
+    });
 
-export default app;
+    return endpoint;
+}

package/templates/tool/tsconfig.json

@@ -1,14 +1,24 @@
 {
     "compilerOptions": {
-        "target": "ES2020",
+        "target": "ES2022",
         "module": "ESNext",
-        "moduleResolution": "node",
+        "moduleResolution": "Bundler",
         "esModuleInterop": true,
         "strict": true,
         "skipLibCheck": true,
+        "resolveJsonModule": true,
+        "allowSyntheticDefaultImports": true,
+        "forceConsistentCasingInFileNames": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noImplicitReturns": true,
         "outDir": "dist"
     },
     "include": [
-        "src"
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
     ]
-}
+}

package/templates/tool/vite.config.js

@@ -1,10 +1,48 @@
-import { defineConfig } from 'vite';
 import devServer from '@hono/vite-dev-server';
+import { defineConfig, loadEnv } from 'vite';
 
-export default defineConfig({
-    plugins: [
-        devServer({
-            entry: 'src/server.ts', // Adjust the path to your server entry file
-        }),
-    ],
-});
+export default defineConfig(({ mode }) => {
+    // Load env files
+    const env = loadEnv(mode, process.cwd(), '');
+
+    // Dev config
+    if (mode === 'development') {
+        return {
+            plugins: [
+                devServer({
+                    prefix: '/api',  // mount the tool endpoints under /api
+                    entry: './src/server.ts',
+                }),
+            ],
+        }
+    }
+
+    // Build config
+    return {
+        build: {
+            minify: false,
+            lib: {
+                entry: {
+                    server: './src/server.ts',
+                },
+                formats: ['es']
+            },
+            rollupOptions: {
+                external: (id) => {
+                    // Keep relative imports as part of the bundle
+                    if (id.startsWith('.') || id.startsWith('/')) {
+                        return false;
+                    }
+                    // Externalize all node modules and absolute imports
+                    return true;
+                },
+                output: {
+                    preserveModules: true,
+                    preserveModulesRoot: 'src',
+                    entryFileNames: '[name].js'
+                }
+            },
+            outDir: 'dist'
+        },
+    }
+});

package/templates/web/README.md

@@ -1,54 +1,156 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default tseslint.config({
-  extends: [
-    // Remove ...tseslint.configs.recommended and replace with this
-    ...tseslint.configs.recommendedTypeChecked,
-    // Alternatively, use this for stricter rules
-    ...tseslint.configs.strictTypeChecked,
-    // Optionally, add this for stylistic rules
-    ...tseslint.configs.stylisticTypeChecked,
-  ],
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
+# Vertesia Custom App Sample
+
+A sample project demonstrating how to build a custom app/plugin for the Vertesia platform using React, TypeScript, and Vite.
+
+## Overview
+
+This project serves as a template for building Vertesia plugins that can be integrated into the Vertesia platform. It includes:
+
+- React 19 with TypeScript for type-safe component development
+- Tailwind CSS for styling
+- Vite for fast development and optimized builds
+- Dual build modes: standalone app and plugin library
+
+## Project Structure
+
+```txt
+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
+```
+
+## Getting Started
+
+### Installation
+
+```bash
+pnpm install
+```
+
+### Development
+
+Run the app in development mode with hot module replacement:
+
+```bash
+pnpm dev
+```
+
+The app will be available at `https://localhost:5173`.
+
+### Building
+
+Build both standalone app and plugin library:
+
+```bash
+pnpm build
+```
+
+Or build individually:
+
+```bash
+# Build standalone app
+pnpm build:app
+
+# Build plugin library
+pnpm build:lib
+```
+
+The plugin library will be output to the `dist/lib/` directory.
+
+## Deployment
+
+Since this is a standard web application, you can deploy it to any static hosting provider (Vercel, Netlify, Cloudflare Pages, AWS S3, etc.).
+
+### Deploying to Vercel
+
+Vercel is a practical deployment option with a generous free tier. You can very simply deploy your standalone app using the Vercel CLI.
+
+#### Setup
+
+Install the Vercel CLI globally:
+
+```bash
+npm i -g vercel
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default tseslint.config({
-  plugins: {
-    // Add the react-x and react-dom plugins
-    'react-x': reactX,
-    'react-dom': reactDom,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended typescript rules
-    ...reactX.configs['recommended-typescript'].rules,
-    ...reactDom.configs.recommended.rules,
-  },
-})
+#### Deployment Steps
+
+1. **Login to Vercel**:
+
+    ```bash
+    vercel login
+    ```
+
+2. **Deploy to preview**:
+
+    ```bash
+    vercel
+    ```
+
+    This will create a preview deployment and provide you with a URL to test your app.
+
+3. **Deploy to production**:
+
+    ```bash
+    vercel --prod
+    ```
+
+For more information, visit the [Vercel CLI documentation](https://vercel.com/docs/cli).
+
+#### Update App Manifest with Deployment URL
+
+After deploying to Vercel, update your app manifest to point to the deployed URL using the vertesia CLI:
+
+```bash
+vertesia apps update <appId> --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 `appId` by the actual ID and `https://your-app.vercel.app` with your actual Vercel deployment URL.
+
+## Key Features
+
+### Dual Build Modes
+
+- **App Mode**: Builds a standalone application for development and testing
+- **Library Mode**: Builds a plugin that can be integrated into the Vertesia platform
+
+### External Dependencies
+
+When building as a plugin, React and Vertesia dependencies are externalized to prevent duplication:
+
+- `react` / `react-dom`
+- `@vertesia/common`
+- `@vertesia/ui`
+
+## Tech Stack
+
+- **React 19** - UI framework
+- **TypeScript** - Type safety
+- **Vite** - Build tool and dev server
+- **Tailwind CSS 4** - Styling
+- **@vertesia/ui** - Vertesia UI components
+- **@vertesia/plugin-builder** - Plugin build utilities
+
+## Development Notes
+
+- The dev server uses HTTPS (via `@vitejs/plugin-basic-ssl`)
+- CSS can be inlined in the plugin bundle or kept separate (configured in [vite.config.ts](vite.config.ts))
+- For debugging Vertesia UI sources, set `VERTESIA_UI_PATH` in [vite.config.ts](vite.config.ts)
+
+## License
+
+See package.json for license information.

package/templates/web/eslint.config.js

@@ -3,8 +3,9 @@ import globals from 'globals'
 import reactHooks from 'eslint-plugin-react-hooks'
 import reactRefresh from 'eslint-plugin-react-refresh'
 import tseslint from 'typescript-eslint'
+import { defineConfig } from 'eslint/config';
 
-export default tseslint.config(
+export default defineConfig(
   { ignores: ['dist'] },
   {
     extends: [js.configs.recommended, ...tseslint.configs.recommended],

package/templates/web/gitignore

@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+lib
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/templates/web/src/env.ts.tmpl

@@ -4,17 +4,11 @@ Env.init({
     name: "${plugin_title}",
     version: "1.0.0",
     isLocalDev: true,
-    isDocker: false,
+    isDocker: true,
     type: "development",
     endpoints: {
-        studio: "http://127.0.0.1:8091",
-        zeno: "http://127.0.0.1:8092",
-    },
-    firebase: {
-        apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
-        authDomain: window.location.host,
-        projectId: "dengenlabs",
-        appId: "1:265888598630:web:6e5e76c8ecde887e5afba7"
-    },
-    datadog: false,
+        studio: "https://api.vertesia.io",
+        zeno: "https://api.vertesia.io",
+        sts: "https://sts.vertesia.io",
+    }
 });

package/templates/web/vite.config.ts.tmpl

@@ -40,7 +40,7 @@ const inlineCss = ${ inlineCss };
  * Vite configuration to build the plugin as a library or as a standalone application or to run the application in dev mode.
  * Use `vite build --mode lib` to build a library (plugin)
  * Use `vite build` or `vite build --mode app`to build a standalone application
- * Use `vite dev` to run the applicaiton in dev mode.
+ * Use `vite dev` to run the application in dev mode.
  */
 export default defineConfig((env) => {
     if (env.mode === 'lib') {
@@ -83,7 +83,7 @@ function defineLibConfig({ command }: ConfigEnv): UserConfig {
 }
 
 /**
- * Vite configuration to run the applicaiton in dev mode
+ * Vite configuration to run the application in dev mode
  * or to build a standalone application.
  * @returns
  */
@@ -115,8 +115,10 @@ function defineAppConfig(): UserConfig {
         resolve: {
             // For debug support in vertesia ui sources - link to the vertesia/ui location
             alias: VERTESIA_UI_PATH ? {
-                "@vertesia/ui/*": resolve(`${VERTESIA_UI_PATH}/src/*/index.ts`)
-            } : undefined
+                "@vertesia/ui": resolve(`${VERTESIA_UI_PATH}/src`)
+            } : undefined,
+            // Deduplicate React to prevent multiple instances
+            dedupe: ['react', 'react-dom']
         }
     }
 }

package/templates/tool/src/tools/WeatherTool.ts

@@ -1,25 +0,0 @@
-import type { Tool, ToolFunctionParams } from "@vertesia/agent-sdk";
-
-interface WeatherToolParams {
-    location: string;
-}
-
-export const WeatherTool = {
-    name: "weather",
-    description: "Get the current weather for a given location.",
-    input_schema: {
-        type: "object",
-        properties: {
-            location: {
-                type: "string",
-                description: "The location to get the weather for, e.g., 'New York, NY'."
-            }
-        },
-        required: ["location"]
-    },
-    run: async (params: ToolFunctionParams<WeatherToolParams>) => {
-        const { location } = params.input;
-        // Simulate fetching weather data
-        return `The current weather in ${location} is sunny with a temperature of 75°F.`;
-    }
-} satisfies Tool<WeatherToolParams>;

package/templates/tool/vercel.json

@@ -1,7 +0,0 @@
-{
-    "functions": {
-        "api/index.ts": {
-            "runtime": "edge"
-        }
-    }
-}