development-workflow

bwl21's avatarfrom bwl21

Apply when setting up the development environment, running dev server, building, testing, or deploying the extension. Covers npm commands, CORS configuration, debugging, and deployment to ChurchTools.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025
[Developer Tools]

When & Why to Use This Skill

This Claude skill provides a comprehensive development workflow for building, testing, and deploying ChurchTools extensions. It streamlines the entire lifecycle by automating environment setup, managing local development servers, and providing standardized procedures for CORS configuration and production deployment, significantly reducing the barrier to entry for extension developers.

Use Cases

  • Initial environment setup: Quickly configuring .env files and local dependencies for a new ChurchTools extension project.
  • Local development and debugging: Running a Vite-powered dev server and troubleshooting iframe-specific issues like Safari cookie restrictions and CORS errors.
  • API Integration testing: Verifying the churchtoolsClient connection and testing API endpoints directly within the extension context.
  • Production deployment: Executing a reliable build-and-package pipeline to generate ZIP files ready for upload to the ChurchTools administration interface.
namedevelopment-workflow
descriptionApply when setting up the development environment, running dev server, building, testing, or deploying the extension. Covers npm commands, CORS configuration, debugging, and deployment to ChurchTools.

Development Workflow

Environment Setup

  1. Copy .env-example to .env
  2. Configure ChurchTools URL and extension key:
    VITE_KEY=your-extension-key
VITE_CHURCHTOOLS_URL=https://your-instance.church.tools

Development Commands

npm run dev           # Start dev server with hot-reload (port 5173)
npm run build         # Production build
npm run preview       # Preview production build
npm run deploy        # Build and package for ChurchTools
npm run prettier:write # Format code

CORS Configuration

For local development, configure CORS in ChurchTools:

  • Admin > System Settings > Integrations > API > Cross-Origin Resource Sharing
  • Add http://localhost:5173

Safari has stricter cookie handling. Solutions:

  1. Use Vite proxy so API calls go through local server
  2. Run dev server with HTTPS using mkcert

Testing Checklist

  1. Start dev server: npm run dev
  2. Check browser console for errors
  3. Test responsive design
  4. Verify ChurchTools integration
  5. Build test: npm run build
  6. Deploy test: npm run deploy

Deployment Process

  1. Format code: npm run prettier:write
  2. Build: npm run build
  3. Package: npm run deploy
  4. Upload .zip to ChurchTools Admin > Extensions
  5. Configure extension settings
  6. Test in production

Debugging

Browser console tests:

// Test API connection
churchtoolsClient.get('/whoami').then(console.log).catch(console.error)

// Check extension context
console.log('Extension context:', {
  url: window.location.href,
  parent: window.parent !== window,
  churchtoolsClient: !!window.churchtoolsClient
})

Build Output

Check build output:

ls -la dist/
ls -lh dist/assets/

Extension Context

  • Extensions run in iframe context
  • Use window.parent.postMessage for communication with ChurchTools
  • Access ChurchTools API via churchtoolsClient