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 repo contains instruction files, helper scripts, and a setup wizard that work together.

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.

cd my-app/wizard && npm install && node index.mjs

cd my-app && npm run wizard:ux

All 9 Wizard Steps

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

# Terminal wizard:
node wizard/index.mjs --from 8

# Browser wizard — navigate to Step 8 (Bind Connectors):
npm run wizard:ux

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
node wizard/index.mjs --from 8 ← bind real connectors when ready
npm run deploy       ← deploy changes after the app has been registered

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.

# Terminal wizard:
node wizard/index.mjs --from 8

# Or use the browser wizard — navigate to Step 8:
npm run wizard:ux

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.

# Terminal wizard:
node wizard/index.mjs --from 8

# Or use the browser wizard — navigate to Step 8:
npm run wizard:ux

# 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 idempotent setup scripts, column creation patterns, and relationship modeling.

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 now 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

Both the terminal wizard and the browser wizard (npm run wizard:ux) share .wizard-state.json, so you can switch between them freely. The browser wizard lets you jump directly to any step from the step navigator.

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