create-ec-app 1.5.0 → 1.7.0

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/README.md

@@ -0,0 +1,246 @@
+# EC Power Apps Code App
+
+React + TypeScript template for Power Apps code apps. Generated by `create-ec-app`, it keeps the EC base app structure, Tailwind setup, TanStack Query provider, and selected UI layer, then adds Microsoft Power Apps code app support through `@microsoft/power-apps` and `@microsoft/power-apps-vite`.
+
+## Features
+
+- React + TypeScript with Vite
+- Tailwind CSS
+- UI library choice: Kendo UI or shadcn/ui
+- TanStack Query provider pre-wired in `src/main.tsx`
+- Power Apps SDK dependency for code app APIs and generated connector services
+- Power Apps Vite plugin for local play URLs, Power Apps CORS support, and `base: "./"` build output
+
+## Prerequisites
+
+- Node.js LTS and npm
+- Git
+- A Power Platform environment with Power Apps code apps enabled
+- A Power Apps Premium license for users who run the code app
+
+Admins enable code apps in Power Platform admin center by opening the target environment, then Settings > Product > Features, and turning on **Power Apps code apps**.
+
+## Getting Started
+
+Install dependencies if they were not installed during scaffolding:
+
+```bash
+npm install
+```
+
+Initialize the code app metadata and authenticate against your Power Platform environment:
+
+```bash
+npx power-apps init --display-name "{{APP_NAME}}" --environment-id <environment-id> --app-url http://localhost:5173
+```
+
+You can omit the options and run `npx power-apps init` to answer the interactive prompts instead. The command creates `power.config.json`, which the Power Apps SDK, Vite plugin, and deployment commands use.
+
+This template includes `power.config.example.json` only as a reference. Do not rename it before running `npx power-apps init`; the Microsoft CLI refuses to initialize when a real `power.config.json` already exists. The generated `power.config.json` includes your environment ID, app metadata, build settings, and connection/data references. It does not contain authentication tokens, but it is environment-specific, so decide whether to commit it based on your ALM flow.
+
+## Local Development
+
+Start the app locally:
+
+```bash
+npm run dev
+```
+
+The Power Apps Vite plugin prints a **Local Play** URL. Open that URL in the same browser profile you use for your Power Platform tenant so authentication and connector calls work as expected.
+
+If browser local network access restrictions appear, allow the browser prompt for the local endpoint. For iframe embedding scenarios, Microsoft recommends adding `allow="local-network-access"` to the iframe.
+
+## Data Access
+
+Code apps should not use the Dynamics webresource `AuthService`/`token.json` pattern. In a code app, the Power Apps host manages end-user authentication, and `@microsoft/power-apps` plus generated services perform data requests through Power Platform connectors and Dataverse references.
+
+The normal flow is:
+
+1. Create or identify the connection in [Power Apps](https://make.powerapps.com).
+2. Add the data source to this project with the Power Apps CLI.
+3. Import the generated model and service files from `src/generated`.
+4. Build and push the app with `npx power-apps push`.
+
+### Connect to Dataverse
+
+After `npx power-apps init`, add a Dataverse table by logical name:
+
+```bash
+npx power-apps add-data-source --api-id dataverse --resource-name <table-logical-name>
+```
+
+Example:
+
+```bash
+npx power-apps add-data-source --api-id dataverse --resource-name account
+```
+
+The CLI updates `power.config.json` and generates typed files under `src/generated/models` and `src/generated/services`. For example, after adding Accounts you can use the generated service:
+
+```ts
+import { AccountsService } from "./generated/services/AccountsService";
+import type { Accounts } from "./generated/models/AccountsModel";
+
+export async function listAccounts() {
+	const result = await AccountsService.getAll({
+		select: ["name", "accountnumber"],
+		top: 50,
+	});
+
+	return result.data ?? [];
+}
+
+export async function createAccount(name: string) {
+	const account = { name } satisfies Partial<Accounts>;
+	const result = await AccountsService.create(
+		account as Omit<Accounts, "accountid">,
+	);
+
+	return result.data;
+}
+```
+
+For Dataverse CRUD, use the generated service methods such as `create`, `get`, `getAll`, `update`, and `delete`. Prefer `select` when reading data so the app retrieves only the columns it needs.
+
+### Connect to Other Power Platform Connectors
+
+For non-Dataverse connectors, first create or locate the connection in Power Apps, then get the API name and connection ID. You can use the Power Apps maker portal or:
+
+```bash
+pac connection list
+```
+
+Add a non-tabular connector data source:
+
+```bash
+npx power-apps add-data-source --api-id <api-name> --connection-id <connection-id>
+```
+
+Add a tabular connector data source such as SQL or SharePoint:
+
+```bash
+npx power-apps add-data-source \
+	--api-id <api-name> \
+	--connection-id <connection-id> \
+	--resource-name <table-or-list-name> \
+	--dataset <dataset-name>
+```
+
+You can discover datasets and tables through the npm CLI:
+
+```bash
+npx power-apps list-datasets --api-id <api-name> --connection-id <connection-id>
+npx power-apps list-tables --api-id <api-name> --connection-id <connection-id> --dataset <dataset-name>
+```
+
+For ALM-friendly apps, prefer connection references instead of binding directly to a maker's connection:
+
+```bash
+npx power-apps list-connection-references --solution-id <solution-id>
+npx power-apps add-data-source \
+	--api-id <api-name> \
+	--connection-ref <connection-reference-logical-name> \
+	--solution-id <solution-id>
+```
+
+For tabular connectors, environment variable references can be used for dataset and table values:
+
+```bash
+npx power-apps add-data-source \
+	--api-id shared_sharepointonline \
+	--connection-id <connection-id> \
+	--dataset "@envvar:<site-environment-variable-schema-name>" \
+	--resource-name "@envvar:<list-environment-variable-schema-name>"
+```
+
+### Dataverse Actions and Functions
+
+Dataverse actions and functions use the newer npm-only commands:
+
+```bash
+npx power-apps find-dataverse-api --search "WhoAmI"
+npx power-apps add-dataverse-api --api-name WhoAmI
+```
+
+The command updates `power.config.json`, writes schema files, and generates a service such as:
+
+```ts
+import { WhoAmIService } from "./generated/services/WhoAmIService";
+
+const result = await WhoAmIService.WhoAmI();
+```
+
+### Runtime Context
+
+Use `getContext` from the Power Apps SDK when you need app, environment, user, query parameter, or session details:
+
+```ts
+import { getContext } from "@microsoft/power-apps/app";
+
+const context = await getContext();
+
+console.log(context.app.environmentId);
+console.log(context.user.userPrincipalName);
+console.log(context.host.sessionId);
+```
+
+This replaces most webresource-style assumptions about `window.Xrm`, parent frame context, or manually loaded local tokens.
+
+## Code Apps vs Webresources
+
+This target is intentionally different from the `webresource` target:
+
+- Webresources run inside Dynamics 365/model-driven app pages and can use `window.Xrm`; Code Apps run in the Power Apps host.
+- Webresources in this repo use `src/services/AuthService.ts` and `token.json` for local Dataverse Web API calls; Code Apps should use `@microsoft/power-apps`, `power.config.json`, and generated services.
+- The Code Apps scaffold removes webresource/Power Pages auth artifacts if they are present during generation.
+- Webresource builds are tuned for web resource upload with deterministic `main.css`/JS files; Code Apps builds are published with `npx power-apps push`.
+- Code Apps can use Power Platform connectors, connection references, environment variables, generated Dataverse CRUD services, and generated Dataverse action/function services as part of the platform hosting model.
+
+## Build and Deploy
+
+Build the production assets:
+
+```bash
+npm run build
+```
+
+Publish a new version to the environment configured in `power.config.json`:
+
+```bash
+npx power-apps push
+```
+
+When the push succeeds, the command returns a Power Apps URL where you can run the app. You can also open [Power Apps](https://make.powerapps.com) to play, share, or review the app details.
+
+## Solution and ALM Notes
+
+For healthy ALM, use a non-default solution. If your environment has a preferred solution, new code apps are saved there by default when deployed. To target a specific solution with the PAC CLI path, use:
+
+```bash
+pac code push --solutionName <solution-name>
+```
+
+If you already deployed the app and need to add it to a solution manually, open Power Apps, go to Solutions, choose the solution, then select Add existing > App > Code app.
+
+Microsoft's current npm CLI is the preferred path for new code app work. Older docs still show the PAC CLI flow:
+
+```bash
+pac auth create
+pac env select --environment <environment-id>
+pac code init --displayname "{{APP_NAME}}"
+npm run build | pac code push
+```
+
+Use the npm CLI unless you specifically need a PAC CLI option that has not moved yet.
+
+## Related Microsoft Documentation
+
+- [Power Apps code apps overview](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/overview)
+- [Quickstart with npm CLI](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/npm-quickstart)
+- [Code apps architecture](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/architecture)
+- [Connect your code app to data](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/connect-to-data)
+- [Connect your code app to Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/connect-to-dataverse)
+- [Add a Dataverse action or function](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/add-dataverse-action-function)
+- [Get context data](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/retrieve-context)
+- [Use environment variables in data sources](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/use-environment-variables)
+- [Application lifecycle management for code apps](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/alm)

package/templates/targets/code-apps/package.patch.json

@@ -0,0 +1,8 @@
+{
+	"dependencies": {
+		"@microsoft/power-apps": "^1.1.9"
+	},
+	"devDependencies": {
+		"@microsoft/power-apps-vite": "^1.0.2"
+	}
+}

package/templates/targets/code-apps/power.config.example.json

@@ -0,0 +1,14 @@
+{
+	"version": "1.0",
+	"appId": null,
+	"appDisplayName": "{{APP_NAME}}",
+	"region": "prod",
+	"environmentId": "<environment-id>",
+	"description": " ",
+	"buildPath": "./dist",
+	"buildEntryPoint": "index.html",
+	"localAppUrl": "http://localhost:5173",
+	"logoPath": "Default",
+	"connectionReferences": {},
+	"databaseReferences": {}
+}

package/templates/targets/code-apps/vite.config.patch.ts

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

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

@@ -4,7 +4,7 @@ function App() {
 	const { isAuthenticated, user } = useAuth(); //INFO: User is where the token information is stored (user?.idToken)
 
 	return (
-		<div className="ec:flex ec:flex-col ec:items-center ec:justify-center ec:h-screen ec:gap-4">
+		<div className="flex h-screen flex-col items-center justify-center gap-4">
 			{isAuthenticated ? (
 				<div>You are logged in</div>
 			) : (

package/templates/targets/webresource/README.md

@@ -270,10 +270,15 @@ Basic flow:
 npm run build
 ```
 
-2. Run the generator and point `--pcf-dir` at the generated PCF project directory:
+2. Run the generator from the webresource root. Point `--pcf-dir` at the webresource root and `--output` at the PCF project folder you want to generate:
 
 ```bash
-npx create-ec-app@latest --pcf-dir ./pcf/{{ControlName}} namespace {{EC}} --constructor {{ControlName}} --display-name "Control Name"
+npx create-ec-app@latest \
+  --pcf-dir . \
+  --output ./pcf/{{ControlName}} \
+  --namespace EC \
+  --constructor {{ControlName}} \
+  --display-name "Control Name"
 ```
 
 3. Install dependencies inside that generated PCF directory:
@@ -281,32 +286,41 @@ npx create-ec-app@latest --pcf-dir ./pcf/{{ControlName}} namespace {{EC}} --cons
 ```bash
 cd ./pcf/{{ControlName}}
 npm install
+npm run build
 ```
 
 This writes a standalone PCF project to the `--pcf-dir` folder. The generated control:
 
 - imports `src/App.tsx` directly instead of wrapping built HTML in an iframe
-- reuses the built stylesheet from `dist/main.css`
+- creates and imports `pcf-scoped.css` from the built `dist/main.css`
+- scopes every non-keyframe CSS selector under the generated PCF host selector
 - creates `src/runtime/types.ts` only if that file does not already exist
 - provides a runtime object with record context and `context.webAPI` access inside the generated PCF shell, following the `PcfBase` pattern
 - mounts your React app directly into the PCF container
 
-Typical conversion flow from inside a generated webresource project:
+Regenerate after app code or CSS changes by running the same sequence again from the webresource root:
 
 ```bash
-npm install
 npm run build
-npx create-ec-app@latest --pcf-dir ./pcf/FusionNotebookHost namespace EC --constructor FusionNotebookHost --display-name "Fusion Notebook Host"
+npx create-ec-app@latest \
+  --pcf-dir . \
+  --output ./pcf/FusionNotebookHost \
+  --namespace EC \
+  --constructor FusionNotebookHost \
+  --display-name "Fusion Notebook Host"
 cd pcf/FusionNotebookHost
 npm install
 npm run build
 ```
 
+Regeneration removes and recreates the PCF output folder, so keep durable app code in `src` and use generator templates or layers for repeatable PCF-specific changes.
+
 What gets generated:
 
 - a minimal PCF wrapper project under `pcf/<ConstructorName>`
 - a checked-in PCF shell stamped out from `create-ec-app/templates/pcf/base`
-- direct imports back to your webresource source and built CSS
+- direct imports back to your webresource source
+- a generated `pcf-scoped.css` file with CSS selectors scoped to the PCF control
 
 ## Notes
 

package/templates/ui/kendo/src/main.patch.tsx

@@ -4,7 +4,6 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import "@progress/kendo-theme-fluent/dist/all.css";
 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/ui/shadcn-ui/components.json

@@ -8,7 +8,7 @@
 		"css": "src/index.css",
 		"baseColor": "neutral",
 		"cssVariables": true,
-		"prefix": "ec"
+		"prefix": ""
 	},
 	"iconLibrary": "lucide",
 	"rtl": false,

package/templates/ui/shadcn-ui/src/index.patch.css

@@ -1,12 +1,9 @@
-@layer theme, base, components, utilities;
-
-@import "tailwindcss/theme.css" layer(theme) prefix(ec) important;
-@import "tailwindcss/utilities.css" layer(utilities) prefix(ec) important;
-@import "tw-animate-css/prefix";
+@import "tailwindcss";
+@import "tw-animate-css";
 @import "shadcn/tailwind.css";
 
 @custom-variant hover (&:hover);
-@custom-variant dark (&:is(.ec-app.dark *, .ec-app .dark *));
+@custom-variant dark (&:is(.dark *));
 
 @theme inline {
   --radius-sm: calc(var(--radius) - 4px);
@@ -46,7 +43,7 @@
   --color-sidebar-ring: var(--sidebar-ring);
 }
 
-.ec-app[data-ec-app-id="{{APP_NAME}}"] {
+:root {
   --radius: 0.625rem;
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
@@ -79,13 +76,9 @@
   --sidebar-accent-foreground: oklch(0.205 0 0);
   --sidebar-border: oklch(0.922 0 0);
   --sidebar-ring: oklch(0.708 0 0);
-
-  background: var(--background);
-  color: var(--foreground);
 }
 
-.ec-app[data-ec-app-id="{{APP_NAME}}"].dark,
-.ec-app[data-ec-app-id="{{APP_NAME}}"] .dark {
+.dark {
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
   --card: oklch(0.205 0 0);
@@ -120,20 +113,10 @@
 }
 
 @layer base {
-  :where(.ec-app, .ec-app *, .ec-app *::before, .ec-app *::after) {
-    box-sizing: border-box;
-  }
-
-  :where(.ec-app *) {
-    border-color: var(--border);
-    outline-color: color-mix(in oklab, var(--ring) 50%, transparent);
+  * {
+    @apply border-border outline-ring/50;
   }
-
-  :where(.ec-app button, .ec-app input, .ec-app select, .ec-app textarea) {
-    font: inherit;
-  }
-
-  :where(.ec-app button:not(:disabled), .ec-app [role="button"]:not(:disabled)) {
-    cursor: pointer;
+  body {
+    @apply bg-background text-foreground;
   }
 }

package/templates/base/src/runtime/EcAppShell.tsx

@@ -1,29 +0,0 @@
-import * as React from "react";
-
-export const EC_APP_SCOPE_CLASS = "ec-app";
-export const EC_APP_ID = "{{APP_NAME}}";
-export const EC_PCF_SCOPE_CLASS = "ec-pcf-shell-control";
-
-const EcPortalContainerContext = React.createContext<HTMLElement | null>(null);
-
-export function useEcPortalContainer() {
-	return React.useContext(EcPortalContainerContext);
-}
-
-export function EcAppShell({ children }: { children: React.ReactNode }) {
-	const [portalContainer, setPortalContainer] =
-		React.useState<HTMLDivElement | null>(null);
-
-	return (
-		<div
-			className={EC_APP_SCOPE_CLASS}
-			data-ec-app-id={EC_APP_ID}
-			data-ec-app-root=""
-		>
-			<EcPortalContainerContext.Provider value={portalContainer}>
-				{children}
-				<div data-ec-portal-root="" ref={setPortalContainer} />
-			</EcPortalContainerContext.Provider>
-		</div>
-	);
-}