Made a Metadata Manager with Tanstack Router

[jorgedanisc]

I needed a solution that would let me customize dynamically Metadata on my Vite React SPA with Tanstack Router. So I developed this:

Actual Code

// MetadataManager.tsx
import { useMatch, useMatches, useRouterState } from '@tanstack/react-router';
import { useEffect, createContext, useContext, useState, ReactNode, useMemo, useCallback, useRef } from 'react';
import createDOMPurify from 'dompurify';

const DOMPurify = createDOMPurify(window);

export interface CustomMetadataProps {
  title?: string;
  description?: string;
  keywords?: string[];
  author?: string;
  robots?: string;
  viewport?: string;
  canonicalUrl?: string;
  themeColor?: string;
  favicon?: string;

  ogTitle?: string;
  ogDescription?: string;
  ogImage?: string;
  ogType?: string;
  ogUrl?: string;

  twitterCard?: string;
  twitterTitle?: string;
  twitterDescription?: string;
  twitterImage?: string;
  twitterCreator?: string;
  twitterSite?: string;
}

type MetadataContextType = {
  setMetadata: (metadata: Partial<CustomMetadataProps>) => void;
};

const MetadataContext = createContext<MetadataContextType | null>(null);

export function useMetadata() {
  const context = useContext(MetadataContext);
  if (!context) {
    throw new Error('useMetadata must be used within a MetadataProvider');
  }
  return context;
}

const DEFAULT_METADATA: CustomMetadataProps = {
  title: 'My App',
  description: 'A modern web application',
  keywords: ['web', 'app', 'react'],
  author: 'Your Name',
  robots: 'index, follow',
  viewport: 'width=device-width, initial-scale=1',
  canonicalUrl: '',
  themeColor: '#000000',
  favicon: '/favicon.ico',
  ogTitle: 'My App',
  ogDescription: 'A modern web application',
  ogImage: '/og-image.png',
  ogType: 'website',
  ogUrl: '',
  twitterCard: 'summary_large_image',
  twitterTitle: 'My App',
  twitterDescription: 'A modern web application',
  twitterImage: '/twitter-image.png',
  twitterCreator: '@username',
  twitterSite: '@username'
};

export function MetadataProvider({ children }: { children: ReactNode }) {
  const [dynamicMetadata, setDynamicMetadata] = useState<Partial<CustomMetadataProps>>({});

  const setMetadata = useCallback((metadata: Partial<CustomMetadataProps>) => {
    setDynamicMetadata(prev => {
      const hasChanges = Object.entries(metadata).some(
        ([key, value]) => prev[key as keyof CustomMetadataProps] !== value
      );
      return hasChanges ? { ...prev, ...metadata } : prev;
    });
  }, []);

  const value = useMemo(() => ({ setMetadata }), [setMetadata]);

  return (
    <MetadataContext.Provider value={value}>
      <MetadataManager dynamicMetadata={dynamicMetadata} />
      {children}
    </MetadataContext.Provider>
  );
}

const sanitizeContent = (content: string | undefined): string => {
  if (!content) return '';
  return DOMPurify.sanitize(String(content), { ALLOWED_TAGS: [], ALLOWED_ATTR: [] });
};

const isValidUrl = (url: string | undefined): boolean => {
  if (!url) return false;
  try {
    if (url.startsWith('/')) return true;
    const parsed = new URL(url);
    return parsed.protocol === 'https:' && !url.startsWith('//') && !url.match(/^(data|javascript|vbscript|file):/i);
  } catch {
    return false;
  }
};

const sanitizeUrl = (url: string | undefined): string => {
  if (!url) return '';
  if (!isValidUrl(url)) return '';
  return DOMPurify.sanitize(url, { ALLOWED_TAGS: [], ALLOWED_ATTR: [] });
};

type MetadataManagerProps = {
  dynamicMetadata?: CustomMetadataProps;
};

export function MetadataManager({ dynamicMetadata = {} }: MetadataManagerProps) {
  const matches = useMatches();
  const match = matches[matches.length - 1];
  const { location } = useRouterState();
  const previousPathRef = useRef(location.pathname);
  const metadataRef = useRef<(HTMLMetaElement | HTMLLinkElement)[]>([]);
  const faviconRef = useRef<HTMLLinkElement[]>([]);
  const prevMetadataRef = useRef<CustomMetadataProps | null>(null);

  const metadata = useMemo(() => {
    const merged = { ...DEFAULT_METADATA };
    
    Object.entries(dynamicMetadata).forEach(([key, value]) => {
      if (value !== undefined) {
        merged[key as keyof CustomMetadataProps] = value;
      }
    });

    Object.entries(match.staticData).forEach(([key, value]) => {
      if (value !== undefined) {
        merged[key as keyof CustomMetadataProps] = value;
      }
    });

    if (!merged.twitterImage && merged.ogImage) {
      merged.twitterImage = merged.ogImage;
    }

    return merged;
  }, [dynamicMetadata, match.staticData]);

  const shouldUpdate = useMemo(() => {
    if (!prevMetadataRef.current) {
      prevMetadataRef.current = metadata;
      return true;
    }
    const hasChanges = Object.entries(metadata).some(
      ([key, value]) => prevMetadataRef.current?.[key as keyof CustomMetadataProps] !== value
    );
    if (hasChanges) {
      prevMetadataRef.current = metadata;
    }
    return hasChanges;
  }, [metadata]);

  const cleanup = useCallback(() => {
    metadataRef.current.forEach(tag => tag.remove());
    metadataRef.current = [];

    faviconRef.current.forEach(tag => tag.remove());
    faviconRef.current = [];
  }, []);

  const setMetaTag = useCallback((name: string, content: string | undefined, property?: string) => {
    if (!content) return null;

    const contentToUse = property?.includes('image') ? sanitizeUrl(content) : sanitizeContent(content);
    if (!contentToUse) return null;

    const nameToUse = sanitizeContent(name);
    const propertyToUse = property ? sanitizeContent(property) : '';
    
    const selector = property ? `meta[property="${propertyToUse}"]` : `meta[name="${nameToUse}"]`;
    let meta = document.querySelector(selector) as HTMLMetaElement;
    
    if (!meta) {
      meta = document.createElement('meta');
      if (property) {
        meta.setAttribute('property', propertyToUse);
      } else {
        meta.setAttribute('name', nameToUse);
      }
      document.head.appendChild(meta);
      metadataRef.current.push(meta);
    }
    
    const currentContent = meta.getAttribute('content');
    if (currentContent !== contentToUse) {
      meta.setAttribute('content', contentToUse);
    }
    
    return meta;
  }, []);

  const updateFavicon = useCallback((faviconUrl: string) => {
    try {
      faviconRef.current.forEach(tag => tag.remove());
      faviconRef.current = [];

      document.querySelectorAll('link[rel*="icon"]').forEach(el => {
        if (!faviconRef.current.includes(el as HTMLLinkElement)) {
          el.remove();
        }
      });

      if (isValidUrl(faviconUrl)) {
        const sanitizedUrl = sanitizeUrl(faviconUrl);
        if (!sanitizedUrl) return;

        const link = document.createElement('link');
        link.rel = 'icon';
        link.href = sanitizedUrl;
        document.head.appendChild(link);
        faviconRef.current.push(link);

        const appleLink = document.createElement('link');
        appleLink.rel = 'apple-touch-icon';
        appleLink.href = sanitizedUrl;
        document.head.appendChild(appleLink);
        faviconRef.current.push(appleLink);
      }
    } catch (error) {
      console.error('Error updating favicon:', error);
    }
  }, []);

  useEffect(() => {
    const currentPath = location.pathname;
    
    if (previousPathRef.current !== currentPath) {
      cleanup();
      previousPathRef.current = currentPath;
    }

    if (!shouldUpdate) return;

    const title = sanitizeContent(metadata.title);
    if (document.title !== title) {
      document.title = title;
    }

    setMetaTag('description', metadata.description);
    setMetaTag('keywords', metadata.keywords?.map(sanitizeContent).join(', '));
    setMetaTag('author', metadata.author);
    setMetaTag('robots', metadata.robots);
    setMetaTag('viewport', metadata.viewport);
    setMetaTag('theme-color', metadata.themeColor);

    if (isValidUrl(metadata.canonicalUrl)) {
      let link = document.querySelector('link[rel="canonical"]') as HTMLLinkElement;
      if (!link) {
        link = document.createElement('link');
        document.head.appendChild(link);
        metadataRef.current.push(link);
      }
      link.rel = 'canonical';
      link.href = sanitizeUrl(metadata.canonicalUrl) || '';
    }

    setMetaTag('og:title', metadata.ogTitle, 'og:title');
    setMetaTag('og:description', metadata.ogDescription, 'og:description');
    if (isValidUrl(metadata.ogImage)) {
      setMetaTag('og:image', metadata.ogImage, 'og:image');
      setMetaTag('og:image:secure_url', metadata.ogImage, 'og:image:secure_url');
    }
    setMetaTag('og:type', metadata.ogType, 'og:type');
    if (isValidUrl(metadata.ogUrl)) {
      setMetaTag('og:url', metadata.ogUrl, 'og:url');
    }

    setMetaTag('twitter:card', metadata.twitterCard);
    setMetaTag('twitter:title', metadata.twitterTitle);
    setMetaTag('twitter:description', metadata.twitterDescription);
    if (isValidUrl(metadata.twitterImage)) {
      setMetaTag('twitter:image', metadata.twitterImage);
    }
    setMetaTag('twitter:creator', metadata.twitterCreator);
    setMetaTag('twitter:site', metadata.twitterSite);

    if (metadata.favicon) {
      updateFavicon(metadata.favicon);
    }

    return cleanup;
  }, [shouldUpdate, location.pathname, cleanup, setMetaTag, updateFavicon, metadata]);

  useEffect(() => {
    let manifestLink = document.querySelector('link[rel="manifest"]') as HTMLLinkElement | null;
    if (!manifestLink) {
      manifestLink = document.createElement('link');
      manifestLink.rel = 'manifest';
      manifestLink.href = '/manifest.json';
      document.head.appendChild(manifestLink);
      metadataRef.current.push(manifestLink);
    }
  }, []);

  return null;
}

Basic set up

// somewhere in main.tsx or in your type declarations

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
  interface StaticDataRouteOption extends CustomMetadataProps {}
}

// __root.tsx
export const Route = createRootRouteWithContext()({
  component: () => {
    return (
      <>
        <MetadataProvider>
          <Outlet />
        </MetadataProvider>
        <TanStackRouterDevtools />
      </>
    );
  }
})

How to use?

There are two ways of using this, by specifying staticData on the tanstack route or by using the setMetadata from the Context.

export const Route = createFileRoute('/hello/')({
  staticData: {
    title: 'Hello',
    ogImage: "https://nationalparkexpress.com/wp-content/uploads/2023/09/leon-liu-_0aOFIW34rw-unsplash-1024x683.jpg"
  },
  component: <>Hey!</>,
})

or

function Hello() {
  const { setMetadata } = useMetadata();

  
  const handleClick = () => {
    setMetadata({
      title: 'Hello',
    });
  }

  return <button onClick={handleClick}>Change Metadata</button>
}

Hope that this would be helpful to anyone, and would appreciate any suggestion on improvements to this component, would love to ear feedback!