create-ec-app 1.6.0 → 1.8.0

package/dist/portalContainers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portalContainers.js","sourceRoot":"","sources":["../src/portalContainers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-ec-app",
-	"version": "1.6.0",
+	"version": "1.8.0",
 	"description": "Unified CLI tool to create different types of EC applications: Webresource, Portal, Power Pages, Power Apps Code Apps",
 	"bin": {
 		"create-ec-app": "./dist/index.js"

package/scripts/check-generated-css-scope.mjs

@@ -23,30 +23,51 @@ const root = postcss.parse(css, { from: cssPath });
 const failures = [];
 
 root.walkRules((rule) => {
-	if (!rule.nodes?.some((node) => node.type === "decl" && node.prop.startsWith("--"))) {
+	if (isKeyframesRule(rule)) {
 		return;
 	}
 
 	for (const selector of splitSelectorList(rule.selector)) {
-		if (!selector.includes(".ec-pcf-shell-control")) {
-			failures.push(`unscoped custom-property rule: ${selector}`);
+		if (!selector.includes(".pcf-shell-control")) {
+			failures.push(`unscoped PCF rule: ${selector}`);
 		}
 	}
 });
 
-if (!css.includes("[data-ec-pcf-control=")) {
+if (!css.includes("[data-pcf-control=")) {
 	failures.push("missing PCF control data attribute scope");
 }
 
+if (css.includes(".ec-pcf-shell-control") || css.includes("[data-ec-pcf-control=")) {
+	failures.push("legacy EC PCF scope is still present");
+}
+
 if (failures.length > 0) {
-	console.error("PCF CSS variable scope check failed:");
+	console.error("PCF CSS scope check failed:");
 	for (const failure of failures) {
 		console.error(`- ${failure}`);
 	}
 	process.exit(1);
 }
 
-console.log("PCF CSS variable scope check passed.");
+console.log("PCF CSS scope check passed.");
+
+function isKeyframesRule(rule) {
+	let parent = rule.parent;
+
+	while (parent) {
+		if (
+			parent.type === "atrule" &&
+			parent.name.toLowerCase().endsWith("keyframes")
+		) {
+			return true;
+		}
+
+		parent = parent.parent;
+	}
+
+	return false;
+}
 
 function splitSelectorList(selectorList) {
 	const selectors = [];

package/templates/base/src/main.tsx

@@ -4,7 +4,6 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
 import "./index.css";
 import App from "./App.tsx";
-import { EcAppShell } from "./runtime/EcAppShell.tsx";
 
 const queryClient = new QueryClient({
 	defaultOptions: {
@@ -24,9 +23,7 @@ const root = createRoot(document.getElementById("root")!);
 root.render(
 	<StrictMode>
 		<QueryClientProvider client={queryClient}>
-			<EcAppShell>
-				<App />
-			</EcAppShell>
+			<App />
 		</QueryClientProvider>
 	</StrictMode>
 );

package/templates/pcf/base/README.md

@@ -9,6 +9,29 @@ npm install
 npm run build
 ```
 
+## Regenerate From Webresource Changes
+
+Do not edit this generated PCF folder as the durable source of truth. From the webresource root, rebuild and regenerate:
+
+```bash
+npm run build
+npx create-ec-app@latest \
+  --pcf-dir . \
+  --output ./pcf/{{PCF_CONSTRUCTOR}} \
+  --namespace {{PCF_NAMESPACE}} \
+  --constructor {{PCF_CONSTRUCTOR}} \
+  --display-name "{{CONTROL_DISPLAY_NAME}}"
+cd pcf/{{PCF_CONSTRUCTOR}}
+npm install
+npm run build
+```
+
+Then run the harness:
+
+```bash
+npm run start -- --no-open
+```
+
 ## Control Info
 
 - Namespace: `{{PCF_NAMESPACE}}`
@@ -18,14 +41,15 @@ npm run build
 
 ## Notes
 
-- The wrapper imports `src/App` directly and uses generated `pcf-scoped.css` derived from the webresource build.
+- The wrapper imports `src/App` directly, renders it through the local PCF shell, and uses generated `pcf-scoped.css` derived from the webresource build.
+- Source-app CSS imports are ignored by the PCF webpack config because the built CSS is already included through `pcf-scoped.css`.
 - Regenerate this folder after rebuilding the webresource whenever the app changes.
 - The project includes both `pcf-scripts` build support and a `.pcfproj` for Dataverse solution packaging flows.
 
 ## CSS scoping
 
-This PCF control renders the app inside the PCF host container class `.ec-pcf-shell-control`.
+This PCF control renders the app inside the PCF host container class `.pcf-shell-control`.
 
-During PCF generation, `create-ec-app` reads the webresource's built `dist/main.css`, scopes CSS custom-property rules to this control's `.ec-pcf-shell-control[data-ec-pcf-control="{{PCF_CONSTRUCTOR}}"]` host selector, and writes the result to `pcf-scoped.css`.
+During PCF generation, `create-ec-app` reads the webresource's built `dist/main.css`, scopes CSS selectors to this control's `.pcf-shell-control[data-pcf-control="{{PCF_CONSTRUCTOR}}"]` host selector, and writes the result to `pcf-scoped.css`.
 
-Tailwind utilities remain unprefixed, while shadcn/Tailwind theme variables are local to the generated PCF control. Radix/shadcn portals render into the app-local portal root where supported.
+Tailwind utilities and base selectors are isolated under the generated PCF host selector. Radix/shadcn portals render into the PCF-local portal root where supported.

package/templates/pcf/base/index.ts

@@ -4,7 +4,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
 import App from "{{PROJECT_APP_IMPORT}}";
 import "{{PROJECT_CSS_IMPORT}}";
-import { EcAppShell } from "{{PROJECT_EC_APP_SHELL_IMPORT}}";
+import { PcfAppShell } from "./runtime/PcfAppShell";
 import type { IInputs, IOutputs } from "./control/generated/ManifestTypes";
 import type {
 	PcfRuntimeContext,
@@ -16,13 +16,37 @@ function sanitizeGuid(value: string | null | undefined): string | null {
 	return value.replace(/[{}]/g, "");
 }
 
+function getPageClientUrl(
+	pageContext:
+		| {
+				clientUrl?: unknown;
+				getClientUrl?: unknown;
+		  }
+		| undefined,
+): string | null {
+	const getClientUrl = pageContext?.getClientUrl;
+	if (typeof getClientUrl === "function") {
+		try {
+			const clientUrl = getClientUrl.call(pageContext);
+			return typeof clientUrl === "string" ? clientUrl : null;
+		} catch {
+			return null;
+		}
+	}
+
+	return typeof pageContext?.clientUrl === "string"
+		? pageContext.clientUrl
+		: null;
+}
+
 function getContextInfo(context: ComponentFramework.Context<IInputs>) {
 	const pageContext = (
 		context as ComponentFramework.Context<IInputs> & {
 			page?: {
+				clientUrl?: unknown;
 				entityId?: string;
 				entityTypeName?: string;
-				getClientUrl?: () => string;
+				getClientUrl?: unknown;
 			};
 		}
 	).page;
@@ -39,7 +63,7 @@ function getContextInfo(context: ComponentFramework.Context<IInputs>) {
 		),
 		entityName:
 			modeContextInfo?.entityTypeName ?? pageContext?.entityTypeName ?? null,
-		clientUrl: pageContext?.getClientUrl?.() ?? null,
+		clientUrl: getPageClientUrl(pageContext),
 		userId: sanitizeGuid(context.userSettings.userId),
 	};
 }
@@ -112,8 +136,8 @@ export class {{PCF_CONSTRUCTOR}}
 		_state: ComponentFramework.Dictionary,
 		container: HTMLDivElement,
 	): void {
-		container.classList.add("ec-pcf-shell-control");
-		container.dataset.ecPcfControl = "{{PCF_CONSTRUCTOR}}";
+		container.classList.add("pcf-shell-control");
+		container.dataset.pcfControl = "{{PCF_CONSTRUCTOR}}";
 		this.runtime = createRuntime(context);
 		this.root = createRoot(container);
 		this.render();
@@ -144,7 +168,7 @@ export class {{PCF_CONSTRUCTOR}}
 				StrictMode,
 				null,
 				React.createElement(
-					EcAppShell,
+					PcfAppShell,
 					null,
 					React.createElement(
 						QueryClientProvider,

package/templates/pcf/base/runtime/PcfAppShell.tsx

@@ -0,0 +1,17 @@
+import * as React from "react";
+
+import { PortalContainerContext } from "{{PROJECT_PORTAL_CONTAINER_IMPORT}}";
+
+export function PcfAppShell({ children }: { children: React.ReactNode }) {
+	const [portalContainer, setPortalContainer] =
+		React.useState<HTMLDivElement | null>(null);
+
+	return (
+		<div data-pcf-app-root="">
+			<PortalContainerContext.Provider value={portalContainer}>
+				{children}
+				<div data-pcf-portal-root="" ref={setPortalContainer} />
+			</PortalContainerContext.Provider>
+		</div>
+	);
+}

package/templates/pcf/base/runtime/emptyStyles.js

@@ -0,0 +1 @@
+module.exports = {};

package/templates/pcf/base/webpack.config.js

@@ -1,4 +1,7 @@
 const path = require("path");
+const webpack = require("webpack");
+
+const projectSrcPath = path.resolve(__dirname, "{{PROJECT_SRC_ALIAS}}");
 
 module.exports = {
 	resolve: {
@@ -8,4 +11,14 @@ module.exports = {
 			"react-dom": path.resolve(__dirname, "{{PROJECT_REACT_DOM_ALIAS}}"),
 		},
 	},
+	plugins: [
+		new webpack.NormalModuleReplacementPlugin(
+			/\.(css|scss|sass)$/,
+			(resource) => {
+				if (path.resolve(resource.context).startsWith(projectSrcPath)) {
+					resource.request = path.resolve(__dirname, "runtime/emptyStyles.js");
+				}
+			},
+		),
+	],
 };

package/templates/targets/code-apps/AGENTS.md

@@ -0,0 +1,187 @@
+## Purpose
+
+This repository is a Power Apps code app using React, TypeScript, Vite, and the Power Apps code app SDK.
+
+Treat it as a Power Apps-hosted code app, not a Dynamics web resource. Keep it small, readable, and easy to push with the Power Apps tooling.
+
+Use the global AGENTS.md rules first. This file adds project-specific constraints.
+
+## Hard Constraints
+
+- Keep Power Apps code app hosting working.
+- Keep local Power Apps play support working.
+- Keep generated connector and Dataverse service access working.
+- Keep the app client-side.
+- Make surgical changes.
+
+Do not add Dynamics `Xrm`, `token.json`, Power Pages ADAL, Static Web Apps routing, or direct Dataverse Web API auth patterns unless the target changes.
+
+## Runtime Modes
+
+The app supports two modes.
+
+### Power Apps-hosted
+
+- The Power Apps host manages end-user authentication, app loading, and runtime context.
+- Use `@microsoft/power-apps` APIs when app, environment, user, host, or query-parameter context is needed.
+- Use generated models and services for Dataverse and connector access.
+- Preserve `power.config.json` semantics after `npx power-apps init`.
+- Do not assume model-driven app `window.Xrm` context exists.
+
+### Local dev
+
+- Run Vite through `npm run dev`.
+- Open the Local Play URL printed by the Power Apps Vite plugin.
+- Use the same browser profile as the target Power Platform tenant.
+- Run `npx power-apps init` before real push/data-source work.
+- Treat `power.config.example.json` as documentation only; do not rename it to bypass initialization.
+
+Do not mix this with webresource `authService.ts`, `token.json`, or Power Pages `AuthContext`.
+
+## Critical Files
+
+| File | Rule |
+|---|---|
+| `vite.config.ts` | Preserve `powerApps()` plus React, Tailwind, and alias config. |
+| `power.config.json` | Generated by `npx power-apps init`; environment-specific app metadata and data references live here. |
+| `power.config.example.json` | Reference only. Do not make it the real config before initialization. |
+| `src/generated/models/*` | Generated data-source models. Do not hand-edit unless the generator output is known wrong. |
+| `src/generated/services/*` | Generated service methods for Dataverse/connectors/actions/functions. Prefer these over custom clients. |
+| `src/main.tsx` | Preserve bootstrap, providers, and global theme/style imports. |
+
+## API and Data Access
+
+Prefer generated Power Apps services.
+
+Use:
+
+- `npx power-apps add-data-source` for Dataverse and connector data sources
+- `npx power-apps add-dataverse-api` for Dataverse actions/functions
+- generated service methods from `src/generated/services`
+- generated model types from `src/generated/models`
+- `getContext` from `@microsoft/power-apps/app` when host context is needed
+- narrow `select` options when generated Dataverse services support them
+- clear errors when generated calls fail
+
+Avoid:
+
+- direct browser calls to Dataverse Web API
+- copied webresource `getApiUrl()` / `getAuthHeaders()` helpers
+- manually maintained connector clients
+- wrapping every generated service in another generic service layer
+- repository/client layers for small features
+- Zod schemas for every generated response
+- silent fallbacks for failed connector or Dataverse calls
+
+For known data sources, use the generated service for that source. Add a new data source only when the current feature needs it.
+
+## Validation
+
+Use generated TypeScript models for normal connector and Dataverse response shapes.
+
+Use runtime validation only when the current feature needs it, such as:
+
+- user-entered form data
+- URL/query parameters that control behavior
+- data sent to create/update/delete operations
+- genuinely variable connector data where the UI must branch safely
+- security-sensitive or data-loss-prone paths
+
+Do not validate values just because they are shaped like GUIDs, logical names, dates, URLs, or enum strings. If the generated service or platform will reject the value clearly and there is no local UX/security need, pass it through.
+
+Do not normalize strings by default. Trim, lowercase, strip braces, or reformat only when the app has a known input source that sends multiple formats.
+
+## Services, Queries, and Mutations
+
+Keep service files explicit.
+
+Preferred shape:
+
+- call the generated service directly from a small domain service when naming the operation helps
+- one TanStack Query hook when components need query state
+- one mutation hook when mutation state or invalidation is needed
+- query keys colocated with the hook when reused for invalidation
+
+Do not create wrapper chains such as:
+
+```text
+resolveConfig -> normalizeInput -> validateInput -> resolveGeneratedService -> buildRequest -> executeRequest
+```
+
+Prefer direct flow:
+
+```text
+call generated service -> check result/error -> return typed data
+```
+
+## State Management
+
+- Use TanStack Query for server/connector state.
+- Use local component state for local UI behavior.
+- Use Zustand only for shared client state that has outgrown local state.
+- Do not store server state in Zustand.
+- Do not add Redux unless explicitly requested.
+
+## UI and Styling
+
+Stay consistent with the project's existing UI system.
+
+- Shadcn/ui projects: use existing `@/components/ui` components and Tailwind utilities.
+- Kendo projects: use Kendo React components for rich controls and Tailwind for layout/composition.
+- Preserve the existing theme and global CSS imports.
+- Do not mix UI systems unless explicitly asked.
+- Do not hand-roll custom CSS unless component props and Tailwind are not enough.
+- Keep layouts compact, scannable, responsive, and suitable for Power Apps hosting.
+
+## Code Shape
+
+Prefer:
+
+- focused React components
+- direct typed functions
+- existing generated services and components
+- small local helpers only when they remove real duplication or name non-obvious domain logic
+- explicit connector/table/action handling over generic frameworks
+
+Avoid:
+
+- broad factories
+- generic service clients
+- classes for simple service logic
+- excessive configuration
+- defensive wrappers around every value
+- broad refactors while adding a feature
+
+## Error Handling
+
+Connector calls, Dataverse reads/saves/deletes, auth/context failures, uploads, downloads, and required parsing failures should throw.
+
+Do not swallow failed generated service calls and treat them as empty data unless the requirement explicitly says the feature is best-effort.
+
+Include useful operation context and platform error text where practical.
+
+## Build and Deployment
+
+Do not replace Vite, remove `powerApps()`, add SSR, add Next.js, or change the app into a webresource/Power Pages/SWA deployment unless explicitly asked.
+
+Use `npm run build` for production assets and `npx power-apps push` for the npm CLI path. Use PAC CLI only when a required option is not available through the npm CLI.
+
+## Checks
+
+Run the smallest relevant command for the changed area, such as:
+
+- typecheck
+- lint
+- targeted tests
+- Vite build when deployment shape could be affected
+- local Power Apps play smoke test when SDK/plugin/data-source behavior changes
+
+Do not run broad expensive checks unless the change touches shared infrastructure or the project requires it.
+
+## Figma MCP
+
+When using the Figma MCP server, ensure that you are not just blindly copying the designs. Take note and always place a focus on the following:
+
+- Ensure responsiveness on all screen sizes
+- If there are icons as part of the design, use those, don't blindly look for Lucide-React equivalents.
+- Use the exact colours in the design. Don't make up your own.

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

@@ -0,0 +1,192 @@
+## Purpose
+
+This repository is a Power Pages single-page application using React, TypeScript, and Vite.
+
+Treat it as a Power Pages code site. Keep it small, readable, and easy to upload to Power Pages.
+
+Use the global AGENTS.md rules first. This file adds project-specific constraints.
+
+## Hard Constraints
+
+- Keep Power Pages code-site deployment working.
+- Keep Power Pages `_api` access working.
+- Keep local Vite development working.
+- Keep the app client-side.
+- Make surgical changes.
+
+Do not add Dynamics `Xrm`, `token.json`, Static Web Apps routing, or Power Apps code app SDK patterns unless the target changes.
+
+## Runtime Modes
+
+The app supports two modes.
+
+### Power Pages-hosted
+
+- Run as a browser SPA hosted by Power Pages.
+- Use Power Pages `_api` for Dataverse access from the site.
+- Rely on Power Pages web roles, table permissions, and site settings for data authorization.
+- Preserve code-site build output and `powerpages.config.json`.
+- Do not call the Dataverse organization Web API directly from the browser.
+- Do not assume `window.Xrm` or model-driven app context exists.
+
+### Local dev
+
+- Use Vite for local UI development.
+- Use the existing Vite `/_api` proxy when local code needs to call a Power Pages site.
+- Keep the proxy target explicit and environment-specific.
+- Use the existing `AuthContext` flow only where this template already requires it.
+- Never commit client secrets, tenant-specific secrets, or real token values.
+
+Do not mix Power Pages auth with webresource `authService.ts` or `token.json`.
+
+## Critical Files
+
+| File | Rule |
+|---|---|
+| `src/context/AuthContext.tsx` | Current auth boundary for this template. Reuse it; do not add a second auth system. |
+| `src/main.tsx` | Preserve `AuthProvider`, `QueryClientProvider`, bootstrap, and global style imports. |
+| `vite.config.ts` | Preserve React, Tailwind, alias, and the `/_api` dev proxy when API calls are used locally. |
+| `powerpages.config.json` | Power Pages code-site configuration. Keep compiled path and landing page accurate. |
+| `src/App.tsx` | Keep app behavior client-side and provider-aware. |
+
+## API and Data Access
+
+Prefer direct, boring Power Pages Web API calls.
+
+Use:
+
+- relative `_api/...` URLs
+- the existing auth context only where the current template flow already uses it
+- Power Pages request verification/CSRF handling where the portal Web API requires it
+- Power Pages table permissions and web roles for authorization
+- narrow `$select` queries
+- `URLSearchParams` for normal query parameters
+- direct `fetch` inside service files
+- small TypeScript interfaces for response shapes
+- clear `response.ok` checks with useful status text
+
+Avoid:
+
+- direct calls to `https://<org>.crm*.dynamics.com/api/data/v9.2` from the browser
+- duplicated auth contexts
+- raw fetch calls inside UI components
+- repository/client layers for small features
+- generic OData builders
+- Zod schemas for every Power Pages response
+- GUID or logical-name regex validation by default
+- silent fallbacks for failed Power Pages calls
+
+For known tables, use known entity set names. Fetch metadata only when the feature truly supports arbitrary table names.
+
+Escape OData string literals when interpolating inside quoted OData expressions. Do not create a broad escaping/parsing layer for simple queries.
+
+## Validation
+
+Use TypeScript types for normal Power Pages Web API response shapes.
+
+Use runtime validation only when the current feature needs it, such as:
+
+- user-entered form data
+- URL/search parameters that control behavior
+- local config that can be wrong
+- genuinely variable API data where the UI must branch safely
+- security-sensitive or data-loss-prone paths
+
+Do not validate values just because they are shaped like GUIDs, logical names, dates, URLs, or enum strings. If Power Pages or Dataverse will reject the value clearly and there is no local UX/security need, pass it through.
+
+Do not normalize strings by default. Trim, lowercase, strip braces, or reformat only when the app has a known input source that sends multiple formats.
+
+## Services, Queries, and Mutations
+
+Keep service files explicit.
+
+Preferred shape:
+
+- one fetch/save function for the operation
+- one TanStack Query hook when components need it
+- one mutation hook when mutation state or invalidation is needed
+- query keys colocated with the hook when reused for invalidation
+
+Do not create wrapper chains such as:
+
+```text
+resolveConfig -> normalizeInput -> validateInput -> resolveMetadata -> buildRequest -> executeRequest
+```
+
+Prefer direct flow:
+
+```text
+read auth/context -> fetch -> check response -> return typed data
+```
+
+## State Management
+
+- Use TanStack Query for server state.
+- Use local component state for local UI behavior.
+- Use Zustand only for shared client state that has outgrown local state.
+- Do not store server state in Zustand.
+- Do not add Redux unless explicitly requested.
+
+## UI and Styling
+
+Stay consistent with the project's existing UI system.
+
+- Shadcn/ui projects: use existing `@/components/ui` components and Tailwind utilities.
+- Kendo projects: use Kendo React components for rich controls and Tailwind for layout/composition.
+- Preserve the existing theme and global CSS imports.
+- Do not mix UI systems unless explicitly asked.
+- Do not hand-roll custom CSS unless component props and Tailwind are not enough.
+- Keep layouts compact, scannable, responsive, and suitable for Power Pages.
+
+## Code Shape
+
+Prefer:
+
+- focused React components
+- direct typed functions
+- existing auth, services, and components
+- small local helpers only when they remove real duplication or name non-obvious domain logic
+- explicit Power Pages table/field handling over generic frameworks
+
+Avoid:
+
+- broad factories
+- generic service clients
+- classes for simple service logic
+- excessive configuration
+- defensive wrappers around every value
+- broad refactors while adding a feature
+
+## Error Handling
+
+Power Pages reads, saves, deletes, uploads, downloads, auth failures, and required parsing failures should throw.
+
+Do not swallow failed fetches and treat them as "not found" unless the requirement explicitly says the feature is best-effort.
+
+Include response status and useful response text where practical.
+
+## Build and Deployment
+
+Do not replace Vite, add SSR, add Next.js, change the code-site output shape, or introduce backend coupling unless explicitly asked.
+
+Keep output deployable through the Power Pages code-site flow and keep `powerpages.config.json` aligned with the built `dist` folder.
+
+## Checks
+
+Run the smallest relevant command for the changed area, such as:
+
+- typecheck
+- lint
+- targeted tests
+- Vite build when deployment shape could be affected
+- local `/_api` proxy smoke test when API routing changes
+
+Do not run broad expensive checks unless the change touches shared infrastructure or the project requires it.
+
+## Figma MCP
+
+When using the Figma MCP server, ensure that you are not just blindly copying the designs. Take note and always place a focus on the following:
+
+- Ensure responsiveness on all screen sizes
+- If there are icons as part of the design, use those, don't blindly look for Lucide-React equivalents.
+- Use the exact colours in the design. Don't make up your own.