@kaptive/create-widget 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 state systems gmbh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @kaptive/create-widget
+
+Scaffolds a new [Kaptive](https://kaptive.ch) custom widget project.
+
+A Kaptive custom widget is a small web app that a workspace admin uploads as a bundle and drops into any project. This scaffolds everything needed to build one, typed parameters included.
+
+## Usage
+
+```bash
+npm create @kaptive/widget
+```
+
+or, with a directory and options up front:
+
+```bash
+npm create @kaptive/widget my-widget -- --name "Weather" --id weather
+```
+
+Prompts for a project directory, display name, stable widget id, description, and framework (React today), then writes a ready-to-run project. `-y`/`--yes` accepts the defaults without prompting, for a non-interactive run.
+
+### Options
+
+| Flag                   | What it sets                                                                                                                                                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`        | Display name shown in the Kaptive editor.                                                                                                                                                                                              |
+| `--id <id>`            | Stable widget id: 3–64 lowercase letters, digits or dashes, starting with a letter or digit. Chosen once and never changed — re-uploading a bundle with the same id creates a new version of the same widget rather than a second one. |
+| `--description <text>` | One-line description.                                                                                                                                                                                                                  |
+| `--framework <id>`     | Widget framework. Only `react` today.                                                                                                                                                                                                  |
+| `-y, --yes`            | Accept the defaults without prompting.                                                                                                                                                                                                 |
+
+## What you get
+
+- A Vite + React project with `@kaptive/cli`'s plugin already wired up.
+- `kaptive.manifest.json`, declaring the parameters your widget needs.
+- `kaptive.dev.json`, standing in for a real player while you run `npm run dev`.
+- A generated, always-up-to-date `src/kaptive-env.d.ts`, so `parameters.yourKey` is typed straight from the manifest.
+
+## Next steps
+
+```bash
+cd my-widget
+npm install
+npm run dev
+```
+
+Edit `kaptive.manifest.json` to declare parameters — `text`, `number`, `boolean`, `color`, and `asset` are the available types, each becoming a field in the widget's properties panel in the Kaptive editor. Edit `kaptive.dev.json` to try out values while you develop; there's no live editor to ask, so the dev server reads from that file and reloads when it changes.
+
+When you're ready to ship:
+
+```bash
+npm run build
+```
+
+produces `<id>-<version>.zip`. Hand it to a workspace admin, who uploads it under **Settings → Widgets** — from then on, anyone in the workspace can drop it into a project. Bump `version` in the manifest before each upload; Kaptive rejects a bundle declaring a version it already has.
+
+See the scaffolded project's own README for the full parameter reference and what `kaptive.ready()` gives your widget at runtime, or the [`@kaptive/widget-api`](https://www.npmjs.com/package/@kaptive/widget-api) and [`@kaptive/cli`](https://www.npmjs.com/package/@kaptive/cli) packages it depends on.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { stdin, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { WIDGET_MANIFEST_FILENAME, parseWidgetManifest, widgetIdSchema } from "@kaptive/widget-api/manifest";
+import { createInterface } from "node:readline/promises";
+//#region src/scaffold.ts
+/**
+* React is the only framework for now. The list is what the prompt renders, so
+* adding another one is a matter of dropping in a template directory and an
+* entry here.
+*/
+var FRAMEWORKS = [{
+	id: "react",
+	label: "React",
+	template: "react"
+}];
+/**
+* Template files whose name cannot ship as-is: npm strips `.gitignore` from
+* published packages, and a leading dot invites tooling to treat the file as
+* configuration for the CLI package itself.
+*/
+var RENAMES = { _gitignore: ".gitignore" };
+/** Derives a valid widget id from a display name. */
+function slugifyWidgetId(input) {
+	return input.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64).replace(/-+$/, "");
+}
+function isValidWidgetId(id) {
+	return widgetIdSchema.safeParse(id).success;
+}
+/** Derives an npm-safe package name from a display name. */
+function toPackageName(input) {
+	return slugifyWidgetId(input) || "kaptive-widget";
+}
+/**
+* Substitutes `{{token}}` placeholders. Values going into a `.json` file are
+* JSON-escaped, so a widget name containing a quote produces a valid manifest
+* rather than a broken one.
+*/
+function applyReplacements(content, values, asJson) {
+	const escape = (value) => asJson ? JSON.stringify(value).slice(1, -1) : value;
+	return content.replace(/\{\{(name|id|description|packageName)\}\}/g, (_, key) => escape(values[key]));
+}
+/** True when `directory` does not exist, or exists and holds nothing. */
+async function isDirectoryEmpty(directory) {
+	try {
+		return (await readdir(directory)).length === 0;
+	} catch {
+		return true;
+	}
+}
+/** Copies a template into `targetDir`, substituting placeholders as it goes. */
+async function scaffold(options) {
+	const written = [];
+	async function copyDirectory(from, to) {
+		await mkdir(to, { recursive: true });
+		for (const entry of await readdir(from, { withFileTypes: true })) {
+			const source = path.join(from, entry.name);
+			const name = RENAMES[entry.name] ?? entry.name;
+			const destination = path.join(to, name);
+			if (entry.isDirectory()) {
+				await copyDirectory(source, destination);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			const content = await readFile(source, "utf8");
+			await writeFile(destination, applyReplacements(content, options.values, name.endsWith(".json")), "utf8");
+			written.push(path.relative(options.targetDir, destination));
+		}
+	}
+	await copyDirectory(options.templateDir, options.targetDir);
+	const manifestFile = path.join(options.targetDir, WIDGET_MANIFEST_FILENAME);
+	const result = parseWidgetManifest(JSON.parse(await readFile(manifestFile, "utf8")));
+	if (!result.ok) throw new Error(`Generated ${WIDGET_MANIFEST_FILENAME} is invalid:\n  ${result.errors.join("\n  ")}`);
+	return written.sort();
+}
+//#endregion
+//#region src/prompts.ts
+function createPrompter(interactive) {
+	if (!interactive) return {
+		ask: (_q, fallback) => Promise.resolve(fallback),
+		close: () => {}
+	};
+	const rl = createInterface({
+		input: stdin,
+		output: stdout
+	});
+	return {
+		async ask(question, fallback) {
+			return (await rl.question(`${question} (${fallback}) `)).trim() || fallback;
+		},
+		close: () => {
+			rl.close();
+		}
+	};
+}
+async function pickFramework(prompter, interactive, requested) {
+	if (requested) {
+		const match = FRAMEWORKS.find((framework) => framework.id === requested);
+		if (!match) throw new Error(`Unknown framework "${requested}". Available: ${FRAMEWORKS.map((f) => f.id).join(", ")}`);
+		return match;
+	}
+	const first = FRAMEWORKS[0];
+	if (!first) throw new Error("No widget templates are available");
+	if (FRAMEWORKS.length === 1 || !interactive) return first;
+	const options = FRAMEWORKS.map((framework, index) => `  ${index + 1}) ${framework.label}`).join("\n");
+	console.log(`\nFramework:\n${options}`);
+	for (;;) {
+		const answer = await prompter.ask("Choose a framework", first.id);
+		const match = FRAMEWORKS[Number(answer) - 1] ?? FRAMEWORKS.find((framework) => framework.id === answer.trim().toLowerCase());
+		if (match) return match;
+		console.log(`  "${answer}" is not one of the options.`);
+	}
+}
+/**
+* A non-interactive prompter always echoes the same fallback back, so a
+* validating retry loop over it would spin forever on an invalid fallback —
+* most commonly a suggested id slugified down to under 3 characters from a
+* short `--name`. Non-interactive mode therefore gets exactly one try.
+*/
+async function askWidgetId(prompter, interactive, provided, suggestion) {
+	if (provided) {
+		if (!isValidWidgetId(provided)) throw new Error(`"${provided}" is not a valid widget id: use 3-64 lowercase letters, digits or dashes, starting with a letter or digit.`);
+		return provided;
+	}
+	if (!interactive) {
+		if (isValidWidgetId(suggestion)) return suggestion;
+		throw new Error(`Could not derive a valid widget id from "${suggestion}" — pass --id explicitly (3-64 lowercase letters, digits or dashes, starting with a letter or digit).`);
+	}
+	for (;;) {
+		const answer = await prompter.ask("Widget id", suggestion);
+		if (isValidWidgetId(answer)) return answer;
+		console.log("  Use 3-64 lowercase letters, digits or dashes, starting with a letter or digit.");
+	}
+}
+//#endregion
+//#region src/index.ts
+var DEFAULT_DIRECTORY = "my-kaptive-widget";
+/** Turns a directory name into a plausible display name. */
+function titleFromDirectory(directory) {
+	const words = path.basename(path.resolve(directory)).replace(/[-_]+/g, " ").trim();
+	return words ? words.charAt(0).toUpperCase() + words.slice(1) : "My widget";
+}
+async function run(directory, opts) {
+	const interactive = Boolean(stdin.isTTY) && !opts.yes;
+	const prompter = createPrompter(interactive);
+	try {
+		console.log("\nCreating a Kaptive widget.\n");
+		const targetDirectory = directory ?? await prompter.ask("Project directory", DEFAULT_DIRECTORY);
+		const targetDir = path.resolve(targetDirectory);
+		if (!await isDirectoryEmpty(targetDir)) throw new Error(`${targetDir} already exists and is not empty.`);
+		const name = opts.name ?? await prompter.ask("Widget name", titleFromDirectory(targetDirectory));
+		const id = await askWidgetId(prompter, interactive, opts.id, slugifyWidgetId(name) || slugifyWidgetId(path.basename(targetDir)));
+		const description = opts.description ?? await prompter.ask("Description", `${name} widget for Kaptive`);
+		const framework = await pickFramework(prompter, interactive, opts.framework);
+		const written = await scaffold({
+			targetDir,
+			templateDir: path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "templates", framework.template),
+			values: {
+				name,
+				id,
+				description,
+				packageName: toPackageName(name)
+			}
+		});
+		const relative = path.relative(process.cwd(), targetDir) || ".";
+		console.log(`\nCreated ${written.length} files in ${relative}\n\nNext steps:\n  cd ${relative}\n  npm install\n  npm run dev\n\nEdit kaptive.manifest.json to declare the parameters your widget needs,\nand kaptive.dev.json to set their values while you develop.\n\nWhen you are ready, "npm run build" produces ${id}-0.1.0.zip for a\nworkspace admin to upload under Settings → Widgets.\n`);
+	} finally {
+		prompter.close();
+	}
+}
+var program = new Command("create-widget").description("Scaffold a Kaptive custom widget").argument("[directory]", "Directory to create the widget in").option("--name <name>", "Display name shown in the Kaptive editor").option("--id <id>", "Stable widget id (lowercase letters, digits, dashes)").option("--description <text>", "One-line description").option("--framework <id>", `Widget framework: ${FRAMEWORKS.map((f) => f.id).join(", ")}`).option("-y, --yes", "Accept the defaults without prompting").action(run);
+try {
+	await program.parseAsync(process.argv);
+} catch (error) {
+	console.error(`\n${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
+//#endregion
+export {};

package/dist/prompts.d.ts

@@ -0,0 +1,14 @@
+import { type Framework } from "./scaffold.js";
+export interface Prompter {
+    ask: (question: string, fallback: string) => Promise<string>;
+    close: () => void;
+}
+export declare function createPrompter(interactive: boolean): Prompter;
+export declare function pickFramework(prompter: Prompter, interactive: boolean, requested: string | undefined): Promise<Framework>;
+/**
+ * A non-interactive prompter always echoes the same fallback back, so a
+ * validating retry loop over it would spin forever on an invalid fallback —
+ * most commonly a suggested id slugified down to under 3 characters from a
+ * short `--name`. Non-interactive mode therefore gets exactly one try.
+ */
+export declare function askWidgetId(prompter: Prompter, interactive: boolean, provided: string | undefined, suggestion: string): Promise<string>;

package/dist/scaffold.d.ts

@@ -0,0 +1,38 @@
+export interface Framework {
+    id: string;
+    label: string;
+    /** Directory under `templates/`. */
+    template: string;
+}
+/**
+ * React is the only framework for now. The list is what the prompt renders, so
+ * adding another one is a matter of dropping in a template directory and an
+ * entry here.
+ */
+export declare const FRAMEWORKS: readonly Framework[];
+export interface TemplateValues {
+    name: string;
+    id: string;
+    description: string;
+    packageName: string;
+}
+/** Derives a valid widget id from a display name. */
+export declare function slugifyWidgetId(input: string): string;
+export declare function isValidWidgetId(id: string): boolean;
+/** Derives an npm-safe package name from a display name. */
+export declare function toPackageName(input: string): string;
+/**
+ * Substitutes `{{token}}` placeholders. Values going into a `.json` file are
+ * JSON-escaped, so a widget name containing a quote produces a valid manifest
+ * rather than a broken one.
+ */
+export declare function applyReplacements(content: string, values: TemplateValues, asJson: boolean): string;
+/** True when `directory` does not exist, or exists and holds nothing. */
+export declare function isDirectoryEmpty(directory: string): Promise<boolean>;
+export interface ScaffoldOptions {
+    targetDir: string;
+    templateDir: string;
+    values: TemplateValues;
+}
+/** Copies a template into `targetDir`, substituting placeholders as it goes. */
+export declare function scaffold(options: ScaffoldOptions): Promise<string[]>;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kaptive/create-widget",
+  "version": "0.1.0",
+  "description": "Scaffold a Kaptive custom widget.",
+  "keywords": [
+    "kaptive",
+    "widget",
+    "scaffold",
+    "create",
+    "digital-signage"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://kaptive.ch",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "bin": {
+    "create-kaptive-widget": "./dist/index.js",
+    "create-widget": "./dist/index.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "@kaptive/widget-api": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "^10.0.0",
+    "prettier": "^3.8.1",
+    "typescript": "6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "lint": "eslint . --max-warnings 0 --cache --cache-location node_modules/.cache/eslint/",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/templates/react/README.md

@@ -0,0 +1,66 @@
+# {{name}}
+
+A custom widget for [Kaptive](https://kaptive.app).
+
+## Get started
+
+```bash
+npm install
+npm run dev
+```
+
+## Parameters
+
+Declare whatever your widget needs in `kaptive.manifest.json`:
+
+```json
+{ "key": "title", "type": "text", "label": "Title", "default": "Hello" }
+```
+
+Types are `text`, `number`, `boolean`, `color` and `asset`. Each one turns into
+a field in the widget's properties panel in the Kaptive editor, and it is typed
+in your code — `parameters.title` is a `string`, `parameters.count` is a
+`number`. The types are generated from the manifest, so you never write them
+yourself.
+
+A `color` arrives as a hex string. An `asset` lets someone pick a file — from
+the workspace media library, or one sitting on the player's own storage — and
+arrives as a URL you can drop into an `<img>`, or `null` if nothing is picked
+yet. `accept` narrows which library categories are offered (`image`, `video`,
+`pdf`, `model`):
+
+```json
+{ "key": "logo", "type": "asset", "label": "Logo", "accept": ["image"] }
+```
+
+There is no editor while you develop, so values come from `kaptive.dev.json`.
+Edit that file and the page reloads. Point an asset parameter at any URL there
+— a file in `public/`, or a remote one — or simulate a file on a real player's
+own storage with `{ "source": "local", "localFilePath": "..." }`.
+
+## Ship it
+
+```bash
+npm run build
+```
+
+You get `{{id}}-<version>.zip`. Hand it to a workspace admin, who uploads it
+under **Settings → Widgets** — from then on anyone can drop it into a project.
+
+Bump `version` in the manifest before each upload; Kaptive rejects a bundle
+declaring a version it already has. Uploading replaces the widget on every
+screen using it, within seconds.
+
+## Good to know
+
+- Your widget is transparent and gets resized freely in the editor. Looking
+  right at any size is up to you.
+- `kaptive.ready()` also gives you `player` (device name, orientation, time
+  zone, resolution) and `block` (your size in pixels).
+- `fetch` and `localStorage` work as usual. Your widget runs on its own origin,
+  so anything you store stays yours and survives updates and reboots.
+- Parameters are read once at start-up. If someone changes one, the widget
+  restarts with the new values.
+- Your widget also works deployed outside Kaptive entirely. Add a
+  `kaptive.prod.json` (same shape as `kaptive.dev.json`) to bake in real
+  values for that case; without one, it falls back to the manifest's defaults.

package/templates/react/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+
+# Generated from kaptive.manifest.json on every dev/build/check-types run.
+src/kaptive-env.d.ts
+
+# Packaged bundles
+*.zip

package/templates/react/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react/kaptive.dev.json

@@ -0,0 +1,12 @@
+{
+  "parameters": {
+    "title": "{{name}}",
+    "count": 42
+  },
+  "player": {
+    "deviceName": "My Development screen",
+    "timezone": "Europe/Zurich",
+    "orientation": 0,
+    "resolution": { "width": 1920, "height": 1080 }
+  }
+}

package/templates/react/kaptive.manifest.json

@@ -0,0 +1,23 @@
+{
+  "id": "{{id}}",
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "description": "{{description}}",
+  "entry": "index.html",
+  "parameters": [
+    {
+      "key": "title",
+      "type": "text",
+      "label": "Title",
+      "default": "{{name}}",
+      "maxLength": 60
+    },
+    {
+      "key": "count",
+      "type": "number",
+      "label": "Count",
+      "default": 0
+    }
+  ]
+}

package/templates/react/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "kaptive widget dev",
+    "build": "kaptive widget build",
+    "validate": "kaptive widget validate",
+    "check-types": "kaptive widget types && tsc --noEmit"
+  },
+  "dependencies": {
+    "@kaptive/widget-api": "^0.1.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@kaptive/cli": "^0.1.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.1"
+  }
+}

package/templates/react/src/App.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useState } from "react";
+import { kaptive, type KaptiveParameters } from "@kaptive/widget-api";
+
+export function App() {
+  const [parameters, setParameters] = useState<KaptiveParameters | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let active = true;
+
+    // The values someone set in the Kaptive editor, typed from your manifest.
+    kaptive
+      .ready()
+      .then((context) => {
+        if (active) setParameters(context.parameters);
+      })
+      .catch((cause: unknown) => {
+        if (active) {
+          setError(cause instanceof Error ? cause.message : String(cause));
+        }
+      });
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  if (error) return <main className="widget message">{error}</main>;
+  if (!parameters) return <main className="widget message">Loading…</main>;
+
+  return (
+    <main className="widget">
+      <h1>{parameters.title}</h1>
+      <p>{parameters.count}</p>
+    </main>
+  );
+}

package/templates/react/src/app.css

@@ -0,0 +1,43 @@
+/* No background, so the widget sits on the project's own. Add one if you want. */
+html,
+body,
+#root {
+  margin: 0;
+  height: 100%;
+  overflow: hidden;
+  background: transparent;
+}
+
+.widget {
+  box-sizing: border-box;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 0.2em;
+
+  font-family:
+    system-ui,
+    -apple-system,
+    "Segoe UI",
+    sans-serif;
+  color: #111827;
+}
+
+/* Viewport units, so the text reads well at whatever size the block is. */
+.widget h1 {
+  margin: 0;
+  font-size: clamp(1rem, 9vh, 6rem);
+  line-height: 1.1;
+}
+
+.widget p {
+  margin: 0;
+  font-size: clamp(0.875rem, 5vh, 3rem);
+  opacity: 0.6;
+}
+
+.widget.message {
+  font-size: 0.875rem;
+  opacity: 0.7;
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "./app.css";
+
+const container = document.getElementById("root");
+if (!container) throw new Error("Missing #root element in index.html");
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/react/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { kaptiveWidget } from "@kaptive/cli";
+
+export default defineConfig({
+  // Keeps asset paths relative — each widget is served from its own origin root.
+  base: "./",
+  plugins: [react(), kaptiveWidget()],
+});