# CRR Event Sharing Tool — Vue 3 Implementation Plan ## 1. Goal Build a small self-hosted web application for the **Centro Recreativo da Rebolaria** that makes it easy for people to promote CRR events on Facebook. The primary workflow is: ```text User receives: https://crrebolaria.pt/partilhar ↓ Opens current event sharing page ↓ Sees event poster + suggested sharing text ↓ Clicks "Copiar texto" ↓ Clicks "Abrir publicação no Facebook" ↓ Facebook opens the original CRR post ↓ User selects: Partilhar → Escrever publicação ↓ Pastes suggested text and publishes ``` Important constraint: do **not** attempt to automatically create a Facebook share containing the original Facebook post through `sharer.php`. Facebook does not reliably allow another Facebook post to be attached that way. The tool should facilitate the process rather than automate the final Facebook action. --- ## 2. Technology Use: - Vue 3 - TypeScript - Vite - Vue Router - `vite-ssg` for static generation - `@unhead/vue` for per-page metadata - Markdown + YAML frontmatter - `gray-matter` for frontmatter parsing - `markdown-it` for Markdown rendering - `zod` for event schema validation - Vanilla browser APIs for clipboard/native sharing - Docker - nginx Do **not** add: - database - CMS - Node.js production server - Nuxt - backend API - user accounts - Facebook Graph API The production result must be a fully static site. --- ## 3. Why use `vite-ssg` Do not deploy the project as a plain Vue SPA only. A normal SPA would make per-event Open Graph metadata unreliable because WhatsApp, Facebook, Messenger and other crawlers may not execute client-side JavaScript. Use `vite-ssg` so routes such as: ```text /partilhar/festas-2026 /partilhar/penalty-cup-2026 ``` are pre-rendered into real HTML files at build time. Each event page must therefore contain its own server-visible: ```html <meta name="description"> <meta property="og:title"> <meta property="og:description"> <meta property="og:image"> <meta property="og:url"> ``` This is an important architectural requirement. --- ## 4. Repository structure Target structure: ```text crr-share/ ├── src/ │ ├── components/ │ │ ├── AppHeader.vue │ │ ├── EventHeader.vue │ │ ├── EventPoster.vue │ │ ├── SharePanel.vue │ │ ├── ShareText.vue │ │ ├── ShareInstructions.vue │ │ └── FacebookPost.vue │ │ │ ├── content/ │ │ └── events/ │ │ ├── festas-2026.md │ │ └── penalty-cup-2026.md │ │ │ ├── data/ │ │ └── events.ts │ │ │ ├── layouts/ │ │ └── DefaultLayout.vue │ │ │ ├── pages/ │ │ ├── HomePage.vue │ │ ├── SharePage.vue │ │ └── EventSharePage.vue │ │ │ ├── router/ │ │ └── routes.ts │ │ │ ├── styles/ │ │ └── global.css │ │ │ ├── types/ │ │ └── event.ts │ │ │ ├── App.vue │ └── main.ts │ ├── public/ │ ├── images/ │ │ └── events/ │ ├── favicon.svg │ └── logo.* │ ├── scripts/ │ └── validate-events.ts │ ├── Dockerfile ├── compose.yaml ├── nginx.conf ├── .dockerignore ├── vite.config.ts ├── tsconfig.json ├── package.json ├── package-lock.json └── README.md ``` The agent may simplify component splitting where appropriate, but should preserve the overall separation between: - content loading - event schema/model - routing - sharing UI - Facebook embed - layout/styling --- ## 5. Event content model Each event must be represented by **one Markdown file**. Example: ```markdown --- title: "Festas do 66.º Aniversário" slug: "festas-2026" active: true date: start: 2026-09-05 end: 2026-09-07 location: name: "Centro Recreativo da Rebolaria" locality: "Rebolaria, Batalha" poster: "/images/events/festas-2026.jpg" facebook: url: "https://www.facebook.com/story.php?story_fbid=122327514458210862&id=61556325866671" embed: true share: text: | Já está tudo preparado para mais um grande fim de semana na Rebolaria! 🎉🥳 Dias 5, 6 e 7 de setembro, apareçam e venham festejar connosco! ❤️💚 Vejam o programa completo aqui em baixo 👇 --- ## Sobre o evento O Centro Recreativo da Rebolaria celebra o seu **66.º aniversário** com três dias de música, tradição, convívio e animação. ## Programa ### Sábado, 5 de setembro - 15h00 — Torneio de Penalty Cup - 19h00 — Abertura do restaurante - 22h00 — Pedro Nobre - De seguida — DJ Pinona ### Domingo, 6 de setembro - 12h00 — Abertura do arraial - 16h30 — Rancho Folclórico Rosas do Lena - 19h00 — Abertura do restaurante - 22h00 — Red Kiss ### Segunda-feira, 7 de setembro - 18h30 — Jogos tradicionais - 19h00 — Abertura do restaurante - 22h00 — Fábio Tacho — Teclista e Vocalista ``` The Markdown body is for human-readable event information. The YAML frontmatter is for structured application data. --- ## 6. Event TypeScript model Define an explicit event model. For example: ```ts export interface EventDate { start: string; end: string; } export interface EventLocation { name: string; locality?: string; } export interface FacebookConfig { url: string; embed: boolean; } export interface ShareConfig { text: string; } export interface EventData { title: string; slug: string; active: boolean; date: EventDate; location: EventLocation; poster: string; facebook: FacebookConfig; share: ShareConfig; html: string; } ``` Do not rely on untyped frontmatter objects throughout the app. --- ## 7. Event loading Implement one central event loader in: ```text src/data/events.ts ``` Use Vite: ```ts import.meta.glob(...) ``` to load event Markdown files at build time. A reasonable approach is: ```ts const files = import.meta.glob( "../content/events/*.md", { query: "?raw", import: "default", eager: true, }, ); ``` Then for each file: 1. parse YAML frontmatter with `gray-matter` 2. validate metadata with `zod` 3. render Markdown body with `markdown-it` 4. return a typed `EventData` Expose helpers such as: ```ts getEvents() getEventBySlug(slug) getActiveEvent() ``` Sort events deterministically, preferably by start date descending. --- ## 8. Schema validation Use `zod`. Required fields: ```text title slug active date.start date.end location.name poster facebook.url facebook.embed share.text ``` Validate: - slug format - valid dates - end date >= start date - valid Facebook URL - non-empty share text - poster path starts with `/` - exactly zero or one active events - no duplicated slugs Example schema concept: ```ts const EventSchema = z.object({ title: z.string().min(1), slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), active: z.boolean(), date: z.object({ start: z.string(), end: z.string(), }), location: z.object({ name: z.string().min(1), locality: z.string().optional(), }), poster: z.string().startsWith("/"), facebook: z.object({ url: z.string().url(), embed: z.boolean(), }), share: z.object({ text: z.string().min(1), }), }); ``` If event data is invalid, the production build must fail with a clear error. --- ## 9. Explicit validation script In addition to runtime/build-time loading validation, create: ```text scripts/validate-events.ts ``` and expose: ```json { "scripts": { "validate": "tsx scripts/validate-events.ts", "build": "npm run validate && vite-ssg build" } } ``` The validator should catch: - invalid YAML - invalid field types - duplicate slugs - multiple `active: true` events - invalid Facebook URLs - invalid date ranges - missing poster files where practical The agent may adapt the exact command to the chosen `vite-ssg` setup. --- ## 10. Routes Use Vue Router-compatible route definitions. Required routes: ```text / /partilhar /partilhar/:slug ``` ### `/` Simple CRR landing page. ### `/partilhar` Resolve the current event using: ```ts getActiveEvent() ``` Prefer rendering the active event directly rather than introducing an unnecessary HTTP redirect. If there is no active event, render a friendly empty state. ### `/partilhar/:slug` Render the requested historical/current event. Unknown slugs should produce a sensible 404/not-found state. --- ## 11. Static generation Configure `vite-ssg` so every event route is generated at build time. The generated route list should include: ```text / /partilhar /partilhar/festas-2026 /partilhar/penalty-cup-2026 ... ``` Do not hard-code event routes manually. Generate them from the Markdown content. The agent must verify the final `dist` directory contains pre-rendered content for every event. --- ## 12. Event page UX Mobile is the primary target. Page order: ```text CRR branding Event title Event date/location Poster ------------------------ AJUDA-NOS A DIVULGAR Suggested sharing text [ Copiar texto ] ✓ Texto copiado [ Abrir publicação no Facebook ] ------------------------ COMO PARTILHAR 1. Copia o texto. 2. Abre a publicação. 3. Escolhe Partilhar → Escrever publicação. 4. Cola o texto e publica. ------------------------ Original Facebook publication (optional embed) ------------------------ About the event Programme ``` The two primary calls to action are: ```text Copiar texto Abrir publicação no Facebook ``` Both must be large, touch-friendly controls. --- ## 13. `SharePanel.vue` Create a reusable component receiving something like: ```ts interface Props { shareText: string; facebookUrl: string; } ``` Responsibilities: - show the suggested text - copy text to clipboard - show success/failure state - expose Facebook button - display sharing instructions Do not let Facebook-specific embed logic live in this component. --- ## 14. Copy functionality Primary implementation: ```ts await navigator.clipboard.writeText(props.shareText); ``` After successful copy: ```text ✓ Copiado ``` Restore to: ```text Copiar texto ``` after around 2–3 seconds. If Clipboard API is unavailable or fails: 1. select the textarea 2. try a compatible fallback 3. if copying still fails, show: ```text Não foi possível copiar automaticamente. Selecione o texto acima e copie-o manualmente. ``` The share text must remain visible/selectable even without JavaScript. --- ## 15. Facebook button The button must use the original CRR Facebook post URL directly. Conceptually: ```vue <a :href="facebookUrl" target="_blank" rel="noopener noreferrer" class="primary-facebook-button" > Abrir publicação no Facebook </a> ``` Do not construct: ```text facebook.com/sharer/sharer.php?u=<facebook post> ``` The objective is to open the actual original CRR publication. --- ## 16. Facebook embed Create: ```text src/components/FacebookPost.vue ``` Props: ```ts interface Props { url: string; } ``` Only render it when: ```yaml facebook: embed: true ``` Use the official Facebook post plugin/embed mechanism. Keep this isolated so it can be changed without affecting event data or sharing logic. The entire page must remain usable if the embed: - does not load - is blocked by browser privacy controls - is blocked by cookies/tracking settings - is unavailable because the Facebook post is not public - changes behavior in the future The embed is optional enhancement only. Always keep a visible normal link to the original Facebook publication. --- ## 17. Multiple suggested texts — future compatibility V1 can use: ```yaml share: text: | ... ``` But design the data and component structure so the project can later support: ```yaml share: texts: - | Já está tudo preparado... - | As Festas da Rebolaria estão quase aí... - | Dias 5, 6 e 7... ``` Future UI could provide: ```text Texto 1 Texto 2 Texto 3 ``` The implementation should not require a major rewrite to support this. --- ## 18. Optional native sharing As a secondary enhancement, support: ```ts navigator.share(...) ``` when available. This should share the CRR landing/event page itself. Example: ```text [ Partilhar esta página ] ``` This is not a replacement for the Facebook workflow and should be visually secondary. Do not make it a V1 blocker. --- ## 19. Design Design principles: - Portuguese UI - mobile-first - maximum content width around 600–700px - large readable typography - large buttons - minimal visual clutter - accessible contrast - poster prominently displayed - CRR identity/colours where available - no dashboard/admin appearance Prefer normal CSS rather than introducing a large UI framework unless justified. Use semantic HTML inside Vue templates: ```text header main section article footer button a ``` Avoid icon-only actions. --- ## 20. Metadata and social previews Use `@unhead/vue` so each pre-rendered event page gets unique metadata. For every event generate: ```html <title>... ``` This is important for: - WhatsApp - Messenger - Facebook - SMS link previews - email clients The poster should be the main Open Graph image. Open Graph image URLs must be absolute. --- ## 21. Site URL Use one configuration source for the public URL. Recommended: ```text VITE_SITE_URL=https://crrebolaria.pt ``` or a build-time config module. Provide: ```text .env.example ``` with: ```env VITE_SITE_URL=https://crrebolaria.pt ``` Do not scatter the production hostname through components. Use this value to build: - canonical URLs - Open Graph URLs - absolute poster URLs --- ## 22. Homepage Keep `/` deliberately small. Possible content: ```text Centro Recreativo da Rebolaria Eventos em destaque Festas do 66.º Aniversário [ Ver evento ] [ Ajudar a divulgar ] ``` Do not turn this project into a complete institutional website. The main feature is `/partilhar`. --- ## 23. `/partilhar` behavior `/partilhar` is the permanent public sharing address. If exactly one event is active: - show the active event sharing page If no event is active: ```text Neste momento não existe nenhuma campanha de divulgação ativa. ``` Optionally show recent events beneath it. If more than one event is active: - fail validation/build - do not choose one arbitrarily --- ## 24. Historical event URLs An old URL such as: ```text /partilhar/festas-2026 ``` must continue to work even after another campaign becomes active. This makes URLs safe to distribute permanently. Do not remove old content just because `active` becomes false. --- ## 25. Docker Use a multi-stage production build. Example: ```dockerfile FROM node:22-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:alpine COPY nginx.conf /etc/nginx/conf.d/default.conf COPY --from=build /app/dist /usr/share/nginx/html EXPOSE 80 ``` The final production image should contain nginx and static files only. No Node.js process should run in production. --- ## 26. nginx Serve the pre-rendered static site. Important distinction from a normal SPA: Because routes are pre-generated, nginx should prefer actual generated files/directories. A configuration can still include a safe fallback where useful, but do not rely on `index.html` SPA fallback as the mechanism for all routes. Configure: - static file serving - compression - sensible security headers - long-lived cache for hashed Vite assets - short/no aggressive cache for HTML Example asset rule: ```nginx location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; } ``` Adapt to the actual generated Vite asset directory. --- ## 27. Docker Compose Provide: ```yaml services: crr-share: build: . container_name: crr-share restart: unless-stopped ports: - "8080:80" ``` Assume an external reverse proxy handles: - domain - TLS - certificates Do not put certificate management inside this container. --- ## 28. `.dockerignore` Include at least: ```text node_modules dist .git .gitignore .vscode .idea .DS_Store npm-debug.log ``` Do not exclude source Markdown or poster files. --- ## 29. Development workflow Install: ```bash npm install ``` Development server: ```bash npm run dev ``` Validate: ```bash npm run validate ``` Build: ```bash npm run build ``` Docker production test: ```bash docker compose build docker compose up -d ``` Open: ```text http://localhost:8080 ``` --- ## 30. Event creation workflow Adding a future event should require only content changes. Process: ```text 1. Copy an existing Markdown event. 2. Change title. 3. Change slug. 4. Change dates. 5. Change share text. 6. Change Facebook URL. 7. Add poster to public/images/events/. 8. Set new event active: true. 9. Set previous event active: false. 10. Rebuild Docker. ``` Example: ```bash cp src/content/events/festas-2026.md \ src/content/events/festas-2027.md ``` Then: ```bash docker compose up -d --build ``` No Vue source file should need modification for a normal new event. --- ## 31. README Create a complete but concise `README.md`. It must explain: - what the application does - why Facebook sharing cannot be fully automated - local development - Docker deployment - reverse proxy expectations - how to create an event - how to change the active event - how to add a poster - how to obtain/use the Facebook post URL - how social previews work - how to rebuild after content changes Include a copy/paste Markdown event template. --- ## 32. Error handling ### Invalid Markdown/YAML Fail validation/build clearly. ### Missing poster Prefer validation failure where practical. ### Invalid Facebook URL Fail validation/build. ### Facebook post unavailable The rest of the page must continue working. ### Clipboard unavailable Keep text selectable and provide manual-copy guidance. ### JavaScript disabled Event information and Facebook link remain available. ### No active event Render a friendly message. ### Unknown event slug Render a proper not-found view. --- ## 33. Accessibility Minimum requirements: - meaningful `alt` text for poster - keyboard navigation - visible focus styles - touch targets around at least 44px - good text/background contrast - no information conveyed by colour alone - readable mobile typography - descriptive button/link labels - accessible status message after copying For copy status, use an `aria-live` region. --- ## 34. Privacy Do not add by default: - Google Analytics - Meta Pixel - tracking cookies - external analytics The Facebook embed itself may load Facebook resources. That is another reason the embed should be optional. The sharing page must work without the embed. --- ## 35. Testing At minimum add automated checks for: - event parser - schema validation - duplicate slug rejection - multiple active event rejection - active event resolution - Markdown rendering - route generation - correct Facebook URL - exact share text - absolute Open Graph image URL A light browser test is recommended. Example with Playwright: ```text Open /partilhar verify active event title click Copy verify copied confirmation verify Facebook link href open /partilhar/festas-2026 verify event renders ``` Test one mobile viewport. Do not introduce excessive test infrastructure. --- ## 36. Initial event Create: ```text src/content/events/festas-2026.md ``` Metadata: ```yaml title: "Festas do 66.º Aniversário" slug: "festas-2026" active: true date: start: 2026-09-05 end: 2026-09-07 location: name: "Centro Recreativo da Rebolaria" locality: "Rebolaria, Batalha" facebook: url: "https://www.facebook.com/story.php?story_fbid=122327514458210862&id=61556325866671" embed: true ``` Suggested text: ```text Já está tudo preparado para mais um grande fim de semana na Rebolaria! 🎉🥳 Dias 5, 6 e 7 de setembro, apareçam e venham festejar connosco! ❤️💚 Vejam o programa completo aqui em baixo 👇 ``` Programme: ```text Sábado, 5 de setembro 15h00 — Torneio de Penalty Cup 19h00 — Abertura do restaurante 22h00 — Pedro Nobre De seguida — DJ Pinona Domingo, 6 de setembro 12h00 — Abertura do arraial 16h30 — Rancho Folclórico Rosas do Lena 19h00 — Abertura do restaurante 22h00 — Red Kiss Segunda-feira, 7 de setembro 18h30 — Jogos tradicionais 19h00 — Abertura do restaurante 22h00 — Fábio Tacho — Teclista e Vocalista ``` --- ## 37. Suggested dependencies A reasonable initial dependency set: ```json { "dependencies": { "@unhead/vue": "...", "gray-matter": "...", "markdown-it": "...", "vue": "...", "vue-router": "...", "vite-ssg": "...", "zod": "..." }, "devDependencies": { "@vitejs/plugin-vue": "...", "tsx": "...", "typescript": "...", "vite": "...", "vue-tsc": "..." } } ``` Use current stable versions compatible with each other. Do not blindly use the literal placeholders above. Commit `package-lock.json`. --- ## 38. Recommended npm scripts Aim for something similar to: ```json { "scripts": { "dev": "vite", "validate": "tsx scripts/validate-events.ts", "typecheck": "vue-tsc --noEmit", "build": "npm run validate && npm run typecheck && vite-ssg build", "preview": "vite preview" } } ``` Adjust the exact SSG command to the installed `vite-ssg` version. The essential requirement is: ```text validate + typecheck + static build ``` before Docker completes. --- ## 39. Implementation phases Implement in this order: ```text Phase 1 Bootstrap Vue 3 + Vite + TypeScript. Phase 2 Install/configure Vue Router and vite-ssg. Phase 3 Implement event Markdown loader. Phase 4 Implement Zod schema and validation. Phase 5 Generate static routes from event Markdown. Phase 6 Implement /partilhar active-event behavior. Phase 7 Build EventSharePage. Phase 8 Build SharePanel and clipboard interaction. Phase 9 Add Facebook link. Phase 10 Add optional Facebook embed. Phase 11 Render Markdown event details/programme. Phase 12 Implement per-event Open Graph metadata. Phase 13 Add responsive CRR styling. Phase 14 Add Dockerfile + nginx + Compose. Phase 15 Add tests. Phase 16 Write README. Phase 17 Validate output inside Docker. ``` --- ## 40. Definition of done The implementation is complete when: ```bash docker compose up -d --build ``` starts a production container successfully. Opening: ```text http://localhost:8080/partilhar ``` must display the active CRR event. The following must work: 1. The event poster is visible. 2. The suggested share text is visible. 3. **Copiar texto** copies the exact configured text. 4. Copy success is visibly confirmed. 5. **Abrir publicação no Facebook** opens the configured original Facebook post. 6. `/partilhar/festas-2026` works directly. 7. The event's Open Graph metadata is present in the generated HTML. 8. The social preview uses the event poster. 9. Adding another event only requires a Markdown file and poster. 10. Changing the active campaign requires no Vue source code changes. 11. The final production container runs nginx only. 12. The site remains functional when the Facebook embed fails. --- ## 41. Core architectural requirements ### Markdown is the source of truth Event data lives in: ```text src/content/events/*.md ``` Facebook is an external publishing/sharing destination only. ### Static generation is required Use Vue 3, but pre-render event routes. Do not reduce the implementation to a client-only SPA because social-link previews are a core feature. ### Docker production is static Production should be: ```text Vue/Vite/SSG build ↓ static dist/ ↓ nginx ``` No application server is required. ### Content changes should not require code changes A normal future event must be creatable entirely from Markdown/YAML + poster image.