24 KiB
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:
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-ssgfor static generation@unhead/vuefor per-page metadata- Markdown + YAML frontmatter
gray-matterfor frontmatter parsingmarkdown-itfor Markdown renderingzodfor 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:
/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:
<title>
<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:
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:
---
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:
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:
src/data/events.ts
Use Vite:
import.meta.glob(...)
to load event Markdown files at build time.
A reasonable approach is:
const files = import.meta.glob(
"../content/events/*.md",
{
query: "?raw",
import: "default",
eager: true,
},
);
Then for each file:
- parse YAML frontmatter with
gray-matter - validate metadata with
zod - render Markdown body with
markdown-it - return a typed
EventData
Expose helpers such as:
getEvents()
getEventBySlug(slug)
getActiveEvent()
Sort events deterministically, preferably by start date descending.
8. Schema validation
Use zod.
Required fields:
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:
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:
scripts/validate-events.ts
and expose:
{
"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: trueevents - 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:
/
/partilhar
/partilhar/:slug
/
Simple CRR landing page.
/partilhar
Resolve the current event using:
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:
/
/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:
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:
Copiar texto
Abrir publicação no Facebook
Both must be large, touch-friendly controls.
13. SharePanel.vue
Create a reusable component receiving something like:
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:
await navigator.clipboard.writeText(props.shareText);
After successful copy:
✓ Copiado
Restore to:
Copiar texto
after around 2–3 seconds.
If Clipboard API is unavailable or fails:
- select the textarea
- try a compatible fallback
- if copying still fails, show:
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:
<a
:href="facebookUrl"
target="_blank"
rel="noopener noreferrer"
class="primary-facebook-button"
>
Abrir publicação no Facebook
</a>
Do not construct:
facebook.com/sharer/sharer.php?u=<facebook post>
The objective is to open the actual original CRR publication.
16. Facebook embed
Create:
src/components/FacebookPost.vue
Props:
interface Props {
url: string;
}
Only render it when:
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:
share:
text: |
...
But design the data and component structure so the project can later support:
share:
texts:
- |
Já está tudo preparado...
- |
As Festas da Rebolaria estão quase aí...
- |
Dias 5, 6 e 7...
Future UI could provide:
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:
navigator.share(...)
when available.
This should share the CRR landing/event page itself.
Example:
[ 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:
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:
<title>...</title>
<meta name="description" ...>
<link rel="canonical" ...>
<meta property="og:type" content="website">
<meta property="og:title" ...>
<meta property="og:description" ...>
<meta property="og:image" ...>
<meta property="og:url" ...>
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" ...>
<meta name="twitter:description" ...>
<meta name="twitter:image" ...>
This is important for:
- Messenger
- 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:
VITE_SITE_URL=https://crrebolaria.pt
or a build-time config module.
Provide:
.env.example
with:
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:
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:
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:
/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:
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:
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
Adapt to the actual generated Vite asset directory.
27. Docker Compose
Provide:
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:
node_modules
dist
.git
.gitignore
.vscode
.idea
.DS_Store
npm-debug.log
Do not exclude source Markdown or poster files.
29. Development workflow
Install:
npm install
Development server:
npm run dev
Validate:
npm run validate
Build:
npm run build
Docker production test:
docker compose build
docker compose up -d
Open:
http://localhost:8080
30. Event creation workflow
Adding a future event should require only content changes.
Process:
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:
cp src/content/events/festas-2026.md \
src/content/events/festas-2027.md
Then:
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
alttext 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:
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:
src/content/events/festas-2026.md
Metadata:
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:
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:
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:
{
"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:
{
"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:
validate
+
typecheck
+
static build
before Docker completes.
39. Implementation phases
Implement in this order:
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:
docker compose up -d --build
starts a production container successfully.
Opening:
http://localhost:8080/partilhar
must display the active CRR event.
The following must work:
- The event poster is visible.
- The suggested share text is visible.
- Copiar texto copies the exact configured text.
- Copy success is visibly confirmed.
- Abrir publicação no Facebook opens the configured original Facebook post.
/partilhar/festas-2026works directly.- The event's Open Graph metadata is present in the generated HTML.
- The social preview uses the event poster.
- Adding another event only requires a Markdown file and poster.
- Changing the active campaign requires no Vue source code changes.
- The final production container runs nginx only.
- The site remains functional when the Facebook embed fails.
41. Core architectural requirements
Markdown is the source of truth
Event data lives in:
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:
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.