- name
- development-workflow
- description
- 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.
Development Workflow
Environment Setup
- Copy
.env-exampleto.env - Configure ChurchTools URL and extension key:
VITE_KEY=your-extension-key
VITE_CHURCHTOOLS_URL=https://your-instance.church.toolsDevelopment 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 codeCORS 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
.zipto 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.postMessagefor communication with ChurchTools - Access ChurchTools API via
churchtoolsClient