Skip to content

Commit b244b90

Browse files
nchopranchopra
authored
feat(assets): add static assets service for RefRef scripts (#40)
* feat(assets): add static assets service for RefRef scripts - Introduced a new `assets` application to serve static scripts for attribution tracking and referral widgets via Cloudflare. - Implemented build scripts to copy and prepare assets for deployment, including versioning and checksum generation. - Configured CORS and caching headers for optimal performance in production. - Added comprehensive README documentation for setup, deployment, and usage instructions. - Updated environment variables in the webapp to point to the new assets service. - Created necessary configuration files for TypeScript, Wrangler, and Git ignore settings. - Enhanced the overall project structure to support the new assets service. * feat(assets): migrate to Cloudflare Workers Static Assets architecture - Updated the assets service to utilize the new Cloudflare Workers Static Assets platform, replacing the previous Pages setup. - Introduced a Worker script (`src/index.ts`) for handling routing, caching, and CORS headers. - Replaced `wrangler.jsonc` with `wrangler.toml` for configuration, aligning with the new architecture. - Removed obsolete `_headers` and `_redirects` files, now managed by the Worker. - Enhanced TypeScript support and added necessary dependencies for the new setup. - Updated README and migration documentation to reflect changes and provide guidance for deployment and local testing.
1 parent 2bdbef5 commit b244b90

18 files changed

Lines changed: 2167 additions & 159 deletions

File tree

‎apps/assets/.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Build outputs
2+
dist/
3+
4+
# Generated assets (built from packages)
5+
public/*.js
6+
public/*.js.map
7+
8+
# Keep configuration files
9+
!public/_headers
10+
!public/_redirects
11+
12+
# Dependencies
13+
node_modules/
14+
15+
# TypeScript
16+
*.tsbuildinfo
17+
18+
# Environment
19+
.env
20+
.env.local
21+
.env.*.local

‎apps/assets/MIGRATION.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Migration to Cloudflare Workers Static Assets
2+
3+
## What Changed
4+
5+
Cloudflare has unified Workers and Pages into a single **Workers Static Assets** platform. Our implementation has been updated to use this new architecture.
6+
7+
## Old vs New Architecture
8+
9+
### Before (Incorrect)
10+
```
11+
❌ Used wrangler.jsonc (wrong format)
12+
❌ Had main = "." (invalid)
13+
❌ Used _headers and _redirects files (Pages-only features)
14+
❌ No Worker script
15+
❌ Relied on Pages behavior for routing
16+
```
17+
18+
### After (Correct)
19+
```
20+
✅ Uses wrangler.toml (correct format)
21+
✅ Has main = "src/index.ts" (Worker script)
22+
✅ Worker handles all routing and headers
23+
✅ Uses env.ASSETS binding to fetch static files
24+
✅ Follows Workers Static Assets best practices
25+
```
26+
27+
## Key Changes
28+
29+
### 1. Added Worker Script (`src/index.ts`)
30+
31+
The Worker script handles:
32+
- **Route mappings**: `/scripts/widget.js` → `/widget.v1.js`
33+
- **Aliases**: `/attribution.latest.js` → `/attribution.v1.js`
34+
- **Cache headers**: Immutable for versioned, short cache for aliases
35+
- **CORS**: Automatic CORS headers for all scripts
36+
37+
### 2. Updated Configuration (`wrangler.toml`)
38+
39+
```toml
40+
# Before
41+
main = "." # ❌ Invalid
42+
43+
# After
44+
main = "src/index.ts" # ✅ Points to Worker script
45+
46+
[assets]
47+
directory = "./public"
48+
binding = "ASSETS" # ✅ Required for env.ASSETS.fetch()
49+
```
50+
51+
### 3. Removed Obsolete Files
52+
53+
- ❌ Deleted `_headers` (now handled in Worker)
54+
- ❌ Deleted `_redirects` (now handled in Worker)
55+
- ❌ Removed `wrangler.jsonc` (renamed to `.toml`)
56+
57+
### 4. Added TypeScript Support
58+
59+
```json
60+
{
61+
"types": ["@cloudflare/workers-types"]
62+
}
63+
```
64+
65+
## How It Works Now
66+
67+
### Request Flow
68+
69+
1. Request arrives: `https://assets.refref.ai/scripts/attribution.js`
70+
2. Worker checks route map: Maps to `/attribution.v1.js`
71+
3. Worker fetches from storage: `env.ASSETS.fetch(request)`
72+
4. Worker adds headers:
73+
- `Cache-Control: public, max-age=3600`
74+
- `Access-Control-Allow-Origin: *`
75+
5. Response sent to client
76+
77+
### Supported URLs
78+
79+
All these work automatically:
80+
81+
```
82+
✅ /attribution.v1.js (direct, immutable)
83+
✅ /widget.v1.js (direct, immutable)
84+
✅ /attribution.latest.js (alias to v1)
85+
✅ /widget.latest.js (alias to v1)
86+
✅ /attribution.js (alias to v1)
87+
✅ /widget.js (alias to v1)
88+
✅ /scripts/attribution.js (backward compatibility)
89+
✅ /scripts/widget.js (backward compatibility)
90+
```
91+
92+
## Benefits of New Architecture
93+
94+
1. **Unified Platform**: No more confusion between Workers and Pages
95+
2. **Code-based Routing**: Explicit, testable routing logic
96+
3. **Dynamic Control**: Can add logic, A/B testing, feature flags, etc.
97+
4. **Better Performance**: Cloudflare's asset storage + Worker caching
98+
5. **Type Safety**: Full TypeScript support with Workers types
99+
100+
## Deployment
101+
102+
No changes to deployment commands:
103+
104+
```bash
105+
# Production
106+
pnpm -F @refref/assets deploy:cloudflare
107+
108+
# Dev/Preview
109+
pnpm -F @refref/assets deploy:cloudflare:dev
110+
```
111+
112+
The Worker + assets are deployed together as a single unit.
113+
114+
## Testing Locally
115+
116+
```bash
117+
# Start local dev server
118+
pnpm -F @refref/assets preview
119+
120+
# Test routes
121+
curl http://localhost:8787/attribution.v1.js
122+
curl http://localhost:8787/scripts/widget.js
123+
```
124+
125+
## Migration Checklist
126+
127+
- [x] Created Worker script (`src/index.ts`)
128+
- [x] Updated `wrangler.toml` configuration
129+
- [x] Removed `_headers` and `_redirects` files
130+
- [x] Added `@cloudflare/workers-types` dependency
131+
- [x] Updated TypeScript configuration
132+
- [x] Updated README documentation
133+
- [x] Tested build process
134+
- [x] Ready for deployment
135+
136+
## References
137+
138+
- [Cloudflare Workers Static Assets Docs](https://developers.cloudflare.com/workers/static-assets/)
139+
- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)
140+
- [Assets Binding](https://developers.cloudflare.com/workers/static-assets/binding/)

0 commit comments

Comments
 (0)