Power Apps Code Apps

🗺️ Template to Production — in 10 Steps

From clicking Use this template on GitHub to promoting through Power Platform Pipelines, every Foundations team follows the same proven path. One picture says it all.

The rest of this guide explains how — section by section.

Start Here

The README and the Guide describe the same workflow. Pick the format that matches how you want to onboard.

What's Inside

The Foundations are an npm-published toolchain. The template repo gives you a clean starting point; the heavy lifting lives in @pacaf/* packages and is invoked from your editor by an AI coding agent.

Foundations monorepo (this repo)

If you're going to fork or contribute, this is the layout you'll see. End users do not need to clone this repo.

Your derived repo after the wizard runs

The wizard writes a Code App scaffold into your repo. Tooling stays in npm; only the project code and synced instruction files live in your repo.

Required Tech Stack

Every Code App uses this exact stack. No substitutions without team lead approval.

Narrative-First Planning Layer

Use this when the business problem is still being worked out and you want the eventual app to be more than a fast scaffold.

⚠️ Enable Code Apps in Your Environment

This is a prerequisite. Without it, pac code push will fail with "does not allow this operation for this Code app."

Steps

1. Open ↗ admin.powerplatform.microsoft.com
2. Select your development environment
3. Go to Settings → Features
4. Find "Code components for canvas apps" → toggle ON
5. Find "Allow publishing of canvas apps with code components" → toggle ON
6. Click Save
7. Wait ~1 minute for the setting to propagate

Auth for pac code push

pac code push requires a user auth profile — the BAP checkAccess API rejects SPN tokens. This is a one-time setup: create a user profile via device-code sign-in, and all subsequent pushes work silently. PAC CLI caches a refresh token that auto-renews (~90 days).

For CI/CD to test/production, use solution export/import instead of pac code push. Solution export and import both accept SPN auth and deploy the Code App, tables, connection references, and security roles as one atomic unit. See the deployment instructions for the full pipeline.

The Setup Wizard

This is the same quick-start flow described in the README. For non-trivial apps, pair it with the planning layer and prototype checkpoint before locking in schema and connectors.

npx @pacaf/wizard-ux@latest

All 10 Wizard Steps

Expand each step to see what happens and what you'll need.

# Browser wizard — navigate to Step 8 (Bind Connectors):
npx @pacaf/wizard-ux@latest

cd ../your-app
npm run dev:local    ← prototype with mock providers
npm run prototype:seed ← refresh prototype assets after editing the planning payload
npm run dev          ← connected mode once real providers exist
npx @pacaf/wizard-ux@latest --from 8 ← bind real connectors when ready
npm run deploy       ← deploy changes after the app has been registered

🧠 Plan Mode with Your Coding Agent

After the wizard finishes, don't jump to "add a table and a page." Switch your agent into plan mode and let it walk through the planning instruction files 00a → 00d before any schema or production code is written.

How to enter plan mode

What to say first

Describe what you want to build in business terms, not technical ones:

"I want to manage equipment loans across our field offices. Multiple regions, approvers, and an audit trail when assets go missing. Help me plan this out properly before we touch any code or schema."

What the planning workflow produces

When you're happy, exit plan mode and build

Switch your agent out of plan mode and say:

"Looks good. Provision the Dataverse schema, generate the connectors, and deploy to my dev environment."

Your agent will then drive schema provisioning (often via the Dataverse-skills plugin), rerun the wizard's connector-binding step, and run pnpm build + pac code push.

⚙️ pacaf-* CLIs

All helper scripts ship in the @pacaf/scripts package and are invokable via npx. Your derived repo adds them as a devDependency so your package.json scripts can use the bare pacaf-* names.

Creating Connections

Before moving from prototype mode into connected mode, create the actual connection instances in the Maker Portal.

A connection reference (created by the wizard in your solution) is a pointer that says "this app uses the Office 365 Users connector." The connection is the authenticated instance — the actual credential that makes it work. You need both.

Step-by-Step: Create a Connection

1. Go to ↗ make.powerapps.com and select your development environment
2. In the left nav, click Connections (under Data, or directly at make.powerapps.com/environments/<env-id>/connections)
3. Click + New connection
4. Search for the connector (e.g. Office 365 Users) and click it
5. Click Create and authenticate when prompted
6. Once created, click the connection to open its details
7. Copy the Connection ID from the browser URL — it's the GUID at the end:

   https://make.powerapps.com/environments/xxx/connections/shared_office365users/160ffdfd-aff5-4740-86a8-47209c1c608c/details

Common Connectors

Adding Data Sources (After Getting Connection IDs)

Preferred path: rerun the wizard when you are ready to connect real data.

# Browser wizard — navigate to Step 8:
npx @pacaf/wizard-ux@latest

The wizard will create the solution-level connection references, try to discover existing environment connections with pac connection list, and let you select one when matches are found.

# Dataverse tables (no connection ID needed):
pac code add-data-source -a dataverse -t myprefix_project

# Non-Dataverse connectors (connection ID required):
pac code add-data-source -a shared_office365users -c 160ffdfd-aff5-4740-86a8-47209c1c608c
pac code add-data-source -a shared_sharepointonline -c <YOUR_CONNECTION_ID>

pac auth create --name pp-myrepo-d-u-1a2b3c4d --environment https://org-dev.crm.dynamics.com --deviceCode
pac auth select --name pp-myrepo-d-u-1a2b3c4d

Portal Quick Links

Portals you may need during setup (Step 3 App Registration is the main manual step).

Local Development with Vite

Two modes: Prototype (mock providers, no Power Platform) and Connected (real connectors). Always start with Prototype mode.

npm run dev:local

npm run dev

When to Use Each Mode

Prototype Mode — How It Works

npm run dev:local runs VITE_USE_MOCK=true vite --port 3000. Vite serves your app at http://localhost:3000 with sub-second HMR — save a file, see it instantly. Refresh prototype contracts and mock providers anytime with npm run prototype:seed after editing dataverse/planning-payload.json.

Need the full sequence from planning payload through prototype review to real providers? Open the prototype-first golden path.

Mock Data Pattern

Every hook that calls a connector checks VITE_USE_MOCK to decide whether to return mock data or make a real call:

// src/hooks/useProjects.ts
import { useQuery } from '@tanstack/react-query';
import { mockProjects } from '@/mockData/projects';
import { ProjectService } from '@/generated/services/ProjectService';

const USE_MOCK = import.meta.env.DEV && import.meta.env.VITE_USE_MOCK === 'true';

export function useProjects() {
  return useQuery({
    queryKey: ['projects'],
    queryFn: USE_MOCK
      ? () => Promise.resolve({ data: mockProjects })
      : () => ProjectService.getAll(),
  });
}

Connected Mode — Prerequisites

• PAC auth profiles created (pac org who shows org, no popup)
• Data source added: pac code add-data-source
• At least one data source added with pac code add-data-source so src/generated/ exists
• power.config.json exists next to package.json

Vite Configuration

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig(({ command }) => ({
  base: command === 'build' ? './' : '/', // CRITICAL for Code Apps
  plugins: [react()],
  server: {
    port: 3000,          // Required by Power Apps SDK
    strictPort: true,    // Fail if 3000 occupied (don't silently use 3001)
    open: true,          // Auto-open browser
  },
  resolve: {
    alias: { '@': path.resolve(__dirname, './src') },
  },
  build: { outDir: 'dist' },
}));

base: './' is required for production builds. Power Apps serves your bundle from a nested, non-root path. Without relative base, all asset URLs are absolute (/assets/index-abc.js) which 404 → blank screen.

Vite Environment Variables

Only variables prefixed with VITE_ are exposed to client code via import.meta.env. This is a security feature — Power Platform credentials (PP_*) are never leaked to the browser.

Troubleshooting

See .github/instructions/01-scaffold.instructions.md for complete Vite config, mock data patterns, and mutation mocking.

Connectors

Code Apps cannot make direct HTTP calls. All data access goes through Power Platform connectors, but connector binding should happen after prototype validation.

Adding a Data Source

Recommended order: prototype first, then rerun the wizard from the dedicated connector step once the planning payload is stable.

# Browser wizard — navigate to Step 8:
npx @pacaf/wizard-ux@latest

# Dataverse (no connection ID needed):
pac code add-data-source -a dataverse -t myprefix_project

# Non-Dataverse connectors (connection ID required — see Creating Connections):
pac code add-data-source -a shared_office365users -c <CONNECTION_ID>

Wrapping Generated Code with TanStack Query

// src/hooks/useProjects.ts
import { useQuery } from '@tanstack/react-query';
import { SqlService } from '@/generated/services/SqlService';

export function useProjects() {
  return useQuery({
    queryKey: ['projects'],
    queryFn: () => SqlService.getProjects(),
    staleTime: 5 * 60 * 1000,  // Connector calls aren't free
  });
}

See .github/instructions/02-connectors.instructions.md for full patterns including Dataverse OData queries, pagination, and error handling.

Components

React + Fluent UI v9 patterns for consistent, accessible UI.

Key Principles

• Functional components only (no class components)
• Single responsibility — files under ~150 lines
• Fluent UI v9 (@fluentui/react-components) for all controls
• Style with makeStyles + design tokens — never raw CSS values
• Local state (useState) for UI; Server state (TanStack Query) for data
• Colocate tests: ProjectCard/ProjectCard.tsx + ProjectCard.test.tsx

Provider Stack (main.tsx)

<QueryClientProvider>
  <FluentProvider theme={webLightTheme}>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </FluentProvider>
</QueryClientProvider>

See .github/instructions/03-components.instructions.md for layout patterns, data tables, error boundaries, and accessibility guidance.

Deployment & CI/CD

From local dev to production with GitHub Actions.

Flow

Feature Branch → PR → CI (lint + test + build) → Merge → Deploy to Dev
                                                              ↓
                                          Deploy to Test → Deploy to Prod

Manual Deploy (Dev Only)

npm run deploy

GitHub Secrets Required

Per-Environment Variable

See .github/instructions/04-deployment.instructions.md for CI/CD workflow YAML, solution management, and deployment settings files.

Testing

Vitest for units, Playwright for E2E, MSW for connector mocking.

What to Test

• ✅ Component rendering with different states
• ✅ User interactions (clicks, form submissions)
• ✅ Custom hooks wrapping connectors
• ✅ Utility functions with business logic
• ❌ Generated files (src/generated/)
• ❌ Fluent UI internals

See .github/instructions/05-testing.instructions.md for config files, MSW handler patterns, and CI integration.

Security

Auth is automatic. Your job: don't leak secrets, validate inputs, sanitize output.

Required .gitignore Entries

.env.local
.env.*.local
.pac/
auth.json
node_modules/
dist/
coverage/
.wizard-state.json

Input Validation

// Always validate user inputs
if (/<script/i.test(name)) return 'Invalid characters';
if (name.length > 200) return 'Max 200 characters';

// Never use dangerouslySetInnerHTML with user data
<Text>{project.description}</Text>  // Safe — React escapes

See .github/instructions/06-security.instructions.md for error message guidelines, DLP handling, and code review checklist.

Dataverse Schema

Tables, columns, option sets — and the rules that prevent expensive mistakes.

Golden Rules

• Always global option sets — never inline choices
• Always use publisher prefix — mybrn_ideastatus, not ideastatus
• Option values start at 100000000 — never 0 or 1
• Add, don't delete — removing a live option value breaks existing records silently
• Create inside the solution — never from the top-level Tables view

Naming Convention

✅  mybrn_ideastatus          (prefix + descriptive, all lowercase)
✅  mybrn_complexitylevel
❌  IdeaStatus                (no prefix — collides)
❌  mybrn_IdeaStatus          (camelCase — use all lowercase)

See .github/instructions/07-dataverse-schema.instructions.md for column creation patterns, relationship modeling, and the complete provisioning sequence.

🔌 Dataverse-skills Plugin

Strategic alignment with microsoft/Dataverse-skills — the best-practice mechanism for agent-driven Dataverse operations.

Why a plugin instead of built-in scripts?

Foundations is a Code App template — it owns the planning workflow, scaffold, connector adapters, and form field patterns. Dataverse environment operations (schema provisioning, data seeding, solution lifecycle, admin tasks) are better served by a dedicated, community-maintained plugin that evolves with the Dataverse SDK and MCP server.

Scope Split

Install

The wizard (Step 10) detects your coding agent and shows the correct command:

GitHub Copilot:  /plugin install dataverse@awesome-copilot
Claude Code:     /plugin install dataverse@claude-plugins-official

Prerequisites: python3 + pip install PowerPlatform-Dataverse-Client pandas

How It Flows Together

1. Plan the business problem (00a → 00c) → dataverse/planning-payload.json
2. Discover existing schema first → agent uses list_tables / describe_table from the plugin
3. Provision schema → agent uses dv-metadata from the plugin
4. Register data sources → pac code add-data-source generates TypeScript SDK
5. Build the UI with generated services, Fluent UI, TanStack Query

Copilot Studio Agent Integration

Add a conversational AI agent to your Code App using the Microsoft Copilot Studio connector.

Setup Steps

1. Create & publish your agent in ↗ Copilot Studio
2. Get the agent name from Channels → Web app → connection string (e.g. cr3e1_customerSupportAgent)
3. Create a connection in make.powerapps.com → Connections → + New → "Microsoft Copilot Studio"
4. Add the data source:

   pac code add-data-source -a "shared_microsoftcopilotstudio" -c <connectionId>

5. Import & call the generated service in your React code

Invoking the Agent

import { CopilotStudioService } from '@/generated/services/CopilotStudioService';

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: "What is the status of my order?",
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_customerSupportAgent",
});

if (response.data.completed) {
  console.log(response.data.lastResponse);
}

Request Parameters

Response Structure

Prototype Mode (Mock Data)

When running npm run dev:local, create a mock that simulates agent responses with realistic delays. The instruction file includes a complete mock implementation and shows how to wire it into useCopilotAgent with the VITE_USE_MOCK toggle.

See .github/instructions/08-copilot-studio.instructions.md for the complete hook, chat UI component, structured I/O patterns, and troubleshooting.

Naming Conventions

Quick reference for file, component, and Dataverse naming.

Common Connector IDs

Use these when creating deployment settings files or connection references.

To find Connection IDs in the Power Apps Maker Portal, look at the URL after creating a connection:

https://make.powerapps.com/environments/xxx/connections/shared_office365users/CONNECTION_ID/details

What's Next

After the wizard finishes, here's your daily workflow and common commands.

Daily Development

Deploying

pac auth create --name pp-myrepo-d-u-1a2b3c4d --environment <your-env-url> --deviceCode
pac auth select --name pp-myrepo-d-u-1a2b3c4d
pac code push

Connectors & Connection References

The wizard auto-creates connection references in your solution so they travel across environments. This happens in an explicit later connector-binding pass, not during the initial scaffold.

--apiId (-a) is always required for manual adds — there is no interactive picker in the CLI. The wizard compensates for this by discovering existing environment connections with pac connection list and letting you select one when possible. See the Connector IDs table above for common API IDs.

Re-running the Wizard

The wizard stores progress in .wizard-state.json and lets you jump directly to any step from the step navigator.

Keeping Foundations Up to Date

When new @pacaf/* versions ship, refresh tooling and synced instruction files in your derived repo:

Your application code is never touched. Only synced foundations files and the two devDependency versions in your package.json change.

Setting Up CI/CD

See .github/instructions/04-deployment.instructions.md for full details. You'll need:

• GitHub secrets: PP_APP_ID, PP_CLIENT_SECRET, PP_TENANT_ID
• Environment variable per target: POWER_PLATFORM_URL