Manage Meta Tags and Structured Data in Astro

Astro Headstart is a specialized utility library that simplifies HTML head tag management in Astro applications.

It allows you to handle both standard HTML metadata and modern social media tags through a single, well-designed API.

GitHub Repo

Features

🎯 Complete HTML head management through a single <Headstart /> component

📱 Full social media meta tag support for OpenGraph and X.com (Twitter) Cards

🔍 Built-in JSON-LD structured data generation with Schema.org helpers

🧩 Modular architecture with individual component exports

🎨 Theme color and color scheme management for modern browsers

🤖 Search engine optimization with robot directives and meta extensions

🔗 Flexible slot system for custom head element integration

📊 Pre-built schema helpers for articles, websites, and web applications

Use Cases

Blog and content websites requiring rich social media previews and structured data for better search visibility.
E-commerce sites needing product schema markup and social sharing optimization for increased engagement.
Corporate websites managing multiple page types with consistent metadata patterns and branding.
Portfolio sites showcasing work with proper OpenGraph images and creator attribution.
Documentation sites requiring clear navigation metadata and search engine optimization.

Installation

1. Install and add the astro-headstart package to your project.

# npm
npm install astro-headstart
# pnpm
pnpm add astro-headstart
# yarn
yarn add astro-headstart

2. If you use TypeScript and plan to work with structured data, you should also add schema-dts as a development dependency. This package provides type definitions for Schema.org, which enables autocompletion and type-checking for your JSON-LD objects.

# npm
npm install --save-dev schema-dts
# pnpm
pnpm add --save-dev schema-dts
# yarn
yarn add --dev schema-dts

Usage

1. You can use the main <Headstart /> component to manage all head content from a single location. Pass props for the title, description, social media details, and JSON-LD data. You can also insert additional head elements like <link> or <script> tags directly into the component’s default slot.

Here is an example of its use in a page layout.

---
import Headstart from 'astro-headstart';
import { article, website } from 'astro-headstart/jsonld';
const articleSchema = article({
  headline: "My Awesome Blog Post",
  description: "A description of this very awesome blog post.",
  author: { '@type': 'Person', name: "Jane Doe" },
  datePublished: "2025-07-28",
});
const websiteSchema = website({
  name: 'My Awesome Blog',
  url: Astro.site
});
---
<html>
  <head>
    <Headstart
      title="My Awesome Blog Post"
      description="A description for search engines."
      socials={{
        title: "Social Media Title for the Post",
        description: "A different description for social media.",
        image: {
          url: new URL('/social-image.jpg', Astro.site),
          alt: "A descriptive alt text for the image.",
          width: 1200,
          height: 630
        }
      }}
      jsonLd={[articleSchema, websiteSchema]}
    >
      <link rel="icon" href="/favicon.ico" />
    </Headstart>
  </head>
  <body>
    <!-- Page content -->
  </body>
</html>

2. For more specific needs, you can import and use individual components from the library’s subpaths. This approach is useful if you only need to manage a specific type of metadata, such as OpenGraph tags or JSON-LD.

---
import { StandardMeta, OGMetaExtensions } from 'astro-headstart/meta';
import { JSONLinkedData } from 'astro-headstart/jsonld';
import { website } from 'astro-headstart/jsonld';
const websiteSchema = website({ name: "My Website", url: "https://example.com" });
---
<head>
  <StandardMeta
    charset="utf-8"
    description="A page with custom meta implementation."
  />
  <OGMetaExtensions
    type="website"
    title="My Custom Website"
    description="A description for social media."
  />
  <JSONLinkedData data={websiteSchema} />
</head>

Related Resources

Astro Documentation – Official Astro framework documentation covering components, layouts, and build optimization.
Schema.org – Structured data vocabulary and types for creating rich search results.
OpenGraph Protocol – Social media preview specification used by Facebook, LinkedIn, and other platforms.
Google Rich Results Test – Tool for testing and validating your structured data implementation.

FAQs

Q: Can I use Astro Headstart with existing meta tags in my project?
A: Yes, Astro Headstart works alongside existing meta tags. The component generates additional tags without conflicts, and you can use the slot system to include custom head elements.

Q: Does Astro Headstart work with all Astro rendering modes?
A: Astro Headstart supports all Astro rendering modes, including static site generation (SSG), server-side rendering (SSR), and hybrid rendering. The components render at build time with no client-side JavaScript.

Q: How do I test if my structured data is working correctly?
A: Use Google’s Rich Results Test tool to validate your JSON-LD structured data. The tool shows how Google interprets your markup and identifies any issues that might prevent rich results from appearing.

Q: Can I customize the JSON-LD output beyond the pre-built helpers?
A: Yes, you can pass any valid Schema.org structured data to the jsonLd prop. The pre-built helpers are convenience functions, but you can create custom schema objects following the Schema.org specification.

Q: What happens if I don’t provide social media images?
A: Social media platforms will fall back to their default behavior, typically showing a basic link preview without an image. For better engagement, provide at least a 1200×630 pixel image for OpenGraph and Twitter Cards.

Q: What is schema-dts and why is it recommended?
A: schema-dts is a package of TypeScript definitions for Schema.org. It is a dev dependency that provides autocompletion and type-checking in your editor when you create JSON-LD objects, which helps prevent errors.