Development Workflow

Environment Setup

1. •Copy .env-example to .env
2. •Configure ChurchTools URL and extension key:
   code

   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:

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