Prospect Management Code App - Contacts Feature

Overview

This is a Power Platform Code App built with React and TypeScript that provides full CRUD functionality for managing contacts in Dataverse.

Project Structure

.
├── src/                              # Source code
│   ├── components/                   # React components
│   │   └── Contacts/                 # Contact management components
│   │       ├── ContactsList.tsx      # Table view of contacts
│   │       ├── ContactForm.tsx       # Add/Edit contact form
│   │       ├── ContactDetail.tsx     # Detail view modal
│   │       ├── SearchBar.tsx         # Search and filter functionality
│   │       ├── ContactsList.css      # Contacts list styling
│   │       ├── ContactForm.css       # Contact form styling
│   │       ├── ContactDetail.css     # Detail view styling
│   │       └── SearchBar.css         # Search bar styling
│   ├── pages/                        # Page-level components
│   │   ├── ContactsPage.tsx          # Main page orchestrator
│   │   └── ContactsPage.css          # Main page styling
│   ├── hooks/                        # Custom React hooks
│   │   └── useContacts.ts            # Contacts management hook
│   ├── Models/                       # TypeScript interfaces and types
│   │   └── Contact.ts                # Contact data models
│   ├── Services/                     # API services
│   │   └── ContactService.ts         # Dataverse API service
│   ├── utils/                        # Utility functions
│   │   ├── powerPlatformInit.ts      # Power Platform initialization
│   │   └── mockData.ts               # Mock data for development
│   ├── styles/                       # Global stylesheets
│   │   ├── App.css                   # App styling
│   │   └── index.css                 # Global styles
│   ├── App.tsx                       # Root component
│   └── main.tsx                      # React entry point
├── public/                           # Static assets
├── .power/                           # Power Platform configuration
│   └── schemas/                      # Generated schemas
├── dist/                             # Production build output (generated)
├── node_modules/                     # Dependencies (generated)
├── index.html                        # HTML template
├── vite.config.ts                    # Vite build configuration
├── tsconfig.json                     # TypeScript configuration
├── tsconfig.node.json                # TypeScript config for Vite
├── package.json                      # Project dependencies and scripts
├── .env.local                        # Environment variables (local)
├── .eslintrc.json                    # ESLint configuration
├── .gitignore                        # Git ignore rules
├── power.config.json                 # Power Platform project config
├── README.md                         # This file
└── LICENSE                           # MIT License

Key Directories Explained

• src/components: Reusable React UI components
• src/Services: API layer for Dataverse communication
• src/hooks: Custom React hooks for shared logic
• src/utils: Helper functions and mock data
• .power: Power Platform-generated metadata
• dist: Production-ready build (created by npm run build)

Features

• View Contacts - Display all contacts in a table format
• Create Contacts - Add new contacts with form validation
• Edit Contacts - Update existing contact information
• Delete Contacts - Remove contact records
• Search Contacts - Real-time search by name or email
• Detail View - Modal with full contact information
• Responsive Design - Works on desktop, tablet, and mobile

Getting Started

Prerequisites

• Node.js 16+
• npm or yarn
• Power Platform CLI installed: npm install -g pac
• Power Platform environment with Dataverse

Installation

# Navigate to the app directory
cd solutions/apps

# Install dependencies
npm install

Development

# Start development server (runs on http://localhost:3000)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Configuration

Power Platform Connection

The app reads configuration from power.config.json:

{
  "environmentId": "0f5282a0-f08f-edf1-b174-449fed9eec06",
  "connectionReferences": {
    "shared_commondataserviceforapps": {
      "apiId": "shared_commondataserviceforapps",
      "displayName": "Dataverse"
    }
  }
}

Environment Variables

Create a .env.local file for development:

VITE_API_URL=http://localhost:8080
VITE_ENVIRONMENT_URL=https://your-environment.crm.dynamics.com

Troubleshooting

Error: ECONNREFUSED on /api/data/v9.2/contacts

Cause: The dev server cannot connect to the Power Platform backend.

Solutions:

1. Running in Power Apps (Recommended):

   • Push the app to Power Platform using PAC CLI: pac code push
   • The app will automatically use the Power Platform authentication context

2. Local Development:

   • Start the PAC connection proxy: pac code run (in another terminal)
   • This starts the proxy at http://localhost:8080
   • The Vite dev server will forward API requests through this proxy

3. Error: util._extend deprecated:

   • This is a deprecation warning from the http-proxy library
   • It's not critical and can be safely ignored
   • The app will still function properly

No contacts appearing

• Check that contacts exist in your Dataverse environment
• Verify you have read access to the contacts table
• Check browser console for error messages
• Ensure the environment URL is correct in power.config.json

Authentication errors

• If getting 401 errors, the Power Platform authentication context is not available
• Make sure the app is running within the Power Apps environment
• Check that your user has appropriate permissions in Dataverse

API Integration

Contact Service Methods

// Get all contacts
ContactService.getContacts({ orderby: 'lastname asc' })

// Get single contact
ContactService.getContact(contactId)

// Create contact
ContactService.createContact({ firstname, lastname, email })

// Update contact
ContactService.updateContact({ contactid, ...data })

// Delete contact
ContactService.deleteContact(contactId)

// Search contacts
ContactService.searchContacts('john')

Building and Deploying

Build the App

npm run build

This creates a production-optimized build in the dist/ folder.

Deploy to Power Platform

# Build the app
npm run build

# Push to Power Platform
pac code push

The app will be deployed to your Power Platform environment and can be accessed through the Power Apps portal.

Development Tips

1. Hot Module Replacement: Changes to components automatically reload without losing state
2. TypeScript: Full type safety for models and services
3. ESLint: Code quality checks with npm run lint
4. Path Aliases: Use @components, @services, etc. for cleaner imports

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Mobile browsers (iOS Safari, Chrome Mobile)

Performance Considerations

• Contacts are paginated (top 100 by default)
• Search is performed client-side after fetching
• Consider adding server-side pagination for large datasets
• CSS is optimized with minimal dependencies

Contributing

We welcome contributions! Here's how to get involved:

Getting Started

1. Fork the repository on GitHub

   • Click the "Fork" button in the top-right corner of the repository
   • This creates a copy of the repo under your GitHub account

2. Clone your fork

   git clone https://github.com/<your-username>/powerplatform-codeapps.git
   cd powerplatform-codeapps

3. Add upstream remote (to sync with original repo)

   git remote add upstream https://github.com/nipaul/powerplatform-codeapps.git

4. Create a feature branch

   git checkout -b feature/your-feature-name

Development Guidelines

1. Follow TypeScript strict mode rules

   • Add proper types for all variables and function parameters
   • No any types unless absolutely necessary

2. Code Quality

   • Run npm run lint to check code quality
   • Follow existing code patterns and conventions
   • Keep functions small and focused

3. Component Development

   • Create reusable functional components
   • Use React Hooks for state management
   • Include proper JSDoc comments for complex logic
   • Add prop types/interfaces

4. Testing

   • Test with both mock data and real Dataverse
   • Verify responsive design on mobile/tablet
   • Test error scenarios

5. Commit Messages

   • Use clear, descriptive commit messages
   • Reference issues when relevant: Fix: #123 description
   • Examples:
     • feat: Add contact export functionality
     • fix: Correct email validation regex
     • docs: Update README with new features
     • refactor: Simplify ContactService methods

Pull Request Process

1. Keep your branch updated

   git fetch upstream
   git rebase upstream/main

2. Push your changes

   git push origin feature/your-feature-name

3. Create a Pull Request

   • Go to your fork on GitHub
   • Click "New Pull Request"
   • Select main as the base branch
   • Fill in the PR title and description:
     • What changes you made
     • Why the changes are needed
     • How to test the changes
     • Any relevant issue numbers

4. Code Review

   • Respond to feedback from maintainers
   • Make requested changes by pushing to the same branch
   • Keep discussions respectful and constructive
   • The PR will be merged once approved

Areas We Need Help With

• Features: New contact properties, bulk operations, export to Excel
• UI/UX: Improved styling, accessibility improvements, responsive design
• Documentation: Guides, troubleshooting, code examples
• Performance: Optimization, caching, data loading improvements
• Bug Fixes: Found a bug? Create an issue and submit a fix

Reporting Issues

Found a bug? Create an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected behavior vs actual behavior
• Your environment (OS, Node version, browser)
• Screenshots if applicable

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License Summary:

• ✅ You can use this for commercial and private purposes
• ✅ You can modify and distribute the code
• ✅ You must include the original license and copyright notice
• ❌ The authors are not liable for any issues or damages

For the complete license text, see LICENSE

Support

For issues with:

• Power Platform: Check Power Platform documentation
• React: Visit React documentation
• TypeScript: Check TypeScript handbook