How to Customize open-seo.ts for Specific SEO Requirements

Yes, open-seo.ts (the core utility at web/src/lib/seo.ts in the every-app/open-seo repository) supports extensive customization through environment variables, the buildPageSeo function parameters, and constant overrides, allowing you to tailor SEO metadata for any project requirement without altering the underlying logic.

The open-seo.ts module serves as the central SEO engine for the OpenSEO project, generating meta tags, canonical links, and Open Graph data for every page. Located in the every-app/open-seo repository, this TypeScript utility is intentionally designed with flexibility in mind, offering multiple configuration layers that range from global site settings to granular, page-specific metadata control.

Site-Wide Configuration via Environment Variables

The foundation of open-seo.ts customization starts with the SITE_URL constant defined at lines 5-9 of web/src/lib/seo.ts. By default, this resolves to https://openseo.so, but you can override it using environment variables:

• SITE_URL – Primary server-side environment variable
• VITE_SITE_URL – Client-side variable for Vite-based builds

When either variable is present, the utility uses your custom domain for all canonical URL generation. Create or modify your .env file at the project root:

SITE_URL=https://mycustomdomain.com
VITE_SITE_URL=https://mycustomdomain.com

This change immediately propagates to all canonical links generated by the toCanonicalUrl helper function at lines 18-20, ensuring every page references your production domain correctly.

Page-Level Customization with buildPageSeo

For granular control, the buildPageSeo function (lines 22-44) accepts a flexible parameter object defined by the BuildSeoParams type. This allows complete customization of individual page metadata:

Required parameters:

• title – The page title
• path – The URL path (e.g., /blog/my-post)

Optional parameters:

• description – Meta description content
• titleSuffix – Appended to the title (e.g., " | My Site")
• ogType – Open Graph type: "website" or "article"
• imageAlt – Alt text for the social sharing image

Because these values pass directly through function arguments, you can dynamically generate SEO metadata based on CMS content, user state, or route parameters without touching the core library code.

Customizing Canonical URLs and Social Images

The utility provides specific helpers for URL normalization and social media assets. The toCanonicalPath function at lines 11-16 automatically normalizes any path and strips trailing slashes, ensuring consistent canonical URLs regardless of how the path is input.

For social sharing images, the DEFAULT_SOCIAL_IMAGE_PATH constant at line 2 defaults to /social-card.png. You can customize this at the project level by modifying the constant:

// web/src/lib/seo.ts
const DEFAULT_SOCIAL_IMAGE_PATH = "/custom-card.png";

Alternatively, since the buildPageSeo function constructs the full image URL using the configured SITE_URL and the default path, changing the environment variable automatically updates the social image domain, while per-page overrides can be handled through the imageAlt parameter and custom meta tag extensions.

Framework Implementation Examples

SvelteKit Integration

In a SvelteKit application, import buildPageSeo in your +page.ts load functions to generate SEO data server-side:

// src/routes/blog/[slug]/+page.ts
import { buildPageSeo } from '$lib/seo';

export const load = async ({ params }) => {
  const { slug } = params;
  const post = await fetchPost(slug);

  const seo = buildPageSeo({
    title: post.title,
    path: `/blog/${slug}`,
    description: post.excerpt,
    titleSuffix: 'My Blog',
    ogType: 'article',
    imageAlt: `${post.title} – featured image`,
  });

  return { post, seo };
};

This returns a complete SEO object containing meta tags and canonical links that you can render in your page template.

React Client-Side Usage

For React applications using client-side rendering, you can consume the same utility to populate react-helmet or similar head management libraries:

import { buildPageSeo } from '@/lib/seo';

function Head({ title, description }) {
  const seo = buildPageSeo({
    title,
    path: window.location.pathname,
    description,
    titleSuffix: 'MyApp',
  });

  return (
    <Helmet>
      {seo.meta.map((tag, i) =>
        tag.title ? (
          <title key={i}>{tag.title}</title>
        ) : tag.name ? (
          <meta key={i} name={tag.name} content={tag.content} />
        ) : (
          <meta
            key={i}
            property={tag.property}
            content={tag.content}
          />
        )
      )}
      <link rel="canonical" href={seo.links[0].href} />
    </Helmet>
  );
}

Summary

• Environment variables (SITE_URL, VITE_SITE_URL) control the base domain for all canonical URLs without code changes.
• The buildPageSeo function accepts flexible parameters including title, path, description, titleSuffix, ogType, and imageAlt for page-specific metadata.
• Canonical URL normalization is handled automatically by toCanonicalPath (lines 11-16), while toCanonicalUrl (lines 18-20) constructs the full URL.
• The default social image path can be modified via the DEFAULT_SOCIAL_IMAGE_PATH constant at line 2 of web/src/lib/seo.ts.
• All configuration options work across frameworks including SvelteKit and React, as demonstrated in the implementation examples.

Frequently Asked Questions

Can I use open-seo.ts with frameworks other than SvelteKit?

Yes, while open-seo.ts resides in web/src/lib/seo.ts and is optimized for SvelteKit, the core logic is framework-agnostic. The buildPageSeo function returns a plain JavaScript object containing meta tag arrays and canonical links, which you can render in React, Vue, or Angular using the appropriate head management library.

How do I change the default social image across all pages?

Modify the DEFAULT_SOCIAL_IMAGE_PATH constant at line 2 of web/src/lib/seo.ts to point to your preferred image path (e.g., /custom-card.png). Since the utility constructs absolute URLs using the configured SITE_URL, updating the environment variable also ensures the social image references the correct domain in production.

What environment variables control the site domain?

The utility checks for SITE_URL (server-side) and VITE_SITE_URL (client-side for Vite builds) at lines 5-9 of web/src/lib/seo.ts. Setting either variable overrides the default https://openseo.so domain, affecting all canonical URLs and social image references generated by the library.

Is it possible to customize the canonical URL path normalization?

The toCanonicalPath function at lines 11-16 handles normalization by stripping trailing slashes and standardizing path formats. While the source code provides sensible defaults, you can fork or modify this function in web/src/lib/seo.ts to implement custom normalization rules, such as adding locale prefixes or handling specific route patterns, without breaking the rest of the SEO generation logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}