# 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
```
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
Abrir publicação no Facebook
```
Do not construct:
```text
facebook.com/sharer/sharer.php?u=
```
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
...
```
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.