release: v0.20.0

[baezor]

Release v0.20.0

Changes

• feat: add proper social card image for Open Graph sharing (feat: add proper social card image for Open Graph sharing #39)
  • Add branded 1200x630px social card image
  • Blog posts with hero images now use them for og:image
  • Replace default favicon.png with proper social card for og:image

[claude]

Code Review - PR #40: Release v0.20.0

Overview

This release adds proper Open Graph social card support with a custom-branded 1200x630px image. The implementation allows blog posts with hero images to use them for og:image while falling back to a default branded social card.

---

❌ Critical Issues

1. Missing Dependency: sharp Package

Location: scripts/generate-social-card.mjs:1

The script imports sharp but the package is not listed in package.json dependencies or devDependencies.

Impact: The script will fail when run on a fresh install.

Fix Required:

npm install --save-dev sharp

Then commit the updated package.json and package-lock.json.

Why this matters: The social card generation script cannot run without this dependency, which breaks reproducible builds.

---

2. Incorrect Base Branch

Location: PR targets main instead of develop

According to CLAUDE.md workflow guidelines:

• Release PRs should target main (correct for a release)
• However, the current branch should be branched from develop, not main

From CLAUDE.md:

Release workflow:

1. git checkout -b release/v1.x.x from develop
2. Final testing and version bumps
3. Merge to main (tag with version) and back to develop

Issue: If this release branch wasn't created from develop, it may be missing commits that exist in develop but not in main.

Fix Required: Verify the branch was created from develop. If not, you'll need to recreate it or merge develop into this branch first.

---

⚠️ Medium Priority Issues

3. No Script to Generate Social Card in package.json

Location: package.json

The generate-social-card.mjs script exists but there's no npm script to run it. This makes the tool harder to discover and use.

Recommendation: Add to package.json scripts:

"generate:social-card": "node scripts/generate-social-card.mjs"

---

4. Missing Tests for BaseHead Component Changes

Location: src/components/BaseHead.astro

Significant logic was added to handle both string and ImageMetadata types for the image prop, but there are no unit tests covering this component.

Testing gaps:

• No test for string URL handling
• No test for ImageMetadata handling
• No test for URL construction with SITE_URL
• No test ensuring og:image and twitter:image receive correct values

Recommendation: Add component tests using Vitest to cover the new image handling logic, particularly the type discrimination logic at lines 27-29.

---

5. Hardcoded Values in Social Card Generator

Location: scripts/generate-social-card.mjs:45, 55, 70

Values like "Angel Baez", "Full Stack Developer", and "angel-baez.com" are hardcoded in the SVG template.

Issue: If this script is meant to be reusable or if site info changes, these would need manual updates in multiple places.

Recommendation: Import these values from src/const.ts to maintain a single source of truth:

import { SITE_TITLE, SITE_DESCRIPTION, SITE_URL } from '../src/const.ts';

---

6. External Font Loading in SVG

Location: scripts/generate-social-card.mjs:21

The SVG loads Poppins font from Google Fonts CDN. This could fail if:

• Google Fonts is unavailable
• Network connection fails during image generation
• The font URL changes

Impact: Generated images might have fallback fonts, creating inconsistent branding.

Recommendation: Either:

1. Use a local font file, or
2. Document this as a known limitation/requirement
3. Add error handling to detect font loading failures

---

✅ Positive Aspects

1. Correct Asset Location

The social card is properly placed in src/assets/ (not public/), enabling Astro's built-in image optimization.

2. Type Safety Improvements

The image prop in BaseHead now properly accepts string | ImageMetadata, providing better type safety.

3. Path Alias Added

Added @/assets/* path alias to tsconfig.json, following the project's established pattern.

4. Proper URL Construction

URL handling correctly uses new URL() with SITE_URL as the base, ensuring absolute URLs for Open Graph tags.

5. Backward Compatibility

The changes are backward compatible - existing pages continue to work with the default social card.

---

🔍 Minor Issues & Suggestions

7. Variable Naming Inconsistency

Location: src/components/BaseHead.astro:93

The variable is renamed from imageUrl to schemaImageUrl just for the structured data script, which seems unnecessary.

Suggestion: Keep using imageUrl throughout - the rename adds no clarity.

---

8. Missing Documentation

Location: scripts/generate-social-card.mjs

The script lacks:

• Usage instructions in comments
• When/how to regenerate the card
• What to do after generating

Recommendation: Add a comment block at the top explaining:

/**
 * Generates the default social card for Open Graph sharing
 * 
 * Usage: npm run generate:social-card
 * 
 * Outputs: src/assets/social-card.png (1200x630px)
 * 
 * Run this when branding, colors, or site info changes.
 */

---

9. Blog Post Content Updates

Location: src/content/blog/youtube-to-recipe-with-ai.md

The blog post was updated with substantial content changes. While the updates improve accuracy (CLI tool instead of web service), these changes are unrelated to the social card feature.

Observation: Consider separating content updates from feature releases in future PRs for clearer change tracking.

---

🎯 Recommendations Summary

Must fix before merge:

1. ❌ Add sharp to devDependencies
2. ❌ Verify branch was created from develop (per GitFlow)

Should fix before merge:
3. ⚠️ Add npm script for social card generation
4. ⚠️ Add tests for BaseHead image handling logic
5. ⚠️ Import constants from src/const.ts instead of hardcoding

Nice to have:
6. Document external font dependency or use local fonts
7. Remove unnecessary variable renaming
8. Add documentation to the generation script

---

📊 Test Coverage Assessment

Current coverage:

• ✅ Visual regression tests will catch UI regressions
• ❌ No unit tests for new BaseHead logic
• ❌ No integration tests for social card usage

Recommendation: Add unit tests for the BaseHead component's image type handling to prevent regression.

---

🔒 Security Considerations

No security issues identified. The changes:

• Don't introduce user input handling
• Don't expose sensitive data
• Use safe URL construction methods
• Don't create XSS vulnerabilities

---

📈 Performance Considerations

Positive impact:

• Proper social cards improve social media previews
• Using Astro's image optimization for hero images is efficient

No performance concerns: The changes add minimal runtime overhead.

---

Overall Assessment

Verdict: ✅ Approve with Required Changes

This is a well-implemented feature that properly handles Open Graph metadata. The code quality is good with proper type safety and URL handling. However, the missing sharp dependency is a blocking issue that must be resolved before merge.

Once the dependency is added and the branch lineage is verified, this PR will be ready to merge.

Estimated effort to fix: ~5 minutes to add dependency and verify branch.