meta-tag-boilerplate — Next.js Starter Template

SHA-256: 65c9fc15a0049fa5f79bd95a19fc5f7c1a3e63dc1cddf8b26b2d83076f1b29de

2026-10-03T18:55:23.549Z

# Meta Tag Boilerplate

Modern, framework-agnostic meta tag boilerplates for SEO and social media optimization. Ready-to-use configurations for HTML, Next.js, and Vite projects.

## Features

- Multiple Frameworks: HTML, Next.js (App Router), and Vite (React/Vue)
- SEO Optimized: Complete meta tags for search engines
- Social Media Ready: Open Graph and Twitter Card support
- Copy-Paste Ready: Easy to integrate into your projects
- TypeScript Support: Fully typed for Next.js and Vite
- Modern Best Practices: Updated for 2024+ standards
- Schema.org Structured Data: JSON-LD support for rich results
- Dark Mode Support: Theme color configuration for light/dark modes

## Quick Navigation

Choose your framework:

### [HTML](./html/)

Traditional HTML setup for static websites or any web project.

- Static meta tags
- Comprehensive head setup
- Works with any backend or static site generator

### [Next.js](./nextjs/)

Modern setup using Next.js 13+ App Router Metadata API.

- Type-safe metadata configuration
- Static and dynamic metadata support
- Built-in SEO

### [Vite](./vite/)

Setup for Vite projects (React, Vue, and other frameworks).

- Static and dynamic meta tags
- React and Vue components included
- Environment variable support

## Quick Start

1. Choose your framework from the options above
2. Navigate to the framework folder
3. Follow the README in that folder for detailed instructions
4. Copy the boilerplate into your project
5. Replace placeholders with your actual values
6. Run the validation script to verify: `./scripts/validate.sh`

## Agent Skill

This repository ships an installable agent skill (`seo-meta-tags`) that teaches AI coding assistants the project's metadata conventions, placeholder tokens, quality checklist, and per-framework rules.

**Install via [skills.sh](https://skills.sh):**

```bash
npx skills add jeremy0x/meta-tag-boilerplate --skill seo-meta-tags
```

**Structure:**

```text
skills/seo-meta-tags/
├── SKILL.md              # Core workflow, quality gate, metadata families, security rules
├── references/
│   ├── canonical-model.md  # Abstract concept-to-implementation mapping across frameworks
│   ├── html.md           # HTML <head> tag reference & ordering
│   ├── nextjs.md         # Next.js Metadata API & generateMetadata patterns
│   ├── vite.md           # React (react-helmet-async) & Vue (@unhead/vue) components
│   └── tokens.json       # Canonical registry of all {{PLACEHOLDER}} tokens
└── scripts/
    └── validate.sh       # Automated quality gate (CI-ready)
```

## What's Included

### HTML

- `index.html` - Complete HTML boilerplate with modern meta tags
- `README.md` - Detailed documentation and best practices

### Next.js

- `metadata.ts` - Complete metadata configuration for App Router
- `dynamic-metadata-example.tsx` - Example of dynamic metadata generation
- `README.md` - Comprehensive guide with examples

### Vite

- `index.html` - Base HTML template with static meta tags
- `SEO.tsx` - React component for dynamic meta tags
- `SEO.vue` - Vue 3 component for dynamic meta tags
- `README.md` - Setup guide for both React and Vue

## Quality Gate

Run the validation script after replacing placeholders to catch common issues before deployment:

```bash
# Default mode — checks for leftover placeholders, alt text, URL formats, etc.
./scripts/validate.sh

# Template integrity mode — verifies all {{TOKEN}}s match the canonical registry
./scripts/validate.sh --check-templates
```

The 12-point quality gate covers: placeholder cleanup, absolute URLs, image alt text, duplicate tags, title/description length, JSON-LD validity, OG/Twitter parity, canonical URLs, theme color variants, hreflang, and robots directives.

## Placeholder Tokens

All template files use `{{PLACEHOLDER_NAME}}` tokens. The canonical registry at `skills/seo-meta-tags/references/tokens.json` is the single source of truth — every token's name, constraints, required status, and file membership is tracked there. Add new tokens to the registry first, then propagate to framework files.

## Key Meta Tags Included

All boilerplates include:

| Category | Meta Tags |
| --- | --- |
| **Essential** | charset, viewport, title, description, keywords |
| **SEO** | robots, canonical, author, keywords |
| **Theme** | theme-color (with dark/light mode support) |
| **Open Graph** | type, url, title, description, image, site_name |
| **Twitter** | card, title, description, image, site, creator |
| **Icons** | favicon, apple-touch-icon, manifest |
| **Structured Data** | JSON-LD schema markup |
| **i18n** | hreflang alternate links |

## Usage Examples

### HTML Example

```html
<!-- Just copy and paste into your HTML <head> -->
<title>My Awesome Website</title>
<meta name="description" content="Welcome to my website" />
```

### Next.js Example

```typescript
// app/layout.tsx or app/page.tsx
export const metadata: Metadata = {
  title: 'My Awesome Website',
  description: 'Welcome to my website',
  // ... more configuration
}
```

### Vite + React

```tsx
import { SEO } from './components/SEO'

function HomePage() {
  return (
    <>
      <SEO
        title="My Awesome Website"
        description="Welcome to my website"
      />
      <div>Content</div>
    </>
  )
}
```

### Vite + Vue

```vue
<template>
  <SEO
    title="My Awesome Website"
    description="Welcome to my website"
  />
  <div>Content</div>
</template>
```

## Image Recommendations

### Social Media Images (Open Graph / Twitter)

- **Dimensions**: 1200 x 630 pixels
- **Aspect Ratio**: 1.91:1
- **Format**: JPG or PNG
- **File Size**: Under 1MB
- **Alt Text**: Always provide descriptive alt text

### Favicons

Use these tools to generate favicons:

- [favicon.io](https://favicon.io/)
- [RealFaviconGenerator](https://realfavicongenerator.net/)

## Security

When implementing metadata with user-supplied or database-sourced values, follow these rules from the agent skill:

| Context | Risk | Mitigation |
| --- | --- | --- |
| HTML meta tag content | XSS via attribute injection | Escape `"`, `<`, `>`, `&` in all attribute values |
| JSON-LD string fields | Script injection | Use `JSON.stringify()` for all values |
| Dynamic HTML content | XSS via raw HTML | Never use `dangerouslySetInnerHTML` or `v-html` without DOMPurify |
| URL fields | Open redirect, SSRF | Validate URLs start with `https://` |

## Testing Your Metadata

Validate your implementation with these tools:

- **Local** — `./scripts/validate.sh` after placeholder substitution
- Facebook Sharing Debugger: <https://developers.facebook.com/tools/debug/>
- Twitter Card Validator: <https://cards-dev.twitter.com/validator>
- LinkedIn Post Inspector: <https://www.linkedin.com/post-inspector/>
- Schema Markup Validator: <https://validator.schema.org/>
- Open Graph Check: <https://www.opengraph.xyz/>

## Best Practices

1. Title: Keep under 60 characters to avoid truncation
2. Description: 150-160 characters is optimal
3. Images: Always use high-quality images (1200x630px)
4. Canonical URLs: Specify to avoid duplicate content issues
5. Mobile: Test on mobile devices
6. Accessibility: Include alt text for all images
7. Performance: Optimize images and use appropriate formats

## Migration Guide

### From Old HTML Boilerplate

1. Choose your framework (HTML, Next.js, or Vite)
2. Follow the Quick Start guide for that framework
3. Update your placeholder values

### From Other Solutions

- From react-helmet: Use Vite + React setup
- From vue-meta: Use Vite + Vue setup
- From next-seo: Use Next.js setup (built-in metadata API is better)

## Resources

- [Open Graph Protocol](https://ogp.me/)
- [Twitter Cards Documentation](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards)
- [Schema.org Documentation](https://schema.org/)
- [Google Search Central](https://developers.google.com/search/docs)
- [Next.js Metadata API](https://nextjs.org/docs/app/building-your-application/optimizing/metadata)

## Contributing

Contributions are welcome! If you have suggestions for improvements or find any issues:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

Feel free to use and modify the code for your own projects. If you found this repository helpful, please consider giving it a star!