Skip to content

Commit b6f2c80

Browse files
claudeclaude
committed
Initialize TypeScript project with Cloudflare Workers deployment
Setup: - Add package.json with TypeScript, Wrangler, Vitest dependencies - Configure tsconfig.json for ES2022 with Cloudflare Workers types - Add wrangler.toml configuration for worker deployment - Create .gitignore for node_modules and build artifacts Simple deployment test worker: - Implement basic worker returning HTML page with TailwindCSS - Display "Deployment Test Successful" message - Verify TypeScript compilation and deployment pipeline GitHub Actions: - Add deploy.yml workflow for automatic deployment on push to main - Configure Node.js 20, npm ci, and Wrangler deployment - Support manual workflow dispatch Documentation: - Add DEPLOYMENT.md with setup instructions - Document local development with .dev.vars - Document production deployment via GitHub Actions - Include MailChannels setup requirements - Add troubleshooting section Next: Test deployment, then integrate MailChannels
1 parent 7509f19 commit b6f2c80

File tree

7 files changed

+281
-0
lines changed

7 files changed

+281
-0
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Deploy to Cloudflare Workers
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch: # Allow manual triggering
8+
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
name: Deploy
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Node.js
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
cache: 'npm'
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Run tests
27+
run: npm test
28+
continue-on-error: true # Continue even if tests fail (for now, since we don't have tests yet)
29+
30+
- name: Deploy to Cloudflare Workers
31+
uses: cloudflare/wrangler-action@v3
32+
with:
33+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
34+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Wrangler
5+
.wrangler/
6+
.dev.vars
7+
dist/
8+
9+
# TypeScript
10+
*.tsbuildinfo
11+
12+
# Environment variables (local development only)
13+
.env
14+
.env.local
15+
16+
# Editor
17+
.vscode/
18+
.idea/
19+
*.swp
20+
*.swo
21+
22+
# OS
23+
.DS_Store
24+
Thumbs.db

‎DEPLOYMENT.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Deployment Guide
2+
3+
## Prerequisites
4+
5+
1. **Cloudflare Account**: Sign up at https://dash.cloudflare.com
6+
2. **Node.js**: v20 or higher
7+
3. **Wrangler CLI**: Installed via npm (included in dev dependencies)
8+
9+
## Local Development
10+
11+
### 1. Install Dependencies
12+
13+
```bash
14+
npm install
15+
```
16+
17+
### 2. Configure Local Environment
18+
19+
Create a `.dev.vars` file in the project root for local development:
20+
21+
```bash
22+
PERSONAL_EMAIL=your-personal@example.com
23+
WORK_EMAIL=your-work@example.com
24+
MAILCHANNELS_API_KEY=your-mailchannels-key
25+
PINCODE=your-secret-pincode
26+
FROM_EMAIL=noreply@yourdomain.com
27+
FROM_NAME=MailRelay
28+
```
29+
30+
### 3. Run Locally
31+
32+
```bash
33+
npm run dev
34+
```
35+
36+
Visit `http://localhost:8787` to test locally.
37+
38+
## Production Deployment
39+
40+
### Option 1: GitHub Actions (Automatic)
41+
42+
#### Setup GitHub Secrets
43+
44+
Go to your repository Settings → Secrets and variables → Actions, and add:
45+
46+
1. **CLOUDFLARE_API_TOKEN**
47+
- Go to https://dash.cloudflare.com/profile/api-tokens
48+
- Create token with "Edit Cloudflare Workers" permissions
49+
- Copy and paste into GitHub secret
50+
51+
2. **CLOUDFLARE_ACCOUNT_ID**
52+
- Find at https://dash.cloudflare.com
53+
- Look in the URL or Workers & Pages section
54+
- Copy your Account ID
55+
56+
#### Configure Worker Secrets
57+
58+
Set environment variables in Cloudflare:
59+
60+
```bash
61+
# Using Wrangler CLI locally
62+
wrangler secret put PERSONAL_EMAIL
63+
wrangler secret put WORK_EMAIL
64+
wrangler secret put MAILCHANNELS_API_KEY
65+
wrangler secret put PINCODE
66+
wrangler secret put FROM_EMAIL
67+
wrangler secret put FROM_NAME
68+
```
69+
70+
Or set them in the Cloudflare Dashboard:
71+
- Go to Workers & Pages → mailrelay → Settings → Variables
72+
- Add each secret
73+
74+
#### Deploy
75+
76+
Push to `main` branch:
77+
78+
```bash
79+
git push origin main
80+
```
81+
82+
GitHub Actions will automatically deploy to Cloudflare Workers.
83+
84+
### Option 2: Manual Deployment
85+
86+
```bash
87+
# Build and deploy
88+
npm run deploy
89+
```
90+
91+
## MailChannels Setup
92+
93+
MailRelay uses MailChannels for email delivery. You need:
94+
95+
1. **Domain with SPF/DKIM configured** for MailChannels
96+
2. **MailChannels API access** (free for Cloudflare Workers users)
97+
98+
See: https://blog.cloudflare.com/sending-email-from-workers-with-mailchannels/
99+
100+
## Verification
101+
102+
After deployment:
103+
104+
1. Visit your worker URL (e.g., `https://mailrelay.<your-subdomain>.workers.dev`)
105+
2. You should see "Deployment Test Successful"
106+
3. Test sending an email through the form
107+
108+
## Troubleshooting
109+
110+
### Deployment fails
111+
112+
- Check GitHub Actions logs
113+
- Verify CLOUDFLARE_API_TOKEN has correct permissions
114+
- Verify CLOUDFLARE_ACCOUNT_ID is correct
115+
116+
### Worker runs but emails don't send
117+
118+
- Check MailChannels API key is set correctly
119+
- Verify domain SPF/DKIM records
120+
- Check worker logs in Cloudflare Dashboard
121+
122+
### Local development issues
123+
124+
- Ensure `.dev.vars` file exists with all required variables
125+
- Run `wrangler login` if authentication fails

‎package.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "mailrelay",
3+
"version": "1.0.0",
4+
"description": "Email relay with web form and API built on Cloudflare Workers",
5+
"main": "src/index.ts",
6+
"scripts": {
7+
"dev": "wrangler dev",
8+
"deploy": "wrangler deploy",
9+
"test": "vitest"
10+
},
11+
"keywords": ["cloudflare", "workers", "email", "mailchannels"],
12+
"author": "",
13+
"license": "MIT",
14+
"devDependencies": {
15+
"@cloudflare/workers-types": "^4.20241022.0",
16+
"typescript": "^5.6.3",
17+
"vitest": "^2.1.5",
18+
"wrangler": "^3.86.1"
19+
}
20+
}

‎src/index.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/**
2+
* MailRelay - Simple Email Relay Service
3+
* Cloudflare Worker with MailChannels integration
4+
*/
5+
6+
export interface Env {
7+
PERSONAL_EMAIL: string;
8+
WORK_EMAIL: string;
9+
MAILCHANNELS_API_KEY: string;
10+
PINCODE: string;
11+
FROM_EMAIL: string;
12+
FROM_NAME: string;
13+
}
14+
15+
export default {
16+
async fetch(request: Request, env: Env): Promise<Response> {
17+
const url = new URL(request.url);
18+
19+
// Simple HTML page for deployment test
20+
const html = `
21+
<!DOCTYPE html>
22+
<html lang="en">
23+
<head>
24+
<meta charset="UTF-8">
25+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
26+
<title>MailRelay</title>
27+
<script src="https://cdn.tailwindcss.com"></script>
28+
</head>
29+
<body class="bg-gray-50 min-h-screen flex items-center justify-center">
30+
<div class="bg-white p-8 rounded-lg shadow-md max-w-md w-full">
31+
<h1 class="text-3xl font-bold text-gray-800 mb-4">📧 MailRelay</h1>
32+
<p class="text-gray-600 mb-4">Email relay service deployed successfully!</p>
33+
<div class="bg-green-50 border border-green-200 rounded p-4">
34+
<p class="text-green-800 text-sm font-medium">✓ Deployment Test Successful</p>
35+
<p class="text-green-600 text-xs mt-1">Worker is running on Cloudflare</p>
36+
</div>
37+
</div>
38+
</body>
39+
</html>
40+
`;
41+
42+
return new Response(html, {
43+
headers: {
44+
'Content-Type': 'text/html;charset=UTF-8',
45+
},
46+
});
47+
},
48+
};

‎tsconfig.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"compilerOptions": {
3+
"target": "ES2022",
4+
"module": "ES2022",
5+
"lib": ["ES2022"],
6+
"types": ["@cloudflare/workers-types"],
7+
"moduleResolution": "node",
8+
"resolveJsonModule": true,
9+
"allowSyntheticDefaultImports": true,
10+
"strict": true,
11+
"esModuleInterop": true,
12+
"skipLibCheck": true,
13+
"forceConsistentCasingInFileNames": true,
14+
"isolatedModules": true,
15+
"noEmit": true
16+
},
17+
"include": ["src/**/*"],
18+
"exclude": ["node_modules"]
19+
}

‎wrangler.toml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name = "mailrelay"
2+
main = "src/index.ts"
3+
compatibility_date = "2024-10-31"
4+
5+
# Environment variables (secrets should be set via `wrangler secret put`)
6+
# PERSONAL_EMAIL - set via wrangler secret
7+
# WORK_EMAIL - set via wrangler secret
8+
# MAILCHANNELS_API_KEY - set via wrangler secret
9+
# PINCODE - set via wrangler secret
10+
# FROM_EMAIL - set via wrangler secret
11+
# FROM_NAME - set via wrangler secret

0 commit comments

Comments
 (0)