Email preview server: live URL for MJML design iteration #305

New issue

Open

opened 2026-04-03 20:53:25 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-04-03 20:53:25 +00:00

Owner

Type

Feature

Lineage

Standalone — discovered during email design session (2026-04-03). Can't iterate on email design without seeing results live.

Repo

forgejo_admin/basketball-api

User Story

As an admin,
I want a live preview URL that updates when email templates change,
So that I can approve email designs on my phone without deploying to production.

Context

MJML templates compile to HTML. Currently the only way to see an email is to deploy and send a test. Design iteration needs a faster loop: agent edits MJML → compiles → preview URL updates → Lucas checks phone.

The preview server is a dev tool, not a production service. It runs locally on archbox and gets a Tailscale funnel URL.

Solution

A simple npm script that:

Watches templates/email/*.mjml for changes
Compiles to templates/email/compiled/ on save (mjml --watch)
Serves templates/email/compiled/ on a local port (e.g. npx serve or python3 -m http.server)
Tailscale funnel exposes it as a URL Lucas can open on his phone

Add to package.json:

"scripts": {
  "preview:email": "npx concurrently \"mjml --watch 'templates/email/*.mjml' -o templates/email/compiled/\" \"npx serve templates/email/compiled -l 3001\""
}

Or simpler: two terminal commands, no new dependency.

File Targets

Files to modify:

package.json — add preview:email script

Files NOT to touch:

Templates themselves (separate ticket #303)
Python code

Acceptance Criteria

npm run preview:email starts watcher + server
Editing action.mjml and saving → compiled HTML updates within 2 seconds
Opening http://localhost:3001/action.html shows the compiled template
Tailscale funnel tailscale funnel 3001 makes it accessible on phone

Test Expectations

Manual: edit, save, refresh, see change
No automated tests needed — dev tooling only

Constraints

Dev tool only — not deployed to production
No new runtime dependencies (npx handles everything)
Must work on archbox (Linux, Node available via npx)

Checklist

PR opened
Script works locally
No unrelated changes

arch-email — email architecture
project-westside-basketball — parent project
Issue #303 — visual refinement (uses this preview to iterate)

### Type Feature ### Lineage Standalone — discovered during email design session (2026-04-03). Can't iterate on email design without seeing results live. ### Repo `forgejo_admin/basketball-api` ### User Story As an admin, I want a live preview URL that updates when email templates change, So that I can approve email designs on my phone without deploying to production. ### Context MJML templates compile to HTML. Currently the only way to see an email is to deploy and send a test. Design iteration needs a faster loop: agent edits MJML → compiles → preview URL updates → Lucas checks phone. The preview server is a dev tool, not a production service. It runs locally on archbox and gets a Tailscale funnel URL. ### Solution A simple npm script that: 1. Watches `templates/email/*.mjml` for changes 2. Compiles to `templates/email/compiled/` on save (mjml --watch) 3. Serves `templates/email/compiled/` on a local port (e.g. npx serve or python3 -m http.server) 4. Tailscale funnel exposes it as a URL Lucas can open on his phone Add to package.json: ```json "scripts": { "preview:email": "npx concurrently \"mjml --watch 'templates/email/*.mjml' -o templates/email/compiled/\" \"npx serve templates/email/compiled -l 3001\"" } ``` Or simpler: two terminal commands, no new dependency. ### File Targets Files to modify: - `package.json` — add `preview:email` script Files NOT to touch: - Templates themselves (separate ticket #303) - Python code ### Acceptance Criteria - [ ] `npm run preview:email` starts watcher + server - [ ] Editing action.mjml and saving → compiled HTML updates within 2 seconds - [ ] Opening `http://localhost:3001/action.html` shows the compiled template - [ ] Tailscale funnel `tailscale funnel 3001` makes it accessible on phone ### Test Expectations - [ ] Manual: edit, save, refresh, see change - No automated tests needed — dev tooling only ### Constraints - Dev tool only — not deployed to production - No new runtime dependencies (npx handles everything) - Must work on archbox (Linux, Node available via npx) ### Checklist - [ ] PR opened - [ ] Script works locally - [ ] No unrelated changes ### Related - `arch-email` — email architecture - `project-westside-basketball` — parent project - Issue #303 — visual refinement (uses this preview to iterate)