@bridgeline-digital/hawk-app-cli 0.0.0-stage → 0.1.0-dev.20261020205204

package/templates/next/src/app/page.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { HawkApiError, type AnalyticsReportRow } from '@bridgeline-digital/hawk-app-bridge/client';
+// The UI kit's elements (<hawk-kpi>, <hawk-column-chart>, …): defined in the browser, safe to import on the server.
+import { createFormat } from '@bridgeline-digital/hawk-app-ui/elements';
+import { useEffect, useMemo, useState } from 'react';
+import { useHawkApp } from '@/lib/useHawkApp';
+
+/**
+ * Starter screen: the context from the host and one real data call, shown with the UI kit (Spark's look: the kit's
+ * stylesheet and its elements, <hawk-kpi> and <hawk-column-chart>). Replace it with your app. Data comes only through
+ * the bridge: no API keys in the app.
+ */
+export default function Page() {
+    const hawk = useHawkApp();
+    const [rows, setRows] = useState<AnalyticsReportRow<'searches'>[] | null>(null);
+    const [error, setError] = useState<string | null>(null);
+
+    const app = hawk.status === 'ready' ? hawk.app : undefined;
+    const context = hawk.status === 'ready' ? hawk.context : undefined;
+    const format = useMemo(() => createFormat(context?.locale), [context?.locale]);
+
+    // Reload whenever the user changes the date range or engine in the host.
+    useEffect(() => {
+        if (!app || !context) return;
+        let current = true;
+        setRows(null);
+        setError(null);
+        const filters = context.engine ? [{ member: 'engine_id' as const, operator: 'equals', values: [context.engine.id] }] : undefined;
+        app.analytics
+            .report('searches', { filters, limit: 1000 }) // dates default to the host's date range
+            .then((report) => current && setRows(report.data))
+            .catch((e: unknown) => current && setError(e instanceof HawkApiError ? `${e.message}${e.code ? ` (${e.code})` : ''}` : String(e)));
+        return () => {
+            current = false;
+        };
+    }, [app, context?.dateRange?.from, context?.dateRange?.to, context?.engine?.id]);
+
+    // One column per day (a day can have a row per engine).
+    const days = useMemo(() => {
+        const byDay = new Map<string, number>();
+        for (const row of rows ?? []) byDay.set(row.search_date, (byDay.get(row.search_date) ?? 0) + row.search_count);
+        return [...byDay].sort(([a], [b]) => a.localeCompare(b)).map(([date, value]) => ({ label: format.date(date, { year: false }), value }));
+    }, [rows, format]);
+
+    if (hawk.status === 'connecting') return <span className="hawk-spinner" aria-label="Connecting" />;
+    if (hawk.status === 'error') return <div className="hawk-notice is-error">{hawk.message}</div>;
+
+    const total = days.reduce((sum, d) => sum + d.value, 0);
+    const { tenant, engine, dateRange } = hawk.context;
+    return (
+        <main className="hawk-stack">
+            <div>
+                <h1>__NAME__</h1>
+                <p className="hawk-muted">
+                    Client {tenant.clientId}
+                    {engine ? ` · ${engine.name ?? `Engine ${engine.id}`}` : ''}
+                    {dateRange ? ` · ${format.date(dateRange.from)} – ${format.date(dateRange.to)}` : ''}
+                </p>
+            </div>
+
+            {error && <div className="hawk-notice is-error">{error}</div>}
+
+            <div className="hawk-kpi-row">
+                <hawk-kpi label="Searches" value={rows ? format.integer(total) : ''} loading={rows ? undefined : ''} highlight="" />
+                <hawk-kpi label="Searches per day" value={rows ? format.integer(days.length ? total / days.length : 0) : ''} loading={rows ? undefined : ''} hint={rows ? `over ${days.length} days` : undefined} />
+            </div>
+
+            <section className="hawk-section">
+                <div className="hawk-section-header">
+                    <div>
+                        <h2 className="hawk-section-title">Searches per day</h2>
+                        <p className="hawk-section-subtitle">In the host&apos;s date range. Hover a column for its number.</p>
+                    </div>
+                </div>
+                {rows ? <hawk-column-chart label="Searches per day" value-format="integer" columns={days} /> : <span className="hawk-spinner" />}
+            </section>
+
+            <div>
+                <button className="hawk-button" onClick={() => hawk.app.toast('Hello from __NAME__!', 'success')}>
+                    Say hello
+                </button>
+            </div>
+        </main>
+    );
+}

package/templates/next/src/hawk-elements.d.ts

@@ -0,0 +1,10 @@
+// The UI kit's custom elements in JSX (<hawk-kpi>, <hawk-data-table>, <hawk-bar-list>, <hawk-column-chart>).
+import type { HawkElementTags } from '@bridgeline-digital/hawk-app-ui/elements';
+
+declare module 'react' {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace JSX {
+        // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        interface IntrinsicElements extends HawkElementTags {}
+    }
+}

package/templates/next/src/lib/useHawkApp.ts

@@ -0,0 +1,46 @@
+'use client';
+
+import { createApp, type HawkApp, type HawkAppContext } from '@bridgeline-digital/hawk-app-bridge/client';
+import { useEffect, useState } from 'react';
+
+/** Shown when the app is opened directly instead of inside a host. */
+function notEmbeddedMessage(): string {
+    return `Open this app from the Apps page in HawkSearch. Developing locally? Add ?devUrl=${window.location.href} to the app's address in HawkSearch.`;
+}
+
+export type HawkAppState =
+    | { status: 'connecting' }
+    | { status: 'ready'; app: HawkApp; context: HawkAppContext }
+    | { status: 'error'; message: string };
+
+/** Connects to the host (the HawkSearch dashboard / Spark) once and keeps the context (client, engine, dates, theme) current. */
+export function useHawkApp(): HawkAppState {
+    const [state, setState] = useState<HawkAppState>({ status: 'connecting' });
+
+    useEffect(() => {
+        let app: HawkApp | undefined;
+        let cancelled = false;
+
+        createApp({ autoResize: true })
+            .then((connected) => {
+                if (cancelled) return connected.destroy();
+                app = connected;
+                setState({ status: 'ready', app: connected, context: connected.context });
+                connected.onContextChange((context) => setState({ status: 'ready', app: connected, context }));
+            })
+            .catch((error: { code?: string; message?: string }) => {
+                if (cancelled) return;
+                setState({
+                    status: 'error',
+                    message: error.code === 'not_embedded' ? notEmbeddedMessage() : `Could not connect to the host: ${error.message}`,
+                });
+            });
+
+        return () => {
+            cancelled = true;
+            app?.destroy();
+        };
+    }, []);
+
+    return state;
+}

package/templates/next/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/next-mui/next.config.ts

@@ -0,0 +1,13 @@
+import type { NextConfig } from 'next';
+
+// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server
+// features (no SSR, API routes or middleware). All data comes through the bridge.
+// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.
+const nextConfig: NextConfig = {
+    output: 'export',
+    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',
+    trailingSlash: true,
+    images: { unoptimized: true },
+};
+
+export default nextConfig;

package/templates/next-mui/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3100",
+    "build": "next build",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "dependencies": {
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^9.5.0",
+    "@mui/material": "^9.5.0",
+    "@mui/material-nextjs": "^9.5.0",
+    "next": "^16.4.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "@types/node": "^20",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/next-mui/src/app/layout.tsx

@@ -0,0 +1,20 @@
+// Montserrat, Spark's font, bundled with the app (no request to Google Fonts at build or run time).
+import '@bridgeline-digital/hawk-app-ui/fonts';
+import { AppRouterCacheProvider } from '@mui/material-nextjs/v16-appRouter';
+import type { Metadata } from 'next';
+import Providers from './providers';
+
+export const metadata: Metadata = { title: '__NAME__' };
+
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+    return (
+        <html lang="en">
+            <body>
+                {/* Puts MUI's styles into the exported HTML, so the page doesn't flash unstyled. */}
+                <AppRouterCacheProvider>
+                    <Providers>{children}</Providers>
+                </AppRouterCacheProvider>
+            </body>
+        </html>
+    );
+}

package/templates/next-mui/src/app/page.tsx

@@ -0,0 +1,79 @@
+'use client';
+
+import { HawkApiError } from '@bridgeline-digital/hawk-app-bridge/client';
+import { KpiRow, KpiTile, LoadingSection, Notice, Section, useFormat, useHawk, useToast } from '@bridgeline-digital/hawk-app-ui';
+import { ColumnChart } from '@bridgeline-digital/hawk-app-ui/charts';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { useEffect, useState } from 'react';
+
+interface SearchesRow {
+    search_date: string;
+    search_count: number | string;
+}
+
+/**
+ * Starter screen: the context from the host and one real data call, with the UI kit's components.
+ * Replace it with your app. Data comes only through the bridge: no API keys in the app.
+ */
+export default function Page() {
+    const { app, context } = useHawk();
+    const format = useFormat();
+    const toast = useToast();
+    const [rows, setRows] = useState<SearchesRow[] | null>(null);
+    const [error, setError] = useState<string | null>(null);
+    const [attempt, setAttempt] = useState(0);
+
+    // Reload whenever the user changes the date range or engine in the host.
+    useEffect(() => {
+        let current = true;
+        setRows(null);
+        setError(null);
+        const filters = context.engine ? [{ member: 'engine_id', operator: 'equals', values: [context.engine.id] }] : undefined;
+        app.analytics
+            .report<SearchesRow>('searches', { filters, limit: 1000 }) // dates default to the host's date range
+            .then((report) => current && setRows(report.data))
+            .catch((e: unknown) => current && setError(e instanceof HawkApiError ? `${e.message}${e.code ? ` (${e.code})` : ''}` : String(e)));
+        return () => {
+            current = false;
+        };
+    }, [app, context.dateRange?.from, context.dateRange?.to, context.engine?.id, attempt]);
+
+    const { tenant, engine, dateRange } = context;
+    const days = (rows ?? []).map((r) => ({ label: format.date(r.search_date.slice(0, 10), { year: false }), value: Number(r.search_count) || 0 }));
+    const total = days.reduce((sum, d) => sum + d.value, 0);
+    return (
+        <Stack component="main" spacing={2} sx={{ p: 2 }}>
+            {/* No page heading: the host already shows the app's name above the frame. */}
+            <Typography variant="body2" color="text.secondary">
+                Client {tenant.clientId}
+                {engine ? ` · ${engine.name ?? `Engine ${engine.id}`}` : ''}
+                {dateRange ? ` · ${format.date(dateRange.from.slice(0, 10))} – ${format.date(dateRange.to.slice(0, 10))}` : ''}
+            </Typography>
+
+            {error ? (
+                <Notice severity="error" onRetry={() => setAttempt((n) => n + 1)}>
+                    {error}
+                </Notice>
+            ) : !rows ? (
+                <LoadingSection title="Searches" height={160} />
+            ) : (
+                <>
+                    <KpiRow columns={3}>
+                        <KpiTile highlight label="Searches" value={format.integer(total)} />
+                        <KpiTile label="Days" value={format.integer(days.length)} />
+                        <KpiTile label="Per day" value={format.integer(days.length ? total / days.length : 0)} />
+                    </KpiRow>
+                    <Section title="Searches per day">
+                        <ColumnChart label="Searches per day" columns={days} format={format.integer} />
+                    </Section>
+                </>
+            )}
+
+            <Button variant="contained" onClick={() => toast('Hello from __NAME__!', 'success')}>
+                Say hello
+            </Button>
+        </Stack>
+    );
+}

package/templates/next-mui/src/app/providers.tsx

@@ -0,0 +1,11 @@
+'use client';
+
+import { HawkAppProvider } from '@bridgeline-digital/hawk-app-ui';
+
+/**
+ * Connects to the host (HawkSearch or Spark) and shows the app in Spark's theme, in the host's colors and mode. Until it
+ * has connected it shows a spinner, and outside a host it says how to open the app. Pages read the app with useHawk().
+ */
+export default function Providers({ children }: Readonly<{ children: React.ReactNode }>) {
+    return <HawkAppProvider>{children}</HawkAppProvider>;
+}

package/templates/next-mui/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/preact/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/preact/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "dependencies": {
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "preact": "^11.0.0"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "@types/node": "^20",
+    "@preact/preset-vite": "^2.10.6",
+    "typescript": "^5.6.0",
+    "vite": "^8.0.0"
+  }
+}

package/templates/preact/src/App.tsx

@@ -0,0 +1,83 @@
+import { HawkApiError, type AnalyticsReportRow } from '@bridgeline-digital/hawk-app-bridge/client';
+import { createFormat } from '@bridgeline-digital/hawk-app-ui/elements';
+import { useEffect, useMemo, useState } from 'preact/hooks';
+import { useHawkApp } from './useHawkApp';
+
+/**
+ * Starter screen: the context from the host and one real data call, shown with the UI kit (Spark's look: the kit's
+ * stylesheet and its elements, <hawk-kpi> and <hawk-column-chart>). Replace it with your app. Data comes only through
+ * the bridge: no API keys in the app.
+ */
+export function App() {
+    const hawk = useHawkApp();
+    const [rows, setRows] = useState<AnalyticsReportRow<'searches'>[] | null>(null);
+    const [error, setError] = useState<string | null>(null);
+
+    const app = hawk.status === 'ready' ? hawk.app : undefined;
+    const context = hawk.status === 'ready' ? hawk.context : undefined;
+    const format = useMemo(() => createFormat(context?.locale), [context?.locale]);
+
+    // Reload whenever the user changes the date range or engine in the host.
+    useEffect(() => {
+        if (!app || !context) return;
+        let current = true;
+        setRows(null);
+        setError(null);
+        const filters = context.engine ? [{ member: 'engine_id' as const, operator: 'equals', values: [context.engine.id] }] : undefined;
+        app.analytics
+            .report('searches', { filters, limit: 1000 }) // dates default to the host's date range
+            .then((report) => current && setRows(report.data))
+            .catch((e: unknown) => current && setError(e instanceof HawkApiError ? `${e.message}${e.code ? ` (${e.code})` : ''}` : String(e)));
+        return () => {
+            current = false;
+        };
+    }, [app, context?.dateRange?.from, context?.dateRange?.to, context?.engine?.id]);
+
+    // One column per day (a day can have a row per engine).
+    const days = useMemo(() => {
+        const byDay = new Map<string, number>();
+        for (const row of rows ?? []) byDay.set(row.search_date, (byDay.get(row.search_date) ?? 0) + row.search_count);
+        return [...byDay].sort(([a], [b]) => a.localeCompare(b)).map(([date, value]) => ({ label: format.date(date, { year: false }), value }));
+    }, [rows, format]);
+
+    if (hawk.status === 'connecting') return <span className="hawk-spinner" aria-label="Connecting" />;
+    if (hawk.status === 'error') return <div className="hawk-notice is-error">{hawk.message}</div>;
+
+    const total = days.reduce((sum, d) => sum + d.value, 0);
+    const { tenant, engine, dateRange } = hawk.context;
+    return (
+        <main className="hawk-stack">
+            <div>
+                <h1>__NAME__</h1>
+                <p className="hawk-muted">
+                    Client {tenant.clientId}
+                    {engine ? ` · ${engine.name ?? `Engine ${engine.id}`}` : ''}
+                    {dateRange ? ` · ${format.date(dateRange.from)} – ${format.date(dateRange.to)}` : ''}
+                </p>
+            </div>
+
+            {error && <div className="hawk-notice is-error">{error}</div>}
+
+            <div className="hawk-kpi-row">
+                <hawk-kpi label="Searches" value={rows ? format.integer(total) : ''} loading={rows ? undefined : ''} highlight="" />
+                <hawk-kpi label="Searches per day" value={rows ? format.integer(days.length ? total / days.length : 0) : ''} loading={rows ? undefined : ''} hint={rows ? `over ${days.length} days` : undefined} />
+            </div>
+
+            <section className="hawk-section">
+                <div className="hawk-section-header">
+                    <div>
+                        <h2 className="hawk-section-title">Searches per day</h2>
+                        <p className="hawk-section-subtitle">In the host&apos;s date range. Hover a column for its number.</p>
+                    </div>
+                </div>
+                {rows ? <hawk-column-chart label="Searches per day" value-format="integer" columns={days} /> : <span className="hawk-spinner" />}
+            </section>
+
+            <div>
+                <button className="hawk-button" onClick={() => hawk.app.toast('Hello from __NAME__!', 'success')}>
+                    Say hello
+                </button>
+            </div>
+        </main>
+    );
+}

package/templates/preact/src/hawk-elements.d.ts

@@ -0,0 +1,10 @@
+// The UI kit's custom elements in JSX (<hawk-kpi>, <hawk-data-table>, <hawk-bar-list>, <hawk-column-chart>).
+import type { HawkElementTags } from '@bridgeline-digital/hawk-app-ui/elements';
+
+declare module 'preact' {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace JSX {
+        // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        interface IntrinsicElements extends HawkElementTags {}
+    }
+}

package/templates/preact/src/main.tsx

@@ -0,0 +1,8 @@
+import { render } from 'preact';
+// The UI kit: Spark's look (stylesheet, with Montserrat) and its elements (<hawk-kpi>, <hawk-data-table>, …).
+import '@bridgeline-digital/hawk-app-ui/css';
+import '@bridgeline-digital/hawk-app-ui/elements';
+import { App } from './App';
+import './styles.css';
+
+render(<App />, document.getElementById('root')!);

package/templates/preact/src/styles.css

@@ -0,0 +1,5 @@
+/*
+ * Your app's own styles. Spark's look comes from the UI kit's stylesheet (imported in main.tsx): its hawk-* classes
+ * (hawk-section, hawk-button, hawk-notice, hawk-table, …) and --hawk-ui-* variables, which follow the host's colors
+ * and light or dark mode. Use those before adding your own.
+ */

package/templates/preact/src/useHawkApp.ts

@@ -0,0 +1,44 @@
+import { createApp, type HawkApp, type HawkAppContext } from '@bridgeline-digital/hawk-app-bridge/client';
+import { useEffect, useState } from 'preact/hooks';
+
+/** Shown when the app is opened directly instead of inside a host. */
+function notEmbeddedMessage(): string {
+    return `Open this app from the Apps page in HawkSearch. Developing locally? Add ?devUrl=${window.location.href} to the app's address in HawkSearch.`;
+}
+
+export type HawkAppState =
+    | { status: 'connecting' }
+    | { status: 'ready'; app: HawkApp; context: HawkAppContext }
+    | { status: 'error'; message: string };
+
+/** Connects to the host (the HawkSearch dashboard / Spark) once and keeps the context (client, engine, dates, theme) current. */
+export function useHawkApp(): HawkAppState {
+    const [state, setState] = useState<HawkAppState>({ status: 'connecting' });
+
+    useEffect(() => {
+        let app: HawkApp | undefined;
+        let cancelled = false;
+
+        createApp({ autoResize: true })
+            .then((connected) => {
+                if (cancelled) return connected.destroy();
+                app = connected;
+                setState({ status: 'ready', app: connected, context: connected.context });
+                connected.onContextChange((context) => setState({ status: 'ready', app: connected, context }));
+            })
+            .catch((error: { code?: string; message?: string }) => {
+                if (cancelled) return;
+                setState({
+                    status: 'error',
+                    message: error.code === 'not_embedded' ? notEmbeddedMessage() : `Could not connect to the host: ${error.message}`,
+                });
+            });
+
+        return () => {
+            cancelled = true;
+            app?.destroy();
+        };
+    }, []);
+
+    return state;
+}

package/templates/preact/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/preact/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "strict": true,
+    "noUnusedLocals": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/preact/vite.config.ts

@@ -0,0 +1,11 @@
+import preact from '@preact/preset-vite';
+import { defineConfig } from 'vite';
+
+// Each deploy is served from the apps CDN at /<slug>/v<n>/, so every asset URL needs that prefix.
+// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>/.
+export default defineConfig({
+    base: `${process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'}/`,
+    plugins: [preact()],
+    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (HawkSearch dev mode, ?devUrl=).
+    server: { port: 3100, strictPort: true },
+});

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/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "dependencies": {
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "@types/node": "^20",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^8.0.0"
+  }
+}