reactyll

Multilingual static blog tooling for React. reactyll provides TypeScript types, helpers to resolve posts by language, and a build-time pipeline that turns Markdown (and metadata) into lazy routes and a blogs registry—so your app can list posts, deep-link per locale, and emit correct hreflang metadata.

Introduction

• Problem: Marketing sites often need many localized URLs for the same article, consistent metadata (title, description, OG tags, alternates), and a single place to define “all posts” for listing pages and footers.
• Approach: At build time, a CLI (e.g. blogger) reads your content, generates a routes module (e.g. blogRoutes + blogs), and injects per-page payload into a template component you own (so you keep full control over layout, Markdown rendering, and analytics). reactyll is the library surface (types + getBlogForLanguage). The generator typically lives in the same ecosystem and is configured from your app’s package.json.

Requirements

• Node.js 18+ (or as specified by your consuming app)
• A React app with a static router (e.g. vite-react-ssg, Next.js static export, or similar) if you use the default route shape

Installation

npm install --save-dev reactyll
# or
yarn add -D reactyll

If your setup uses the blog generator CLI, ensure the binary is on your PATH (often provided by the same package or a companion package—follow the version you publish).

Setup

1. Add a blog template component Create a React component that:

Imports types from reactyll, e.g. BlogPage. Declares extra fields your posts need (SEO, dates, related slugs, etc.). Contains a placeholder the CLI replaces with encoded JSON (convention used in the wild: %REPLACE% → JSON.parse(decodeURIComponent(atob('…')))). Example skeleton:

import { BlogPage } from "reactyll";
export interface ExtraProperties {
  date: string;
  headline: string;
  description: string;
  publishDate: string;
  readMore?: string[];
}
const content: BlogPage<ExtraProperties> = JSON.parse(
  decodeURIComponent(atob(`%REPLACE%`))
);
export default function BlogPost() {
  return (
    <>
      <title>{content.properties.title}</title>
      {content.languages.map(([lang, url]) => (
        <link key={lang} rel="alternate" hrefLang={lang} href={url} />
      ))}
      {/* Render content.markdown with your preferred Markdown component */}
    </>
  );
}

2. Configure the generator In package.json:

{
  "scripts": {
    "build-blog": "blogger"
  },
  "blogger": {
    "template": "src/components/BlogTemplate.tsx"
  }
}

Run yarn build-blog (or npm run build-blog) before dev/build so generated files exist (e.g. src/_blog/routes.tsx).

3. Wire routes Import generated blogRoutes and merge with your static routes. Shape is typically an array of [path, Component] (exact type may vary by version):

import { blogRoutes } from "./_blog/routes";
const routes = [
  ...staticRoutes,
  ...blogRoutes.map(([url, Component]) => ({
    path: url,
    Component,
  })),
];

Import blogs from the same module for indexes, footers, and cross-links.

Multilingual behavior blogs: A map (or similar structure) from post id to a language wrapper—for each post, one object keyed by locale codes (en, fr, …). getBlogForLanguage(wrapper, currentLanguage, fallbackLanguage) Returns the BlogProperties (plus your extras) for currentLanguage, or falls back (e.g. to "en") when a translation is missing. BlogPage payload (per generated page) usually includes: properties — title, url, description, optional language, etc. markdown — body for your Markdown renderer. languages — [locale, absoluteOrSitePathUrl][] for and optional ?lang= switching. Separation of concerns: reactyll handles post localization. UI chrome (buttons, nav labels) is often handled by i18next / react-i18next; pass i18n.language into getBlogForLanguage so lists and cards match the user’s locale.

Examples

Blog index (sorted, localized cards)

import { RouteWrapper, BlogProperties, getBlogForLanguage } from "reactyll";
import { blogs } from "../_blog/routes";
import { useTranslation } from "react-i18next";
type Extra = { headline: string; publishDate: string /* … */ };
function BlogIndex() {
  const { i18n } = useTranslation();
  return (
    <ul>
      {Object.values(blogs as RouteWrapper<Extra>).map((wrapper) => {
        const post = getBlogForLanguage(wrapper, i18n.language, "en") as BlogProperties & Extra;
        return (
          <li key={post.url}>
            <a href={post.url}>{post.title}</a>
            <p>{post.headline}</p>
          </li>
        );
      })}
    </ul>
  );
}

Related posts

Store related slugs in metadata, then resolve each with the same language:

const related = post.readMore?.map((slug) =>
  getBlogForLanguage(blogs[slug], i18n.language, "en")
);

Internal Markdown links

Resolve blog/ style links to the localized URL by looking up blogs[slug] for the active language (pattern used in full-featured templates).