{"id":49520979,"url":"https://github.com/brendadeeznuts1111/alchmenyrun","last_synced_at":"2026-05-01T23:39:54.213Z","repository":{"id":320785117,"uuid":"1083343433","full_name":"brendadeeznuts1111/alchmenyrun","owner":"brendadeeznuts1111","description":"Batteries-included Cloudflare infrastructure toolkit with Alchemy - Durable Objects, Workflows, WebSocket chat, MCP integration, and reusable building blocks","archived":false,"fork":false,"pushed_at":"2025-10-28T07:52:37.000Z","size":2065,"stargazers_count":1,"open_issues_count":21,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T23:39:52.363Z","etag":null,"topics":["alchemy","building-blocks","bun","cloudflare","d1","durable-objects","infrastructure-as-code","infrastructure-kit","mcp","r2","react","typescript","websocket","workers","workflows"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brendadeeznuts1111.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-25T20:28:57.000Z","updated_at":"2026-03-29T20:19:19.000Z","dependencies_parsed_at":"2025-10-25T22:21:17.934Z","dependency_job_id":"a38afbff-2c04-4ce1-ab00-662513301676","html_url":"https://github.com/brendadeeznuts1111/alchmenyrun","commit_stats":null,"previous_names":["brendadeeznuts1111/alchmenyrun"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/brendadeeznuts1111/alchmenyrun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendadeeznuts1111%2Falchmenyrun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendadeeznuts1111%2Falchmenyrun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendadeeznuts1111%2Falchmenyrun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendadeeznuts1111%2Falchmenyrun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brendadeeznuts1111","download_url":"https://codeload.github.com/brendadeeznuts1111/alchmenyrun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendadeeznuts1111%2Falchmenyrun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32517232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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":["alchemy","building-blocks","bun","cloudflare","d1","durable-objects","infrastructure-as-code","infrastructure-kit","mcp","r2","react","typescript","websocket","workers","workflows"],"created_at":"2026-05-01T23:39:53.168Z","updated_at":"2026-05-01T23:39:54.200Z","avatar_url":"https://github.com/brendadeeznuts1111.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alchemy Cloudflare Demo\n\n[![CI Matrix](https://github.com/brendadeeznuts1111/alchmenyrun/actions/workflows/ci-matrix.yml/badge.svg)](https://github.com/brendadeeznuts1111/alchmenyrun/actions/workflows/ci-matrix.yml)\n[![Release Feed](https://img.shields.io/badge/rss-releases-orange)](https://github.com/brendadeeznuts1111/alchmenyrun/releases.atom)\n\nA comprehensive Cloudflare infrastructure demo built with Alchemy, showcasing TypeScript-native Infrastructure as Code with Workers, D1 database, R2 storage, KV cache, Durable Objects, and Workflows.\n\n**Live Demo**: https://cloudflare-demo-website-prod.utahj4754.workers.dev\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n1. **Install Bun**\n   ```bash\n   curl -fsSL https://bun.sh/install | bash\n   ```\n\n2. **Cloudflare Account**\n   - Sign up at [cloudflare.com](https://cloudflare.com)\n   - Get your Account ID from the dashboard\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/brendadeeznuts1111/alchmenyrun.git\ncd alchmenyrun\n\n# Install dependencies\nbun i\n```\n\n### Configuration\n\n1. **Configure Alchemy Profile**\n   ```bash\n   bun alchemy configure\n   ```\n   \n   This will create a profile configuration in `~/.alchemy/config.json`\n\n2. **Login to Cloudflare**\n   ```bash\n   bun alchemy login\n   ```\n   \n   This will store your Cloudflare credentials securely in `~/.alchemy/credentials/default/cloudflare.json`\n\n3. **Set Environment Variables (Optional)**\n   \n   Create a `.env` file for local development:\n   ```bash\n   # Alchemy Configuration (optional - can use profiles)\n   ALCHEMY_PASSWORD=your_encryption_password\n   \n   # Override profile if needed\n   # ALCHEMY_PROFILE=prod\n   # CLOUDFLARE_PROFILE=prod\n   ```\n\n**Note**: Alchemy profiles are the recommended way to manage credentials. They're stored locally in `~/.alchemy/` and behave similarly to AWS profiles. Environment variables are only needed for the encryption password and profile overrides.\n\n### Development\n\n```bash\n# Start development server with hot reload\nbun run alchemy:dev\n```\n\nYour application will be available locally with live updates as you edit your code.\n\n### Deployment\n\n```bash\n# Deploy to your personal stage\nbun run deploy\n\n# Deploy to production (main branch)\nbun run deploy:prod\n```\n\n## 📁 Project Structure\n\n```\n├── src/\n│   ├── backend/           # Cloudflare Worker code\n│   │   ├── server.ts      # Main worker entrypoint\n│   │   ├── durable-object.ts # Durable Object for chat\n│   │   └── workflow.ts    # Workflow definitions\n│   ├── frontend/          # React frontend application\n│   │   ├── components/    # React components\n│   │   ├── App.tsx        # Main app component\n│   │   └── main.tsx       # Frontend entrypoint\n│   ├── tests/             # Test files following Alchemy patterns\n│   │   ├── integration.test.ts\n│   │   ├── unit.test.ts\n│   │   └── util.ts\n│   ├── db/               # Database schema and utilities\n│   │   ├── schema.ts     # Drizzle ORM schema\n│   │   └── index.ts      # Database utilities\n│   └── mcp/              # Model Context Protocol implementation\n├── docs/                 # Comprehensive documentation\n│   ├── cloudflare.md     # Provider documentation\n│   └── guides/           # Getting started guides\n├── scripts/              # Helper scripts\n│   └── pre-commit.sh     # Pre-commit automation\n├── alchemy.run.ts        # Infrastructure definition\n├── package.json          # Dependencies and scripts\n└── README.md            # This file\n```\n\n## 🛠️ Features\n\n### Infrastructure Components\n\n- **Cloudflare Workers**: Serverless compute at the edge\n- **D1 Database**: SQLite database with Drizzle ORM\n- **R2 Storage**: Object storage for file uploads\n- **KV Cache**: Key-value storage for caching\n- **Durable Objects**: Stateful compute for real-time features\n- **Workflows**: Orchestration for multi-step processes\n\n### Application Features\n\n- **Real-time Chat**: WebSocket-based chat with Durable Objects\n- **File Upload/Download**: R2 storage integration\n- **User Management**: CRUD operations with D1 database\n- **Caching Layer**: KV storage for performance\n- **API Endpoints**: RESTful API with proper error handling\n- **React Frontend**: Modern UI with Tailwind CSS\n\n## 🧪 Testing\n\nFollows Alchemy's testing best practices:\n\n```bash\n# Run all tests\nbun test\n\n# Run integration tests\nbun test:integration\n\n# Run specific test\nbun vitest ./src/tests/integration.test.ts -t \"should create and deploy website\"\n\n# Run tests in watch mode\nbun test:watch\n```\n\n## 📚 Documentation\n\n- **[Provider Documentation](./docs/cloudflare.md)** - Complete resource reference\n- **[Getting Started Guide](./docs/guides/cloudflare.md)** - Step-by-step tutorial\n- **[Concepts Guide](./docs/concepts.md)** - Phase, Secret, Bindings, and Resources\n- **[Profiles Guide](./docs/profiles.md)** - Managing credentials with Alchemy profiles\n- **[Contributing Guide](./CONTRIBUTING.md)** - Development guidelines\n\n## 🔄 Development Workflow\n\n🔥 **Perfect development workflow locked in!**\n\n### ⚡ **Your 3-Step Process**\n\n```bash\n# 1️⃣ Development\nbun run alchemy:dev  # Code → hot reload → test\n\n# 2️⃣ Before commit  \nbun format           # Auto-fix formatting\nbun run test         # Verify all tests pass\n\n# 3️⃣ Ship it\ngit commit -m \"feat: new feature\"  # Pre-commit hook validates\ngit push origin feature           # PR → preview URL\n```\n\n### 🎯 **What Makes This Flow Powerful**\n\n- **Instant Feedback**: Hot reload shows changes immediately\n- **Zero Friction**: Pre-commit hook handles all validation\n- **Safety Net**: Tests and formatting enforced automatically  \n- **Preview Isolation**: Every PR gets its own infrastructure\n- **Production Ready**: Merge → deploy → cleanup automatically\n\n### 🚀 **You're Ready To Build**\n\nYour stack is:\n- ✅ **Alchemy-compliant** (follows official guidelines exactly)\n- ✅ **Fully scoped** (database → storage → compute hierarchy)\n- ✅ **Type-safe** (complete TypeScript coverage)\n- ✅ **Auto-tested** (comprehensive test suite)\n- ✅ **Production-ready** (zero-downtime deployments)\n\n**Start building!** 🚀\n\n### Adding Features\n\n1. **Create a feature branch**\n   ```bash\n   git checkout -b feat/your-feature\n   ```\n\n2. **Implement the feature**\n   - Add backend API endpoints in `src/backend/`\n   - Create frontend components in `src/frontend/`\n   - Write tests in `src/tests/`\n   - Update documentation in `docs/`\n\n3. **Test your changes**\n   ```bash\n   bun format          # Fix formatting\n   bun test            # Run tests\n   bun check           # Type-check and lint\n   ```\n\n4. **Submit a pull request**\n   - Automatic preview URL will be created\n   - Tests will run in CI\n   - Review and merge to deploy\n\n### Scripts\n\n- `bun run alchemy:dev` – Hot-reload local development\n- `bun run deploy` – Deploy to personal stage (up phase)\n- `bun run deploy:prod` – Deploy main branch to production (up phase)\n- `bun run deploy:read` – Read infrastructure properties without changes (read phase)\n- `bun run destroy` – Clean up all resources (destroy phase)\n- `bun run destroy:prod` – Clean up production resources (destroy phase)\n- `bun run build` – Build frontend assets\n- `bun run check` – Type-check and lint\n- `bun run format` – Format code with oxfmt\n- `bun test` – Run test suite\n\n### Phase Examples\n\n```bash\n# Normal deployment (up phase)\nbun run deploy\n\n# Read infrastructure without changes (read phase)\nbun run deploy:read\n\n# Destroy all resources (destroy phase)\nbun run destroy\n\n# Use specific stage with phase\nPHASE=destroy bun run deploy --stage prod\n```\n\n## 🏗️ Architecture\n\nThis demo follows Alchemy's architecture principles and recommended setup:\n\n### Scope Hierarchy\n\nThis project implements Alchemy's hierarchical scope structure for optimal organization:\n\n```\ncloudflare-demo (Application Scope)\n├── $USER/ (Stage Scope - your username)\n│   ├── database/ (Nested Scope) - Data storage resources\n│   │   └── D1 Database\n│   ├── storage/ (Nested Scope) - File and object storage\n│   │   ├── R2 Bucket\n│   │   └── KV Namespaces (cache + MCP)\n│   ├── compute/ (Nested Scope) - Processing and workflows\n│   │   ├── Queue\n│   │   ├── Durable Objects\n│   │   └── Workflows\n│   └── website (Resource) - Main application\n└── prod/ (Stage Scope - production)\n    └── [same structure as above]\n```\n\n### Apps \u0026 Stages\n\nThis project uses the recommended Alchemy Apps \u0026 Stages pattern:\n\n- **App**: `cloudflare-demo` - Contains all infrastructure resources\n- **Stages**: Isolated environments for different purposes\n  - **Personal Stage**: Each developer's personal environment (`$USER`)\n  - **Pull Request Stage**: Preview environments for PRs (`pr-123`)\n  - **Production Stage**: Production environment (`prod`)\n\n### Stage Management\n\n```bash\n# Personal development (uses your username)\nbun run alchemy:dev    # Development server\nbun run deploy        # Deploy to your stage\n\n# Production\nbun run deploy:prod   # Deploy to production\n\n# Pull Request (automatic)\nbun run deploy --stage pr-123  # Deploy to PR stage\n\n# Cleanup\nbun run destroy       # Clean up your stage\nbun run destroy:prod  # Clean up production\n```\n\n### Resource Naming\n\nResources are automatically named with the pattern: `${app}-${stage}-${id}`\n\n- Example: `cloudflare-demo-website-username` (personal stage)\n- Example: `cloudflare-demo-website-prod` (production stage)\n\n### Alchemy Principles\n\n- **TypeScript Native**: Full type safety and IntelliSense\n- **Minimal Abstraction**: Thin wrappers around Cloudflare APIs\n- **Explicit Configuration**: Clear, declarative infrastructure\n- **Local Development**: Miniflare for local testing\n- **Environment Isolation**: Separate stages for different purposes\n\n## 🔧 Configuration\n\n### Profiles\n\nAlchemy profiles manage credentials without `.env` files:\n\n```bash\n# Configure profile\nalchemy configure [--profile name]\n\n# Login\nalchemy login [--profile name]\n\n# Deploy with profile\nalchemy deploy --profile prod\n```\n\n**Profile Storage**: `~/.alchemy/`\n- `config.json` - Profile settings (no secrets)\n- `credentials/{profile}/{provider}.json` - Credentials (sensitive)\n\nSee [docs/PROFILES_GUIDE.md](./docs/PROFILES_GUIDE.md) for details.\n\n### Execution Phases\n\nThree modes for running infrastructure:\n\n| Phase | Purpose | Usage |\n|-------|---------|-------|\n| `up` | Deploy (default) | `bun ./alchemy.run.ts` |\n| `destroy` | Tear down | `PHASE=destroy bun ./alchemy.run.ts` |\n| `read` | Access only | `PHASE=read bun ./alchemy.run.ts` |\n\n**Read phase example**:\n```bash\n# Build frontend with infrastructure URLs\nPHASE=read bun ./scripts/build-frontend.ts\n```\n\nSee [docs/EXECUTION_PHASES.md](./docs/EXECUTION_PHASES.md) for details.\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PHASE` | Execution phase (`up`/`destroy`/`read`) | `up` |\n| `STAGE` | Deployment stage | `$USER` |\n| `ALCHEMY_PROFILE` | Profile to use | `default` |\n| `CLOUDFLARE_PROFILE` | Cloudflare-specific profile | `default` |\n\n### Infrastructure Definition\n\n`alchemy.run.ts` defines all resources:\n\n```typescript\nconst phase = (process.env.PHASE as \"up\" | \"destroy\" | \"read\") ?? \"up\";\nconst stage = process.env.STAGE ?? process.env.USER ?? \"dev\";\n\nconst app = await alchemy(\"cloudflare-demo\", {\n  phase,\n  stage,\n  profile: process.env.ALCHEMY_PROFILE ?? \"default\"\n});\n\n// Resources use automatic naming: ${app}-${resource}-${stage}\nexport const website = await Worker(\"website\", {\n  script: \"./src/backend/server.ts\"\n});\n\nawait app.finalize();\n```\n\n### Common Patterns\n\n```bash\n# Deploy to dev\nbun run deploy\n\n# Deploy to prod\nSTAGE=prod bun run deploy\n\n# Destroy dev\nPHASE=destroy bun run deploy\n\n# Read infrastructure\nPHASE=read bun run deploy\n\n# Use specific profile\nalchemy deploy --profile prod\n```\n\n## 🚀 Deployment\n\n### Preview Deployments\n\n- Push to feature branch → Automatic preview URL\n- Test changes in isolated environment\n- Preview URL posted as PR comment\n\n### Production Deployment\n\n- Merge to main branch → Automatic production deployment\n- Uses `prod` stage for production resources\n- Zero-downtime deployments\n\n## 🧹 Cleanup\n\n```bash\n# Remove development resources\nbun run destroy\n\n# Remove production resources\nbun run destroy:prod\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for detailed guidelines.\n\n### Before Contributing\n\n1. Read the [Contributing Guide](./CONTRIBUTING.md)\n2. Follow Alchemy's [testing best practices](./CONTRIBUTING.md#testing-best-practices)\n3. Use the [pre-commit script](./scripts/pre-commit.sh)\n4. Ensure all tests pass\n\n## 📄 License\n\nApache-2.0 - see [LICENSE](./LICENSE) for details.\n\n## 🔗 Links\n\n- [Alchemy Documentation](https://alchemy.run)\n- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers)\n- [Drizzle ORM](https://orm.drizzle.team)\n- [React](https://react.dev)\n- [Tailwind CSS](https://tailwindcss.com)\n\n## 💡 Need Help?\n\n- Check our [documentation](./docs/)\n- Review [existing issues](https://github.com/brendadeeznuts1111/alchmenyrun/issues)\n- Join our [Discord community](https://discord.gg/jwKw8dBJdN)\n- Create a [new issue](https://github.com/brendadeeznuts1111/alchmenyrun/issues/new)\n\n---\n\n🚀 **Go build!**  \nYour repo is a **Cloudflare-Bun-SPA rocket**—just:\n\n```bash\nbun run alchemy:dev   # start coding\n```\n\nEverything else happens automatically.  \nHappy shipping!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrendadeeznuts1111%2Falchmenyrun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrendadeeznuts1111%2Falchmenyrun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrendadeeznuts1111%2Falchmenyrun/lists"}