convex-cms 0.0.11-alpha.3 → 0.0.15

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/convex-cms.svg)](https://www.npmjs.com/package/convex-cms)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-> **Alpha (v0.0.10)** Actively developed. APIs & docs may change. [Report issues](https://github.com/obkaro/convex-cms/issues).
+> **Alpha** Actively developed. APIs & docs may change. [Report issues](https://github.com/obkaro/convex-cms/issues).
 
 A headless CMS built as a [Convex Component](https://docs.convex.dev/components). Content management that runs inside your Convex app.
 
@@ -34,7 +34,15 @@ export default app;
 
 ### 3. Initialize
 
-**For Admin UI:** Run `pnpm convex-cms init` then `pnpm convex-cms admin`
+```bash
+pnpm convex-cms init --template blog
+```
+
+This generates 3 files (`convex/cms.ts`, `convex/admin.ts`, `convex/content.ts`) and updates `convex/convex.config.ts`.
+
+**Available templates:** `blog`, `docs`, `landing`, `ecommerce`, `blank`
+
+**For Admin UI:** Run `pnpm convex-cms admin` after init
 → [Full Admin UI Setup](./docs/guides/admin-ui-setup.md)
 
 **For Custom Functions:** Create a CMS client and use it in your functions

package/admin/README.md

@@ -0,0 +1,99 @@
+# Convex CMS Admin UI
+
+The Admin UI for Convex CMS, built with TanStack Start and React.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- A Convex account and project
+
+### Installation
+
+```bash
+cd admin
+pnpm install
+```
+
+### Development
+
+1. Start the Convex development server:
+
+```bash
+pnpm convex dev
+```
+
+This will generate the Convex API types and provide a `VITE_CONVEX_URL`.
+
+2. Create a `.env` file with your Convex URL:
+
+```bash
+cp .env.example .env
+# Edit .env with your VITE_CONVEX_URL from step 1
+```
+
+3. Start the development server:
+
+```bash
+pnpm dev:vite
+```
+
+Or run both Convex and Vite together:
+
+```bash
+pnpm dev
+```
+
+4. Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Project Structure
+
+```
+admin/
+├── convex/                 # Convex configuration
+│   └── convex.config.ts    # CMS component integration
+├── src/
+│   ├── routes/             # TanStack Router routes
+│   │   ├── __root.tsx      # Root layout with Convex provider
+│   │   ├── index.tsx       # Dashboard page
+│   │   ├── content.tsx     # Content entries list
+│   │   ├── media.tsx       # Media library
+│   │   ├── content-types.tsx # Content type management
+│   │   └── settings.tsx    # CMS settings
+│   ├── components/         # Reusable React components
+│   ├── lib/                # Utilities and helpers
+│   │   └── convex.ts       # Convex client utilities
+│   ├── styles/             # CSS styles
+│   │   └── app.css         # Main stylesheet
+│   └── router.tsx          # Router configuration
+├── public/                 # Static assets
+├── vite.config.ts          # Vite + TanStack Start configuration
+├── tsconfig.json           # TypeScript configuration
+└── package.json            # Dependencies and scripts
+```
+
+## Available Scripts
+
+- `pnpm dev` - Start Convex and Vite development servers
+- `pnpm dev:vite` - Start only the Vite development server
+- `pnpm dev:convex` - Start only the Convex development server
+- `pnpm build` - Build for production
+- `pnpm preview` - Preview production build
+- `pnpm typecheck` - Run TypeScript type checking
+
+## Features
+
+- **Dashboard** - Overview of CMS status and quick navigation
+- **Content Management** - Browse and manage content entries
+- **Media Library** - Upload and organize media assets
+- **Content Types** - Define content schemas with custom fields
+- **Settings** - Configure CMS features and preferences
+
+## Technology Stack
+
+- [TanStack Start](https://tanstack.com/start) - Full-stack React framework
+- [TanStack Router](https://tanstack.com/router) - Type-safe routing
+- [Convex](https://convex.dev) - Real-time backend platform
+- [React 19](https://react.dev) - UI library
+- [Vite 7](https://vitejs.dev) - Build tool

package/admin/src/components/ContentTypeFormModal.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback, useMemo, useEffect } from "react";
 import { useMutation } from "convex/react";
 import { useApi } from "~/embed/contexts/ApiContext";
-import type { FieldType, ContentType } from "convex-cms/types";
+import type { FieldType, ContentType } from "~/lib/cmsExports";
 import { CmsDialog } from "~/components/cmsds/CmsDialog";
 import { CmsButton } from "~/components/cmsds/CmsButton";
 import { Input } from "~/components/ui/input";

package/admin/src/contexts/AuthContext.tsx

@@ -39,7 +39,7 @@ import {
   type Resource,
   type Action,
   type OwnershipScope,
-} from '../../../src/component/index';
+} from '../../../src/component/roles';
 
 // =============================================================================
 // Types

package/admin/src/hooks/usePermissions.ts

@@ -30,7 +30,7 @@ import {
   type Action,
   type OwnershipScope,
   type Permission,
-} from '../../../src/component/index';
+} from '../../../src/component/roles';
 
 // =============================================================================
 // Types

package/admin/src/lib/adminApi.ts

@@ -0,0 +1,13 @@
+import type { CmsAdminApi } from "~/embed/contexts/ApiContext";
+
+const fnSymbol = Symbol.for("functionName");
+
+function createApiProxy(prefix: string): CmsAdminApi {
+	return new Proxy({} as CmsAdminApi, {
+		get(_, prop: string) {
+			return { [fnSymbol]: `${prefix}:${prop}` };
+		},
+	});
+}
+
+export const adminApi = createApiProxy("admin");

package/admin/src/lib/cmsExports.ts

@@ -1,6 +1,16 @@
-// Re-export CMS utilities that admin components need
-// Using relative imports to avoid circular dependency with convex-cms package
-export { getRole, getRolePermissions } from '../../../src/client/index';
-export type { RoleName, BaseAdminAPI } from '../../../src/client/index';
-export { useMediaUploadQueue } from '../../../src/react/index';
-export type { UploadQueueFile, UploadQueueFileStatus } from '../../../src/react/index';
+// Re-export CMS utilities that admin components need.
+// Uses published sub-path exports (not relative source paths) so this works both
+// in the monorepo (via workspace:* link) and in user projects (via npm install).
+//
+// IMPORTANT: Do NOT import from the main 'convex-cms' barrel export here.
+// It re-exports convex/server code (via admin functions) which contaminates
+// the browser bundle. Use specific sub-paths that are browser-safe:
+// - convex-cms/roles: only depends on convex/values
+// - convex-cms/types: type-only re-exports from component modules
+// - convex-cms/react: React hooks (browser-safe)
+export { getRole, getRolePermissions } from 'convex-cms/roles';
+export type { RoleName } from 'convex-cms/roles';
+export type { BaseAdminAPI } from 'convex-cms';
+export type { FieldType, ContentType } from 'convex-cms/types';
+export { useMediaUploadQueue } from 'convex-cms/react';
+export type { UploadQueueFile, UploadQueueFileStatus } from 'convex-cms/react';

package/admin/src/standalone/App.tsx

@@ -0,0 +1,156 @@
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { useMemo, type ReactNode } from "react";
+import { RouterProvider } from "@tanstack/react-router";
+import { RouteGuard } from "~/components";
+import {
+	AuthProvider,
+	BreadcrumbProvider,
+	SettingsConfigProvider,
+	ThemeProvider,
+	type GetUserHook,
+	type GetUserRoleHook,
+	type LogoutHook,
+} from "~/contexts";
+import { ApiProvider } from "~/embed/contexts/ApiContext";
+import type { AdminConfig } from "~/lib/admin-config";
+import { resolveAdminConfig } from "~/lib/admin-config";
+import { adminApi } from "~/lib/adminApi";
+import { getCmsConfig } from "./config";
+import { router } from "./router";
+
+const mockGetUser: GetUserHook = () => ({
+	id: "mock_user_123",
+	name: "Demo Admin",
+	email: "admin@example.com",
+});
+
+const mockGetUserRole: GetUserRoleHook = () => "admin";
+const mockLogout: LogoutHook = () => {
+	console.log("Logout called (mock mode)");
+};
+
+const noAuthGetUser: GetUserHook = () => null;
+const noAuthGetUserRole: GetUserRoleHook = () => null;
+const noAuthLogout: LogoutHook = () => {};
+
+function getAuthConfig(authMode: string): {
+	getUser: GetUserHook;
+	getUserRole: GetUserRoleHook;
+	onLogout: LogoutHook;
+} {
+	switch (authMode) {
+		case "mock":
+		case "demo":
+			return {
+				getUser: mockGetUser,
+				getUserRole: mockGetUserRole,
+				onLogout: mockLogout,
+			};
+		case "none":
+		case "disabled":
+			return {
+				getUser: noAuthGetUser,
+				getUserRole: noAuthGetUserRole,
+				onLogout: noAuthLogout,
+			};
+		default:
+			return {
+				getUser: mockGetUser,
+				getUserRole: mockGetUserRole,
+				onLogout: mockLogout,
+			};
+	}
+}
+
+export function App() {
+	const config = getCmsConfig();
+	const authConfig = useMemo(
+		() => getAuthConfig(config.authMode),
+		[config.authMode],
+	);
+	const adminConfig = useMemo(
+		() => resolveAdminConfig(config.adminConfig),
+		[config.adminConfig],
+	);
+
+	return (
+		<ThemeProvider>
+			<BreadcrumbProvider>
+				<ConvexProviderWrapper
+					convexUrl={config.convexUrl}
+					adminConfig={adminConfig}
+				>
+					<AuthProvider
+						getUser={authConfig.getUser}
+						getUserRole={authConfig.getUserRole}
+						onLogout={authConfig.onLogout}
+					>
+						<RouteGuard>
+							<RouterProvider router={router} />
+						</RouteGuard>
+					</AuthProvider>
+				</ConvexProviderWrapper>
+			</BreadcrumbProvider>
+		</ThemeProvider>
+	);
+}
+
+function ConvexProviderWrapper({
+	children,
+	convexUrl,
+	adminConfig,
+}: {
+	children: ReactNode;
+	convexUrl: string;
+	adminConfig: AdminConfig;
+}) {
+	const convex = useMemo(() => {
+		if (!convexUrl) return null;
+		return new ConvexReactClient(convexUrl);
+	}, [convexUrl]);
+
+	if (!convex) {
+		return (
+			<div className="flex min-h-screen items-center justify-center bg-background p-6">
+				<div className="diff-modified max-w-lg space-y-4 rounded-lg border p-6 text-center">
+					<h2 className="text-xl font-semibold text-diff-modified">
+						Convex Configuration Required
+					</h2>
+					<p className="text-sm text-diff-modified-foreground">
+						Please provide a Convex deployment URL to connect to your backend.
+					</p>
+					<div className="space-y-2 text-left text-sm text-diff-modified-foreground">
+						<p className="font-medium">Options:</p>
+						<ul className="list-inside list-disc space-y-1">
+							<li>
+								Run with URL:{" "}
+								<code className="rounded bg-diff-modified-bg/50 px-1">
+									npx convex-cms admin --url YOUR_URL
+								</code>
+							</li>
+							<li>
+								Set environment variable:{" "}
+								<code className="rounded bg-diff-modified-bg/50 px-1">
+									CONVEX_URL=YOUR_URL
+								</code>
+							</li>
+						</ul>
+					</div>
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<ConvexProvider client={convex}>
+			<ApiProvider api={adminApi}>
+				<SettingsConfigProvider
+					baseConfig={adminConfig}
+					api={{ getSettings: adminApi.getSettings }}
+				>
+					{children}
+				</SettingsConfigProvider>
+			</ApiProvider>
+		</ConvexProvider>
+	);
+}

package/admin/src/standalone/config.ts

@@ -0,0 +1,24 @@
+import type { AdminConfig } from "~/lib/admin-config";
+
+interface CmsConfig {
+	convexUrl: string;
+	authMode: string;
+	adminConfig?: Partial<AdminConfig>;
+}
+
+declare global {
+	interface Window {
+		__CMS_CONFIG__?: CmsConfig;
+	}
+}
+
+export function getCmsConfig(): CmsConfig {
+	if (window.__CMS_CONFIG__) {
+		return window.__CMS_CONFIG__;
+	}
+
+	return {
+		convexUrl: import.meta.env.VITE_CONVEX_URL ?? "",
+		authMode: import.meta.env.VITE_AUTH_MODE ?? "demo",
+	};
+}

package/admin/src/standalone/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "~/index.css";
+
+createRoot(document.getElementById("root")!).render(
+	<StrictMode>
+		<App />
+	</StrictMode>,
+);