ShipTanStarter Docs

This guide covers the metadata system in ShipTanStarter and how to customize SEO settings.

Core Features

The ShipTanStarter template comes with a built-in metadata system that provides:

SEO-optimized page titles and descriptions
Social media sharing metadata (Open Graph and Twitter)
Favicon and app icons (Logo and Favicon)

Understanding the Metadata System

The metadata system in ShipTanStarter is configured through several key files:

1. Website Configuration

The main website configuration is defined in src/config/website.ts:

src/config/website.ts

import { messages } from '@/messages';

export const websiteConfig: WebsiteConfig = {
  metadata: {
    name: messages.site.name,
    title: messages.site.title,
    description: messages.site.description,
    images: {
      ogImage: '/og.png',
      logoLight: '/logo.png',
      logoDark: '/logo-dark.png',
    },
  },
  social: {
    github: 'https://github.com/MkFastHQ',
    discord: 'https://mksaas.link/discord',
    twitter: 'https://x.com/ShipTanStarter',
    youtube: 'https://www.youtube.com/@ShipTanStarter',
  },
  // Other configuration sections...
};

This configuration defines:

Website name, title, and description from the messages module
Logo and Open Graph image paths
Social media official account links

2. Messages Files

The basic website metadata such as name, title, and description are defined in the messages files:

src/messages/en.ts

export const messages = {
  site: {
    name: 'ShipTanStarter',
    title: 'ShipTanStarter - The Best SaaS Boilerplate',
    description: 'ShipTanStarter is a full-stack SaaS boilerplate...',
  },
  // other messages...
} as const;

src/messages/zh.ts

export const messages = {
  site: {
    name: 'ShipTanStarter',
    title: 'ShipTanStarter - 快速构建 SaaS 产品',
    description: 'ShipTanStarter 是一个使用最先进技术栈构建的 SaaS 模板...',
  },
  // other messages...
} as const;

To switch the active language, edit src/messages/index.ts and change the re-export to the desired language file.

3. SEO Helper

The seo() function in src/lib/seo.ts builds the metadata and canonical link for each page:

src/lib/seo.ts

export function seo(
  path: string,
  options: {
    title: string;
    description?: string;
    keywords?: string;
    image?: string;
    type?: 'website' | 'article';
  }
) {
  const url = getCanonicalUrl(path);
  const image = options.image ?? getOgImage();

  return {
    meta: metadata({ ...options, url, image, type: options.type ?? 'website' }),
    links: [{ rel: 'canonical', href: url }],
  };
}

This function handles:

Setting page title and description
Configuring Open Graph and Twitter card metadata
Setting up canonical URL
Generating the OG image URL

4. Using SEO in Routes

Each route defines its metadata via the head() function in createFileRoute:

src/routes/index.tsx

import { createFileRoute } from '@tanstack/react-router';
import { seo } from '@/lib/seo';

export const Route = createFileRoute('/')({
  head: () => ({
    ...seo('/', {
      title: 'ShipTanStarter - Home',
      description: 'Welcome to ShipTanStarter',
    }),
  }),
  component: HomePage,
});

5. Root Layout Metadata

The root route (src/routes/__root.tsx) defines global metadata like charset, viewport, favicons, and the default title/description:

src/routes/__root.tsx

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
}>()({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: websiteConfig.metadata?.title },
      { name: 'description', content: websiteConfig.metadata?.description },
    ],
    links: [
      { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' },
      { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon-32x32.png' },
      { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicon-16x16.png' },
      { rel: 'icon', href: '/favicon.ico' },
      { rel: 'manifest', href: '/manifest.json' },
    ],
  }),
  // ...
});

Customizing Website Metadata

Basic Website Information

To change the basic website information like name, title, and description, edit the messages file for your active language:

src/messages/en.ts

export const messages = {
  site: {
    name: 'Your Website Name',
    title: 'Your Website Title - Tagline',
    description: 'A detailed description of your website for SEO purposes',
  },
  // ...
} as const;

To change the Open Graph image and logos:

Place your image files in the public directory
Update the paths in src/config/website.ts:

src/config/website.ts

metadata: {
  // Other settings...
  images: {
    ogImage: '/your-og-image.png',      // Used for social sharing
    logoLight: '/your-logo-light.png',   // Logo for light mode
    logoDark: '/your-logo-dark.png',     // Logo for dark mode
  },
}

Recommended sizes:

OG Image: 1200×630 pixels for best display on social platforms
Logo: At least 512×512 pixels for high-resolution displays

Update your social media official account links in the website configuration:

src/config/website.ts

social: {
  github: 'https://github.com/YourUsername',
  twitter: 'https://x.com/YourHandle',
  discord: 'https://discord.gg/YourInvite',
  youtube: 'https://www.youtube.com/@YourChannel',
},

Favicons and App Icons (Favicon)

To replace the default favicons and app icons:

Generate a complete set of icons using a tool like Real Favicon Generator
Place the generated files in the public directory
The root route already links these files automatically

Page-Specific Metadata

For each route, use the seo() helper in the head() function:

export const Route = createFileRoute('/about')({
  head: () => ({
    ...seo('/about', {
      title: 'About Us',
      description: 'Learn more about our team',
      image: '/images/about-og.png',
    }),
  }),
  component: AboutPage,
});

Blog Post Metadata

Blog posts use frontmatter metadata that is automatically applied:

content/blog/example-post.md

---
title: Example Blog Post
description: This is an example blog post with custom metadata
image: https://example.com/images/blog/example-post.png
date: "2024-01-01"
category: tutorial
---

Content goes here...

Best Practices

Keep Titles Concise: Aim for titles under 60 characters for best display in search results
Descriptive Meta Descriptions: Write compelling descriptions of 150-160 characters
Use High-Quality Images: Create professional, relevant images for OG and Twitter cards
Include Keywords: Incorporate relevant keywords naturally in titles and descriptions
Update Consistently: Keep metadata current with your content changes
Mobile Optimization: Ensure your metadata looks good on mobile devices

Next Steps

Now that you understand how to customize metadata in the ShipTanStarter template, explore these related topics:

Blog

Configure blog system

Components

Customize UI components

Internationalization

Configure build-time language support

Website Configuration

Configure core website settings

Metadata

Blog

Components

Internationalization

Website Configuration

On this page