{"id":32797277,"url":"https://github.com/casualchic/medusa-payload-cloudflare","last_synced_at":"2026-04-30T12:33:34.576Z","repository":{"id":321137149,"uuid":"1084627147","full_name":"casualchic/medusa-payload-cloudflare","owner":"casualchic","description":"Meridian: Production-ready Medusa + Payload CMS + Next.js 16 on Cloudflare Workers. Run a full e-commerce stack for $5/month.","archived":false,"fork":false,"pushed_at":"2025-10-28T00:27:51.000Z","size":1474,"stargazers_count":13,"open_issues_count":0,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-30T12:33:23.938Z","etag":null,"topics":["cloudflare","cloudflare-workers","d1-database","medusa","medusa-v2","medusajs","medusajs-v2","nextjs","opennext","opennext-template","opennextjs","payloadcms","r2"],"latest_commit_sha":null,"homepage":"https://github.com/casualchic/medusa-payload-cloudflare","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/casualchic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY_ENHANCEMENTS.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-28T00:00:53.000Z","updated_at":"2026-04-08T06:50:53.000Z","dependencies_parsed_at":"2025-10-28T02:39:50.222Z","dependency_job_id":null,"html_url":"https://github.com/casualchic/medusa-payload-cloudflare","commit_stats":null,"previous_names":["casualchic/medusa-payload-cloudflare"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/casualchic/medusa-payload-cloudflare","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casualchic%2Fmedusa-payload-cloudflare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casualchic%2Fmedusa-payload-cloudflare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casualchic%2Fmedusa-payload-cloudflare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casualchic%2Fmedusa-payload-cloudflare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/casualchic","download_url":"https://codeload.github.com/casualchic/medusa-payload-cloudflare/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casualchic%2Fmedusa-payload-cloudflare/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32465009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","cloudflare-workers","d1-database","medusa","medusa-v2","medusajs","medusajs-v2","nextjs","opennext","opennext-template","opennextjs","payloadcms","r2"],"created_at":"2025-11-06T00:00:36.429Z","updated_at":"2026-04-30T12:33:34.553Z","avatar_url":"https://github.com/casualchic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Meridian\n\n**The optimal point for edge commerce**\n\n\u003e Production-ready Medusa + Payload CMS + Next.js 15 on Cloudflare Workers\n\u003e Run a complete e-commerce stack for **$5/month** instead of $60/month\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Next.js 16](https://img.shields.io/badge/Next.js-15-black)](https://nextjs.org/)\n[![Payload CMS 3](https://img.shields.io/badge/Payload-3.61-blue)](https://payloadcms.com/)\n[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-orange)](https://workers.cloudflare.com/)\n\n---\n\n## 🎯 Why Meridian?\n\nJust as a **meridian** represents the sun's highest point—peak performance—**Meridian Commerce** achieves the optimal balance between enterprise features and startup costs.\n\nMeridian is the **first production-ready** implementation of Medusa.js e-commerce with Payload CMS running on Cloudflare Workers. We solved the hard problems so you don't have to:\n\n- ✅ **Virtual filesystem** for Cloudflare Workers (no traditional file access)\n- ✅ **Custom build patches** for Next.js compatibility\n- ✅ **Edge runtime middleware** that actually works\n- ✅ **D1 + R2 integration** with Payload CMS\n- ✅ **12x cost reduction** vs Vercel/Railway\n\n### The Problem We Solved\n\nTraditional e-commerce stacks require Docker, VPS hosting, or expensive serverless platforms ($40-60/month minimum). Running Next.js + Payload + Medusa on Cloudflare Workers requires solving several technical challenges:\n\n1. **No filesystem access** - Workers can't read files at runtime\n2. **Import.meta.url undefined** - Breaks many Node.js modules\n3. **Edge runtime limitations** - Dynamic code generation not allowed\n4. **Build tool incompatibilities** - OpenNext.js needs patching for Workers\n\nMeridian solves all of these with production-tested solutions.\n\n---\n\n## 💰 Cost Comparison\n\n| Platform | Monthly Cost | Notes |\n|----------|--------------|-------|\n| **Cloudflare Workers** (Meridian) | **~$5** | D1 + R2 + Workers included |\n| Vercel | $40-60 | Hobby limits too restrictive |\n| Railway | $50-80 | Per-service pricing |\n| DigitalOcean + Docker | $30-50 | Manual DevOps required |\n\n**The Meridian advantage:** Peak performance at the optimal price point.\n\n---\n\n## 🏗️ Architecture\n\n- **Frontend**: Next.js 15 with React 19 (Server Components)\n- **CMS**: Payload CMS 3.61 with D1 SQLite database\n- **E-commerce**: Medusa.js backend integration\n- **Storage**: Cloudflare R2 for media assets\n- **Database**: Cloudflare D1 (distributed SQLite)\n- **Deployment**: Cloudflare Workers via OpenNext.js\n\n### Key Technical Innovations\n\n1. **Virtual Filesystem** (`scripts/patch-middleware-handler.cjs`)\n   - Inlines all Next.js manifest files into the worker bundle\n   - Intercepts `fs.readFileSync()` calls to serve from memory\n   - Solves Workers' lack of traditional filesystem access\n\n2. **Build Patches**\n   - `scripts/patch-opentelemetry.cjs` - Removes telemetry (breaks in Workers)\n   - `scripts/patch-middleware-tracer.cjs` - Fixes middleware bundling\n   - `scripts/patch-middleware-handler.cjs` - Handles `import.meta.url` edge cases\n\n3. **Edge-Compatible Middleware**\n   - No dynamic code generation (`eval()`)\n   - Simplified routing for Workers runtime\n   - Compatible with Cloudflare's V8 isolates\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 20.19.0+\n- pnpm 9+ or 10+\n- Cloudflare account ($5 paid workers plan)\n- Medusa backend (use [Medusa Cloud](https://medusajs.com/cloud/) or self-host)\n\n### 1. Clone \u0026 Install\n\n```bash\ngit clone https://github.com/casualchic/medusa-payload-cloudflare.git meridian\ncd meridian\npnpm install\n```\n\n### 2. Configure Environment\n\n```bash\ncp .env.example .env.local\n```\n\nEdit `.env.local`:\n\n```bash\n# Generate with: openssl rand -hex 32\nPAYLOAD_SECRET=your-secret-here\n\n# Your Medusa backend URL\nNEXT_PUBLIC_MEDUSA_BACKEND_URL=https://your-medusa-backend.com\nNEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_your-key-here\n\n# Optional: For GDPR-compliant logging\nLOG_SECRET=your-log-secret-here\n```\n\n### 3. Local Development\n\n```bash\n# Start dev server\npnpm dev\n\n# Access at:\n# - Storefront: http://localhost:3000\n# - Admin Panel: http://localhost:3000/admin\n```\n\n### 4. Deploy to Cloudflare\n\n```bash\n# Authenticate\npnpm wrangler login\n\n# Deploy (first time - creates D1 database \u0026 R2 bucket)\nCLOUDFLARE_ENV=production pnpm run deploy\n\n# Subsequent deploys\nCLOUDFLARE_ENV=production pnpm run deploy:app\n```\n\n---\n\n## 📦 What's Included\n\n### ✅ Full E-commerce Features\n- Product catalog with variants (size, color, etc.)\n- Shopping cart with persistent state\n- Multi-region support\n- Customer accounts \u0026 order history\n- Payment integration (Stripe ready)\n- Responsive design (mobile-first)\n\n### ✅ Content Management\n- Payload CMS admin panel\n- Flexible page builder with 7 content blocks:\n  - Hero sections\n  - Product showcases\n  - Text content\n  - Image galleries\n  - CTAs\n  - Video embeds\n  - Testimonials\n- R2-backed media library\n- Version history \u0026 drafts\n\n### ✅ Production Ready\n- GitHub Actions CI/CD\n- Comprehensive test suite (unit, integration, E2E)\n- Security best practices\n- Performance optimizations\n- Monitoring setup guides\n\n---\n\n## 📚 Documentation\n\n### Getting Started\n- [Quick Start](#-quick-start) - Get running in 5 minutes\n- [Environment Variables](docs/environment-variables.md) - Complete configuration guide\n- [Deployment Guide](DEPLOYMENT_STEPS.md) - Step-by-step production deployment\n\n### Architecture \u0026 Development\n- [Pages Collection Guide](README_PAGES.md) - Flexible page builder system\n- [Next.js RSC Patterns](NEXTJS_RSC_PATTERNS.md) - Server Components architecture\n- [Deployment Learnings](DEPLOYMENT_LEARNINGS.md) - Key insights and solutions\n\n### Operations\n- [Monitoring Setup](docs/MONITORING_SETUP.md) - Alerts and dashboards\n- [Security Enhancements](docs/SECURITY_ENHANCEMENTS.md) - Production hardening\n- [Runbooks](docs/) - Operational procedures\n\n### Advanced\n- [Build Pipeline](BUILD_PIPELINE.md) - CI/CD and build optimization\n- [Advanced Optimizations](ADVANCED_OPTIMIZATIONS.md) - Performance tuning\n- [ADRs](docs/adr/) - Architectural decision records\n\n---\n\n## 🔧 Configuration\n\n### Cloudflare Resources\n\nMeridian automatically provisions:\n\n- **D1 Database** - For Payload CMS data\n- **R2 Bucket** - For media uploads\n- **Workers** - For serverless compute\n\nConfigure in `wrangler.jsonc`:\n\n```jsonc\n{\n  \"name\": \"your-project-name\",\n  \"compatibility_flags\": [\n    \"nodejs_compat\",\n    \"nodejs_compat_populate_process_env\"\n  ],\n  \"d1_databases\": [\n    {\n      \"binding\": \"DB\",\n      \"database_name\": \"your-db-name\"\n    }\n  ],\n  \"r2_buckets\": [\n    {\n      \"binding\": \"R2\",\n      \"bucket_name\": \"your-bucket-name\"\n    }\n  ]\n}\n```\n\n### Medusa Backend\n\nYou need a Medusa backend. Options:\n\n1. **Medusa Cloud** (recommended for quick start)\n   - Sign up at [medusajs.com/cloud](https://medusajs.com/cloud/)\n   - Get publishable key from admin dashboard\n\n2. **Self-hosted**\n   - Follow [Medusa documentation](https://docs.medusajs.com/)\n   - Deploy to Railway, Render, or DigitalOcean\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all tests\npnpm test\n\n# Individual test suites\npnpm test:unit        # Unit tests\npnpm test:int         # Integration tests\npnpm test:workflows   # GitHub Actions workflow tests\npnpm test:e2e         # End-to-end (Playwright)\n```\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Meridian is open source because we believe in sharing knowledge and building together.\n\n### How to Contribute\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`pnpm test`)\n5. Commit with conventional commits (`feat:`, `fix:`, `docs:`, etc.)\n6. Push and create a Pull Request\n\n### Areas We'd Love Help With\n\n- 🐛 Bug fixes and edge case handling\n- 📝 Documentation improvements\n- ✨ New Payload blocks/features\n- 🎨 UI/UX enhancements\n- 🔧 Cloudflare Workers optimizations\n- 🌍 Internationalization\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## 💼 Professional Services\n\nNeed help implementing Meridian for your business?\n\n- **Quick Start Package** - Setup assistance and configuration\n- **Custom Implementation** - Full design and integration\n- **Ongoing Support** - Maintenance and updates\n\nContact: [Your contact info - update this]\n\n---\n\n## 🗺️ Roadmap\n\n### Current (v1.0)\n- ✅ Production-ready deployment\n- ✅ Full e-commerce features\n- ✅ Payload CMS integration\n- ✅ Comprehensive documentation\n\n### Planned (v1.1+)\n- [ ] Payment provider examples (Stripe, PayPal)\n- [ ] Multi-language support (i18n)\n- [ ] Analytics integration guides\n- [ ] More Payload blocks (FAQ, Blog, etc.)\n- [ ] Storybook component library\n- [ ] One-click deploy button\n\nSee [Issues](https://github.com/casualchic/medusa-payload-cloudflare/issues) for full roadmap.\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\nBuilt with ❤️ by [Ian Rothfuss](https://github.com/ianrothfuss)\n\n---\n\n## 🙏 Acknowledgments\n\nMeridian builds on incredible open source projects:\n\n- [Next.js](https://nextjs.org/) - The React framework\n- [Payload CMS](https://payloadcms.com/) - Headless CMS\n- [Medusa.js](https://medusajs.com/) - E-commerce engine\n- [OpenNext.js](https://opennext.js.org/) - Cloudflare Workers adapter\n- [Cloudflare](https://cloudflare.com/) - Edge infrastructure\n\n---\n\n## ⭐ Star History\n\nIf Meridian helps you build better commerce experiences, please consider starring the repo!\n\n---\n\n## 🔗 Links\n\n- [Documentation](https://github.com/casualchic/medusa-payload-cloudflare/tree/main/docs)\n- [Issues](https://github.com/casualchic/medusa-payload-cloudflare/issues)\n- [Discussions](https://github.com/casualchic/medusa-payload-cloudflare/discussions)\n- [Changelog](CHANGELOG.md)\n\n---\n\n**Meridian** - *The optimal point for edge commerce*\n\n*Just as a meridian represents the sun's highest point, Meridian Commerce represents the peak of e-commerce efficiency—maximum performance at minimum cost.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasualchic%2Fmedusa-payload-cloudflare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcasualchic%2Fmedusa-payload-cloudflare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasualchic%2Fmedusa-payload-cloudflare/lists"}