Development Workflow

Environment Setup

• Copy .env-example to .env

• 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 Cookie Issues

Safari has stricter cookie handling. Solutions:

• Use Vite proxy so API calls go through local server

• Run dev server with HTTPS using mkcert

Testing Checklist

• Start dev server: npm run dev

• Check browser console for errors

• Test responsive design

• Verify ChurchTools integration

• Build test: npm run build

• Deploy test: npm run deploy

Deployment Process

• Format code: npm run prettier:write

• Build: npm run build

• Package: npm run deploy

• Upload .zip to ChurchTools Admin > Extensions

• Configure extension settings

• 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