create-ec-app 0.0.6 → 0.0.7

package/templates/base/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "base",
+	"private": true,
+	"version": "0.1.0",
+	"type": "module",
+	"scripts": {
+		"dev": "vite",
+		"build": "tsc -b && vite build",
+		"lint": "eslint .",
+		"preview": "vite preview",
+		"format": "biome format --write .",
+		"lint:biome": "biome lint .",
+		"check": "biome check --write --no-errors-on-unmatched .",
+		"format:check": "biome format --check .",
+		"lint:fix": "biome lint --apply ."
+	},
+	"dependencies": {
+		"@tailwindcss/vite": "^4.1.18",
+		"tailwindcss": "^4.1.18",
+		"@tanstack/react-query": "^5.90.16",
+		"@types/xrm": "^9.0.88",
+		"react": "^19.2.3",
+		"react-dom": "^19.2.3",
+		"zod": "^4.3.5",
+		"zustand": "^5.0.9"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.2",
+		"@tanstack/eslint-plugin-query": "^5.91.2",
+		"@types/node": "^24.10.4",
+		"@types/react": "^19.2.7",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^5.1.2",
+		"eslint": "^9.39.2",
+		"eslint-plugin-react-hooks": "^7.0.1",
+		"eslint-plugin-react-refresh": "^0.4.26",
+		"globals": "^16.5.0",
+		"typescript": "~5.9.3",
+		"typescript-eslint": "^8.51.0",
+		"vite": "^7.3.0"
+	}
+}

package/templates/base/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/templates/base/src/App.tsx

@@ -0,0 +1,11 @@
+import "./App.css";
+
+function App() {
+	return (
+		<div className="flex flex-col h-screen items-center justify-center">
+			<p>Hello, world!</p>
+		</div>
+	);
+}
+
+export default App;

package/templates/base/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module "*.css";
+declare module "*.scss";
+declare module "*.svg";
+declare module "*.png";

package/templates/base/src/index.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/base/src/main.tsx

@@ -0,0 +1,29 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import "./index.css";
+import App from "./App.tsx";
+
+const queryClient = new QueryClient({
+	defaultOptions: {
+		queries: {
+			refetchOnWindowFocus: false,
+			retry: 3,
+			staleTime: 5 * 60 * 1000, // 5 minutes
+		},
+		mutations: {
+			retry: 1,
+		},
+	},
+});
+
+const root = createRoot(document.getElementById("root")!);
+
+root.render(
+	<StrictMode>
+		<QueryClientProvider client={queryClient}>
+			<App />
+		</QueryClientProvider>
+	</StrictMode>
+);

package/templates/base/tsconfig.app.json

@@ -0,0 +1,32 @@
+{
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+		"target": "ES2022",
+		"useDefineForClassFields": true,
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"module": "ESNext",
+		"types": ["vite/client"],
+		"skipLibCheck": true,
+		/* Bundler mode */
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+		"jsx": "react-jsx",
+		/* Linting */
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"erasableSyntaxOnly": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedSideEffectImports": true,
+
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["./src/*"]
+		}
+	},
+	"include": ["src"]
+}
+

package/templates/base/tsconfig.json

@@ -0,0 +1,19 @@
+{
+    "files": [],
+    "references": [
+        {
+            "path": "./tsconfig.app.json"
+        },
+        {
+            "path": "./tsconfig.node.json"
+        }
+    ],
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "@/*": [
+                "./src/*"
+            ]
+        }
+    }
+}

package/templates/base/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+		"target": "ES2023",
+		"lib": ["ES2023"],
+		"module": "ESNext",
+		"types": ["node"],
+		"skipLibCheck": true,
+
+		/* Bundler mode */
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+
+		/* Linting */
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"erasableSyntaxOnly": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedSideEffectImports": true
+	},
+	"include": ["vite.config.ts"]
+}

package/templates/base/vite.config.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// https://vite.dev/config/
+export default defineConfig({
+	plugins: [react(), tailwindcss()],
+	resolve: {
+		alias: {
+			"@": path.resolve(__dirname, "./src"),
+		},
+	},
+});

package/templates/targets/power-pages/.env

@@ -0,0 +1,3 @@
+VITE_AAD_CLIENT_ID=db392465-21e2-4e5f-9fa5-a25d4dab354f
+VITE_AAD_TENANT_ID=961b8f6e-3902-49b5-b679-5beabfc73016
+VITE_AUTH_DEBUG=true

package/templates/targets/power-pages/README.md

@@ -0,0 +1,180 @@
+# EC Power Pages Single Page Application (SPA)
+
+This is a Power Pages Single Page Application (SPA) built with React, Vite, and TypeScript, generated by `create-ec-app`. It follows Microsoft’s official Power Pages code site model, providing a modern, scalable, and maintainable frontend architecture tailored specifically for Power Pages environments. The app includes integrated authentication, data fetching, and UI options designed to work seamlessly within the Power Pages runtime.
+
+## Features
+
+- **React + Vite + TypeScript**: Modern frontend stack for fast development and optimized builds.
+- **Tailwind CSS**: Utility-first CSS framework with an optional Kendo UI preset for styling consistency.
+- **UI Library Choice**: Select between Kendo UI (including theme selection) or Shadcn/ui components.
+- **TanStack Query**: Preconfigured React Query provider for efficient data fetching and caching.
+- **ADAL Authentication**: Integrated Azure Active Directory Authentication Library (ADAL) for Entra ID authentication with token caching.
+- **Local Development Support**: Full authentication support during local development using ADAL
+- **Optimized Vite Build Output**: Builds optimized assets tailored for upload to Power Pages code sites.
+
+## Auth and API Access
+
+This SPA uses ADAL (Azure Active Directory Authentication Library) for authentication. While ADAL is deprecated by Microsoft, it remains functional for Power Pages scenarios until MSAL v2 support is available.
+
+### Authentication Setup
+
+The `AuthContext` requires the following environment variables:
+
+- `VITE_AAD_TENANT_ID`: Your Azure AD tenant ID (defaults to "common")
+- `VITE_AAD_CLIENT_ID`: Your Azure AD application (client) ID (required)
+- `VITE_AUTH_DEBUG`: Optional, set to "true" for verbose authentication logging
+
+### How It Works
+
+1. **Script Loading**: ADAL is dynamically loaded from Microsoft's CDN (`https://secure.aadcdn.microsoftonline-p.com/lib/1.0.17/js/adal.min.js`)
+2. **Token Caching**: Authentication tokens are cached in localStorage for persistence
+3. **User Information**: The authenticated user object includes `userName`, `displayableId`, `name`, `givenName`, `familyName`, and `idToken`
+4. **Token Retrieval**: Access ID tokens via the `getIdToken()` method from the auth context
+
+### Authentication Flow
+
+- When users call `login()`, they're redirected to Azure AD for authentication
+- After successful authentication, users are redirected back with tokens
+- Tokens are automatically cached and reused for subsequent requests
+- Call `logout()` to clear tokens and sign out the user
+
+## Example Data Fetch Using TanStack Query and AuthContext
+
+Here is an example of a service module `src/services/contacts.ts` that demonstrates fetching contacts data from the Power Pages API using TanStack Query:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { AuthButton } from "./components/shared/AuthButton";
+import { useAuth } from "./context/AuthContext";
+
+type Account = {
+ name: string | null;
+ accountnumber: string | null;
+ accountid: string;
+};
+
+function App() {
+ const { isAuthenticated, user } = useAuth();
+
+ const { data: accounts, isLoading } = useQuery({
+  queryKey: ["accounts"],
+  queryFn: async () => {
+   const response = await fetch(
+    `_api/accounts?$select=name,accountnumber&$top=5`,
+    {
+     method: "GET",
+     headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${user?.idToken}`,
+     },
+    }
+   );
+
+   if (!response.ok) {
+    throw new Error("Network response was not ok");
+   }
+   return response.json();
+  },
+  enabled: isAuthenticated && !!user,
+ });
+
+ if (isLoading) {
+  return (
+   <div className="flex flex-col items-center justify-center h-screen">
+    <div>Loading...</div>
+   </div>
+  );
+ }
+
+ return (
+  <div className="flex flex-col items-center justify-center h-screen gap-4">
+   {accounts ? (
+    <div>
+     <h2 className="mb-4 text-xl font-bold">Accounts:</h2>
+     <ul className="list-disc list-inside">
+      {accounts.value.map((account: Account) => (
+       <li key={account.accountid}>
+        {account.name} - {account.accountnumber}
+       </li>
+      ))}
+     </ul>
+    </div>
+   ) : (
+    <div>
+     {isAuthenticated ? (
+      <div>No accounts data available.</div>
+     ) : (
+      <>
+       <div>Please log in to view your accounts.</div>
+       <AuthButton />
+      </>
+     )}
+    </div>
+   )}
+  </div>
+ );
+}
+
+export default App;
+```
+
+## Creating an Auth Button
+
+```tsx
+import { useAuth } from "@/context/AuthContext";
+import { Button } from "../ui/button";
+
+export const AuthButton = () => {
+  const { isAuthenticated, user, login, logout } = useAuth();
+  const displayName = user?.name || user?.userName || user?.givenName || "";
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      {isAuthenticated ? (
+        <>
+          {displayName && <span>Welcome {displayName}</span>}
+          <Button variant="default" onClick={logout}>
+            Sign Out
+          </Button>
+        </>
+      ) : (
+        <Button onClick={login} variant="outline">
+          Sign In
+        </Button>
+      )}
+    </div>
+  );
+};
+```
+
+## UI Libraries
+
+- Kendo UI: Theme CSS is imported in `src/main.tsx`. Example:
+
+  ```tsx
+  import { Button } from "@progress/kendo-react-buttons";
+  <Button>Click me</Button>;
+  ```
+
+- Shadcn/ui: Components are installed and available under the `@/components` alias. Example:
+
+  ```tsx
+  import { Button } from "@/components/ui/button";
+  <Button>Click me</Button>;
+  ```
+
+## Deployment
+
+To deploy your Power Pages SPA:
+
+- Build the project using `npm run build` or `npm run build:dev` for development builds.
+- Upload the contents of the `dist` folder to your Power Pages site’s **code site**. This is a dedicated location for hosting SPA assets as static content.
+- Reference your built JavaScript and CSS files in your Power Pages pages as needed.
+
+For detailed guidance on Power Pages code sites and deployment, see the [Microsoft Power Pages documentation on code sites](https://learn.microsoft.com/en-us/power-pages/developer/code-sites).
+
+Power Pages code sites support continuous deployment workflows via the Power Platform CLI, enabling streamlined updates and integration with source control.
+
+## Configuration
+
+The `powerpages.config.json` file defines your site configuration, including output paths and landing page settings. Adjust this file to match your project and deployment conventions.

package/templates/targets/power-pages/powerpages.config.json

@@ -0,0 +1,5 @@
+{
+	"compiledPath": "./dist",
+	"siteName": "SITE_NAME",
+	"defaultLandingPage": "index.html"
+}

package/templates/targets/power-pages/src/App.patch.tsx

@@ -0,0 +1,17 @@
+import { useAuth } from "./context/AuthContext";
+
+function App() {
+	const { isAuthenticated, user } = useAuth(); //INFO: User is where the token information is stored (user?.idToken)
+
+	return (
+		<div className="flex flex-col items-center justify-center h-screen gap-4">
+			{isAuthenticated ? (
+				<div>You are logged in</div>
+			) : (
+				<div>Please Log In</div>
+			)}
+		</div>
+	);
+}
+
+export default App;

package/templates/targets/power-pages/src/context/AuthContext.tsx

@@ -0,0 +1,273 @@
+import {
+	createContext,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
+
+// NOTE: ADAL is deprecated. Prefer migrating to MSAL V2 when it is available
+// Env vars required:
+//   VITE_AAD_TENANT_ID
+//   VITE_AAD_CLIENT_ID
+// Optional:
+//   VITE_AUTH_DEBUG=true for verbose logging.
+
+const AAD_TENANT_ID =
+	(import.meta as ImportMeta).env?.VITE_AAD_TENANT_ID || "common";
+const AAD_CLIENT_ID = (import.meta as ImportMeta).env?.VITE_AAD_CLIENT_ID || "";
+const AUTH_DEBUG =
+	((import.meta as ImportMeta).env?.VITE_AUTH_DEBUG ?? "")
+		.toString()
+		.toLowerCase() === "true";
+if (!AAD_CLIENT_ID)
+	console.warn(
+		"VITE_AAD_CLIENT_ID is not set. Entra (ADAL) login will fail."
+	);
+
+interface AADUserInfo {
+	userName?: string;
+	profile?: Record<string, unknown>;
+	idToken?: string;
+	displayableId?: string;
+	name?: string;
+	givenName?: string;
+	familyName?: string;
+	username?: string;
+}
+
+declare global {
+	interface Window {
+		AuthenticationContext?: {
+			new (config: Record<string, unknown>): ADALContext;
+		} & ((config: Record<string, unknown>) => ADALContext);
+	}
+}
+
+interface ADALContext {
+	isCallback: (hash: string) => boolean;
+	handleWindowCallback: () => void;
+	getLoginError: () => string | null;
+	getCachedUser: () => {
+		userName?: string;
+		profile?: Record<string, unknown>;
+	} | null;
+	getCachedToken: (resource: string) => string | null;
+	login: () => void;
+	logOut: () => void;
+}
+
+interface AuthContextType {
+	isAuthenticated: boolean;
+	user: AADUserInfo | null;
+	login: () => Promise<void> | void;
+	logout: () => void;
+	error: string | null;
+	clearError: () => void;
+	getIdToken: () => Promise<string | null>;
+}
+
+const AuthContext = createContext<AuthContextType | null>(null);
+
+export const useAuth = () => {
+	const context = useContext(AuthContext);
+	if (!context) {
+		throw new Error("useAuth must be used within an AuthProvider");
+	}
+	return context;
+};
+
+interface AuthProviderProps {
+	children: ReactNode;
+}
+
+export const AuthProvider = ({ children }: AuthProviderProps) => (
+	<AuthProviderContent>{children}</AuthProviderContent>
+);
+
+const AuthProviderContent = ({ children }: { children: ReactNode }) => {
+	const [isAuthenticated, setIsAuthenticated] = useState(false);
+	const [user, setUser] = useState<AADUserInfo | null>(null);
+	const [idToken, setIdToken] = useState<string | null>(null);
+	const [error, setError] = useState<string | null>(null);
+	const scriptLoadedRef = useRef(false);
+	const adalContextRef = useRef<ADALContext | null>(null);
+
+	const clearError = () => setError(null);
+
+	const logDebug = useCallback((...args: unknown[]) => {
+		if (AUTH_DEBUG) console.log("[AuthDebug]", ...args);
+	}, []);
+
+	//INFO: We load the ADAL script from Microsoft's CDN. The alternative is to do it via npm, but it's deprecated.
+	const loadAdalScript = useCallback((): Promise<void> => {
+		if (scriptLoadedRef.current) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const existing = document.querySelector(
+				"script[data-adal]"
+			) as HTMLScriptElement | null;
+			if (existing) {
+				scriptLoadedRef.current = true;
+				resolve();
+				return;
+			}
+			const script = document.createElement("script");
+
+			//INFO: current version is pinned. Update this as needed.
+			script.src =
+				"https://secure.aadcdn.microsoftonline-p.com/lib/1.0.17/js/adal.min.js";
+			script.async = true;
+			script.defer = true;
+			script.setAttribute("data-adal", "true");
+			script.onload = () => {
+				scriptLoadedRef.current = true;
+				resolve();
+			};
+			script.onerror = (e) => reject(e);
+			document.head.appendChild(script);
+		});
+	}, []);
+
+	const buildAdalConfig = (): Record<string, unknown> => ({
+		tenant: AAD_TENANT_ID,
+		clientId: AAD_CLIENT_ID,
+		redirectUri: window.location.origin,
+		cacheLocation: "localStorage", //INFO: check what is required. Might be sessionStorage might be localStorage
+		navigateToLoginRequestUrl: false,
+		// endpoints: { 'https://graph.microsoft.com': 'https://graph.microsoft.com' }, //INFO: Add more resources as needed
+		extraQueryParameter: "prompt=select_account",
+	});
+
+	const ensureAdalContext = useCallback((): ADALContext | null => {
+		if (
+			!adalContextRef.current &&
+			window.AuthenticationContext &&
+			AAD_CLIENT_ID
+		) {
+			try {
+				const Ctx = window.AuthenticationContext as unknown as {
+					new (config: Record<string, unknown>): ADALContext;
+				};
+				adalContextRef.current = new Ctx(buildAdalConfig());
+				logDebug("ADAL context created");
+			} catch (e) {
+				console.warn("Failed to create ADAL context", e);
+			}
+		}
+		return adalContextRef.current;
+	}, [logDebug]);
+
+	const processCallbackIfPresent = useCallback(() => {
+		const ctx = ensureAdalContext();
+		if (!ctx) return;
+		if (ctx.isCallback(window.location.hash)) {
+			ctx.handleWindowCallback();
+			const err = ctx.getLoginError();
+			if (err) {
+				setError(err);
+			}
+		}
+	}, [ensureAdalContext]);
+
+	const populateFromCache = useCallback(() => {
+		const ctx = ensureAdalContext();
+		if (!ctx) return;
+		const cachedUser = ctx.getCachedUser();
+		const cachedIdToken = ctx.getCachedToken(AAD_CLIENT_ID);
+		if (cachedUser && cachedIdToken) {
+			const profile = cachedUser.profile || {};
+			const profileRecord = profile as Record<string, unknown>;
+			const str = (v: unknown) => (typeof v === "string" ? v : undefined);
+			const mapped: AADUserInfo = {
+				userName: cachedUser.userName,
+				displayableId: str(profileRecord["upn"]) || cachedUser.userName,
+				name: str(profileRecord["name"]),
+				givenName: str(profileRecord["given_name"]),
+				familyName: str(profileRecord["family_name"]),
+				username: cachedUser.userName,
+				idToken: cachedIdToken,
+				profile,
+			};
+			setUser(mapped);
+			setIdToken(cachedIdToken);
+			setIsAuthenticated(true);
+		} else {
+			setIsAuthenticated(false);
+		}
+	}, [ensureAdalContext]);
+
+	const login = async () => {
+		setError(null);
+		if (!AAD_CLIENT_ID) {
+			setError("AAD client ID not configured.");
+			return;
+		}
+		try {
+			await loadAdalScript();
+			const ctx = ensureAdalContext();
+			if (!ctx) {
+				setError("ADAL context not available.");
+				return;
+			}
+			ctx.login();
+		} catch (e) {
+			console.error("AAD login failed", e);
+			setError("Login failed.");
+		}
+	};
+
+	const logout = () => {
+		try {
+			const ctx = ensureAdalContext();
+			if (ctx) ctx.logOut();
+			setIsAuthenticated(false);
+			setUser(null);
+			setIdToken(null);
+		} catch (e) {
+			console.error("Logout failed", e);
+			setError("Logout failed.");
+		}
+	};
+
+	const getIdToken = async (): Promise<string | null> => idToken;
+
+	useEffect(() => {
+		loadAdalScript()
+			.then(() => {
+				processCallbackIfPresent();
+				populateFromCache();
+			})
+			.catch((e) => {
+				console.warn("Failed to load ADAL script", e);
+				setError("Failed to load authentication library.");
+			});
+		if (AUTH_DEBUG) {
+			console.log("[AuthDebug] Mounted AuthProvider (ADAL)", {
+				origin: window.location.origin,
+				tenant: AAD_TENANT_ID,
+				clientIdPresent: !!AAD_CLIENT_ID,
+				time: new Date().toISOString(),
+			});
+		}
+	}, [loadAdalScript, processCallbackIfPresent, populateFromCache]);
+
+	const value = {
+		isAuthenticated,
+		user,
+		login,
+		logout,
+		error,
+		clearError,
+		getIdToken,
+	};
+
+	if (error) {
+		throw new Error(`Authentication error: ${error}`);
+	}
+
+	return (
+		<AuthContext.Provider value={value}>{children}</AuthContext.Provider>
+	);
+};