@kamansoft/vite-plugin-flatwave-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flatwave contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# vite-plugin-flatwave-react
+
+Vite content plugin for Markdown-driven, i18n-aware static React sites.
+
+## Install
+
+```bash
+npm install vite-plugin-flatwave-react
+```
+
+## Configure Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+import { flatwaveContent } from 'vite-plugin-flatwave-react';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    flatwaveContent({
+      contentDir: path.resolve(__dirname, 'src/content'),
+      locales: ['es', 'pt'],
+      defaultLocale: 'es',
+      strictMissingLocales: false,
+      componentsDir: path.resolve(__dirname, 'src/components'),
+      sitemap: { hostname: 'https://example.com' },
+    }),
+  ],
+});
+```
+
+## Content layout
+
+```text
+src/
+  content/
+    es/
+      index.md
+      about.md
+    pt/
+      index.md
+      about.md
+  components/
+    SimplePage.tsx
+```
+
+Each Markdown file needs baseline frontmatter:
+
+```yaml
+---
+title: 'Page title'
+slug: 'page-slug'
+id: 'unique-id'
+component: 'SimplePage'
+public: true
+description: 'Short description'
+canonical: '/es/page-slug'
+robots: 'index, follow'
+keywords: ['tag1', 'tag2']
+---
+Markdown body.
+```
+
+Additional frontmatter fields are preserved in `attributes` and forwarded to the React component.
+
+## React hooks
+
+```ts
+import {
+  useFlatwaveContent,
+  useFlatwaveRoutes,
+  useFlatwaveAlternatives,
+} from 'vite-plugin-flatwave-react/react';
+```
+
+## Build outputs
+
+During `vite build`, the plugin generates:
+
+- locale-prefixed static HTML route files
+- `route-manifest.json`
+- `sitemap.xml`
+- `robots.txt`
+- a virtual module for content lookup
+
+## Validation CLI
+
+```bash
+npx flatwave-validate --content-dir src/content --locales es,pt --default-locale es
+```
+
+Use `--strict-missing` to fail when locale variants are missing.
+
+## License
+
+MIT © 2026 Flatwave contributors.

package/dist/cli/validate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/validate.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { validateContent } from '../content/validator.js';
+const program = new Command();
+program
+    .name('flatwave-validate')
+    .description('Validate Flatwave Markdown content using the same rules as the Vite plugin.')
+    .requiredOption('--content-dir <dir>', 'Markdown content directory, e.g. src/content')
+    .requiredOption('--locales <locales>', 'Comma-separated locales, e.g. es,pt')
+    .requiredOption('--default-locale <locale>', 'Default locale, e.g. es')
+    .option('--components-dir <dirs>', 'Comma-separated component directories', 'src/components,src/pages')
+    .option('--strict-missing', 'Fail when locale variants are missing', false)
+    .option('--no-validate-components', 'Disable component existence validation')
+    .action(async (options) => {
+    const locales = options.locales
+        .split(',')
+        .map((locale) => locale.trim())
+        .filter(Boolean);
+    const componentsDir = options.componentsDir
+        .split(',')
+        .map((dir) => dir.trim())
+        .filter(Boolean);
+    const result = await validateContent({
+        contentDir: options.contentDir,
+        locales,
+        defaultLocale: options.defaultLocale,
+        componentsDir,
+        strictMissingLocales: options.strictMissing,
+        validateComponents: options.validateComponents,
+    });
+    for (const warning of result.warnings) {
+        console.warn(`[WARN] ${warning}`);
+    }
+    if (result.errors.length > 0) {
+        console.error('[ERROR] Flatwave validation failed:');
+        for (const error of result.errors) {
+            console.error(`  - ${error}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Flatwave validation passed for ${locales.join(', ')} with ${result.warnings.length} warning(s).`);
+});
+program.parseAsync(process.argv).catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/content/indexer.d.ts

@@ -0,0 +1,2 @@
+import type { FlatwaveContentIndex, FlatwaveContentOptions } from '../types';
+export declare function buildIndex(options: FlatwaveContentOptions): Promise<FlatwaveContentIndex>;

package/dist/content/indexer.js

@@ -0,0 +1,36 @@
+import { buildContentIndex } from './routeBuilder.js';
+import { routeForLocaleSlug, scanMarkdownFiles } from './scanner.js';
+export async function buildIndex(options) {
+    const parsed = await scanMarkdownFiles(options.contentDir, options.locales);
+    const byLocaleAndId = new Map();
+    const entries = [];
+    for (const file of parsed) {
+        const id = String(file.frontmatter.id || file.slug);
+        const key = `${file.locale}:${id}`;
+        byLocaleAndId.set(key, {
+            id,
+            locale: file.locale,
+            slug: file.slug,
+            path: routeForLocaleSlug(file.locale, file.slug),
+            file: file.file,
+            component: file.frontmatter.component ? String(file.frontmatter.component) : undefined,
+            public: file.frontmatter.public !== false &&
+                String(file.frontmatter.public ?? 'true').toLowerCase() !== 'false',
+            attributes: { ...file.frontmatter },
+            frontmatter: file.frontmatter,
+            body: file.body,
+            route: routeForLocaleSlug(file.locale, file.slug),
+            alternatives: {},
+        });
+        entries.push(byLocaleAndId.get(key));
+    }
+    const alternatives = {};
+    for (const entry of entries) {
+        alternatives[entry.id] ??= {};
+        alternatives[entry.id][entry.locale] = entry.route;
+    }
+    for (const entry of entries) {
+        entry.alternatives = alternatives[entry.id] ?? {};
+    }
+    return buildContentIndex(entries);
+}

package/dist/content/parser.d.ts

@@ -0,0 +1,7 @@
+import type { FlatwaveFrontmatter } from '../types';
+export interface MarkdownParseResult {
+    body: string;
+    attributes: FlatwaveFrontmatter;
+    frontmatter: FlatwaveFrontmatter;
+}
+export declare function parseMarkdown(source: string): MarkdownParseResult;

package/dist/content/parser.js

@@ -0,0 +1,11 @@
+import matter from 'gray-matter';
+export function parseMarkdown(source) {
+    const parsed = matter(source);
+    const frontmatter = parsed.data;
+    const attributes = { ...frontmatter };
+    return {
+        body: parsed.content.trim(),
+        attributes,
+        frontmatter,
+    };
+}

package/dist/content/routeBuilder.d.ts

@@ -0,0 +1,9 @@
+import type { FlatwaveContentEntry, FlatwaveFrontmatter, FlatwaveRoute } from '../types';
+export declare function buildContentIndex(entries: FlatwaveContentEntry[]): {
+    entries: FlatwaveContentEntry[];
+    byId: Record<string, Record<string, FlatwaveContentEntry>>;
+    byLocale: Record<string, Record<string, FlatwaveContentEntry>>;
+    routes: FlatwaveRoute[];
+};
+export declare function routeFromLocaleAndSlug(locale: string, slug: string): string;
+export declare function isPublicFrontmatter(frontmatter: FlatwaveFrontmatter): boolean;

package/dist/content/routeBuilder.js

@@ -0,0 +1,77 @@
+import { isPublicEntry, normalizeSlug } from './scanner.js';
+export function buildContentIndex(entries) {
+    const byId = {};
+    const byLocale = {};
+    const routes = [];
+    for (const entry of entries) {
+        if (!entry.public)
+            continue;
+        byId[entry.id] ??= {};
+        byLocale[entry.locale] ??= {};
+        byId[entry.id][entry.locale] = entry;
+        byLocale[entry.locale][entry.id] = entry;
+    }
+    for (const id of Object.keys(byId).sort()) {
+        const locales = Object.keys(byId[id]).sort();
+        const alternatives = buildAlternatives(locales, (locale) => byId[id][locale]?.route ?? '');
+        for (const locale of locales) {
+            const entry = byId[id][locale];
+            if (!entry)
+                continue;
+            routes.push({
+                locale: entry.locale,
+                path: entry.route,
+                contentId: entry.id,
+                component: entry.component,
+                metadata: buildSeoMetadata(entry.frontmatter, entry.route, entry.locale),
+                frontmatter: entry.frontmatter,
+                alternatives,
+            });
+        }
+    }
+    routes.sort((a, b) => `${a.locale}${a.path}`.localeCompare(`${b.locale}${b.path}`));
+    return {
+        entries: entries.filter((entry) => entry.public),
+        byId,
+        byLocale,
+        routes,
+    };
+}
+function buildAlternatives(locales, getRoute) {
+    const alternatives = {};
+    for (const locale of locales) {
+        const route = getRoute(locale);
+        if (route)
+            alternatives[locale] = route;
+    }
+    return alternatives;
+}
+function buildSeoMetadata(frontmatter, route, _locale) {
+    return {
+        title: String(frontmatter.title || ''),
+        description: frontmatter.description ? String(frontmatter.description) : undefined,
+        canonical: frontmatter.canonical ? String(frontmatter.canonical) : route,
+        image: frontmatter.image ? String(frontmatter.image) : undefined,
+        robots: frontmatter.robots ? String(frontmatter.robots) : 'index, follow',
+        keywords: Array.isArray(frontmatter.keywords) ? frontmatter.keywords.map(String) : undefined,
+        jsonLd: frontmatter.jsonLd,
+        og: recordValue(frontmatter.og),
+        twitter: recordValue(frontmatter.twitter),
+    };
+}
+function recordValue(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined && item !== null)
+            record[key] = String(item);
+    }
+    return Object.keys(record).length > 0 ? record : undefined;
+}
+export function routeFromLocaleAndSlug(locale, slug) {
+    return `/${locale}${normalizeSlug(slug)}`;
+}
+export function isPublicFrontmatter(frontmatter) {
+    return isPublicEntry(frontmatter);
+}

package/dist/content/scanner.d.ts

@@ -0,0 +1,13 @@
+import type { FlatwaveContentEntry, FlatwaveFrontmatter } from '../types';
+export interface ParsedMarkdownFile {
+    file: string;
+    locale: string;
+    slug: string;
+    body: string;
+    frontmatter: FlatwaveFrontmatter;
+}
+export declare function scanMarkdownFiles(contentDir: string, locales: string[]): Promise<ParsedMarkdownFile[]>;
+export declare function normalizeSlug(slug: string): string;
+export declare function routeForLocaleSlug(locale: string, slug: string): string;
+export declare function isPublicEntry(frontmatter: FlatwaveFrontmatter): boolean;
+export declare function buildContentEntry(parsed: ParsedMarkdownFile, alternatives: Record<string, string>): FlatwaveContentEntry;

package/dist/content/scanner.js

@@ -0,0 +1,64 @@
+import fg from 'fast-glob';
+import path from 'node:path';
+import matter from 'gray-matter';
+export async function scanMarkdownFiles(contentDir, locales) {
+    const files = [];
+    for (const locale of locales) {
+        const localeDir = path.resolve(contentDir, locale);
+        const matches = await fg('**/*.md', {
+            cwd: localeDir,
+            onlyFiles: true,
+            absolute: true,
+            ignore: ['**/node_modules/**'],
+        });
+        for (const file of matches.sort()) {
+            const source = await readFile(file);
+            const parsed = matter(source);
+            const frontmatter = parsed.data;
+            const slug = normalizeSlug(String(frontmatter.slug || path.basename(file, '.md')));
+            files.push({
+                file,
+                locale,
+                slug,
+                body: parsed.content.trim(),
+                frontmatter,
+            });
+        }
+    }
+    return files;
+}
+async function readFile(file) {
+    const fs = await import('node:fs/promises');
+    return fs.readFile(file, 'utf-8');
+}
+export function normalizeSlug(slug) {
+    return `/${slug.replace(/^\/+|\/+$/g, '')}`;
+}
+export function routeForLocaleSlug(locale, slug) {
+    const normalized = normalizeSlug(slug);
+    const isHome = normalized === '/' || normalized === '/index';
+    return isHome ? `/${locale}/` : `/${locale}${normalized}`;
+}
+export function isPublicEntry(frontmatter) {
+    if (typeof frontmatter.public === 'boolean')
+        return frontmatter.public;
+    return String(frontmatter.public ?? 'true').toLowerCase() !== 'false';
+}
+export function buildContentEntry(parsed, alternatives) {
+    const route = routeForLocaleSlug(parsed.locale, parsed.slug);
+    const attributes = { ...parsed.frontmatter };
+    return {
+        id: String(parsed.frontmatter.id || parsed.slug),
+        locale: parsed.locale,
+        slug: parsed.slug,
+        path: route,
+        file: parsed.file,
+        component: parsed.frontmatter.component ? String(parsed.frontmatter.component) : undefined,
+        public: isPublicEntry(parsed.frontmatter),
+        attributes,
+        frontmatter: parsed.frontmatter,
+        body: parsed.body,
+        route,
+        alternatives,
+    };
+}

package/dist/content/validator.d.ts

@@ -0,0 +1,2 @@
+import type { FlatwaveContentOptions, ValidationResult } from '../types';
+export declare function validateContent(options: FlatwaveContentOptions): Promise<ValidationResult>;

package/dist/content/validator.js

@@ -0,0 +1,168 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { routeForLocaleSlug, scanMarkdownFiles } from './scanner.js';
+import { buildContentIndex } from './routeBuilder.js';
+export async function validateContent(options) {
+    const errors = [];
+    const warnings = [];
+    const requiredFields = options.requiredFields ?? ['title', 'slug', 'id', 'component', 'public'];
+    const files = await scanMarkdownFiles(options.contentDir, options.locales);
+    await validateRequiredFields(files, requiredFields, errors);
+    await validateDuplicateIds(files, errors);
+    await validateDuplicateSlugs(files, errors);
+    await validateMenuPositions(files, errors);
+    await validateComponents(files, options, errors);
+    validateMissingLocales(files, options, warnings);
+    const entries = files.map((file) => {
+        const id = String(file.frontmatter.id || file.slug);
+        const route = routeForLocaleSlug(file.locale, file.slug);
+        return {
+            id,
+            locale: file.locale,
+            slug: file.slug,
+            path: route,
+            file: file.file,
+            component: file.frontmatter.component ? String(file.frontmatter.component) : undefined,
+            public: file.frontmatter.public !== false &&
+                String(file.frontmatter.public ?? 'true').toLowerCase() !== 'false',
+            attributes: file.frontmatter,
+            frontmatter: file.frontmatter,
+            body: file.body,
+            route,
+            alternatives: {},
+        };
+    });
+    const index = buildContentIndex(entries);
+    if (index.routes.length === 0) {
+        warnings.push(`No public routes were generated from ${options.contentDir}.`);
+    }
+    if (options.strictMissingLocales &&
+        warnings.some((warning) => warning.startsWith('[missing-locale]'))) {
+        errors.push(...warnings.filter((warning) => warning.startsWith('[missing-locale]')));
+    }
+    return { errors, warnings };
+}
+async function validateRequiredFields(files, requiredFields, errors) {
+    for (const file of files) {
+        for (const field of requiredFields) {
+            const value = file.frontmatter[field];
+            if (value === undefined || value === null || value === '') {
+                errors.push(`[${file.locale}] ${file.file}: Missing required frontmatter field: ${field}`);
+            }
+        }
+    }
+}
+async function validateDuplicateIds(files, errors) {
+    const seen = new Map();
+    for (const file of files) {
+        const id = String(file.frontmatter.id || file.slug);
+        const key = `${file.locale}:${id}`;
+        const previous = seen.get(key);
+        if (previous) {
+            errors.push(`[${file.locale}] ${file.file}: Duplicate content id '${id}'. First occurrence: ${previous}`);
+        }
+        else {
+            seen.set(key, file.file);
+        }
+    }
+}
+async function validateDuplicateSlugs(files, errors) {
+    const seen = new Map();
+    for (const file of files) {
+        const key = `${file.locale}:${file.slug}`;
+        const previous = seen.get(key);
+        if (previous) {
+            errors.push(`[${file.locale}] ${file.file}: Duplicate slug '${file.slug}'. First occurrence: ${previous}`);
+        }
+        else {
+            seen.set(key, file.file);
+        }
+    }
+}
+async function validateMenuPositions(files, errors) {
+    const seen = new Map();
+    for (const file of files) {
+        const menu = file.frontmatter.menu;
+        const position = file.frontmatter.menu_position;
+        if (menu === undefined || menu === '' || position === undefined || position === '')
+            continue;
+        const numeric = Number(position);
+        if (Number.isNaN(numeric)) {
+            errors.push(`[${file.locale}] ${file.file}: menu_position must be a number when menu is set.`);
+            continue;
+        }
+        const key = `${file.locale}:${menu}:${numeric}`;
+        const previous = seen.get(key);
+        if (previous) {
+            errors.push(`[${file.locale}] ${file.file}: Duplicate menu/menu_position '${menu}/${numeric}'. First occurrence: ${previous}`);
+        }
+        else {
+            seen.set(key, file.file);
+        }
+    }
+}
+async function validateComponents(files, options, errors) {
+    if (options.validateComponents === false)
+        return;
+    const available = await discoverComponents(options.componentsDir);
+    for (const file of files) {
+        const component = file.frontmatter.component ? String(file.frontmatter.component) : undefined;
+        if (!component)
+            continue;
+        if (!available.has(component)) {
+            errors.push(`[${file.locale}] ${file.file}: Component '${component}' does not exist in ${formatComponentsDir(options.componentsDir)}.`);
+        }
+    }
+}
+async function discoverComponents(componentsDir) {
+    const dirs = Array.isArray(componentsDir)
+        ? componentsDir
+        : componentsDir
+            ? [componentsDir]
+            : ['src/components', 'src/pages'];
+    const components = new Set();
+    for (const dir of dirs) {
+        const absolute = path.resolve(dir);
+        let files;
+        try {
+            files = (await readdir(absolute, { withFileTypes: true }));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.isFile())
+                continue;
+            if (!/\.(tsx?|jsx?)$/.test(file.name))
+                continue;
+            components.add(file.name.replace(/\.[^.]+$/, ''));
+        }
+    }
+    return components;
+}
+function validateMissingLocales(files, options, warnings) {
+    const idsByLocale = new Map();
+    for (const file of files) {
+        const id = String(file.frontmatter.id || file.slug);
+        if (!idsByLocale.has(file.locale))
+            idsByLocale.set(file.locale, new Set());
+        idsByLocale.get(file.locale)?.add(id);
+    }
+    const allIds = new Set();
+    for (const ids of idsByLocale.values()) {
+        for (const id of ids)
+            allIds.add(id);
+    }
+    for (const id of allIds) {
+        for (const locale of options.locales) {
+            if (!idsByLocale.get(locale)?.has(id)) {
+                warnings.push(`[missing-locale] Content id '${id}' is missing locale '${locale}'.`);
+            }
+        }
+    }
+}
+function formatComponentsDir(componentsDir) {
+    if (!componentsDir)
+        return 'src/components or src/pages';
+    return Array.isArray(componentsDir) ? componentsDir.join(', ') : componentsDir;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+import type { FlatwaveContentOptions } from './types';
+export declare function flatwaveContent(options: FlatwaveContentOptions): Plugin[];
+export default flatwaveContent;

package/dist/index.js

@@ -0,0 +1,246 @@
+import path from 'node:path';
+import { buildIndex } from './content/indexer.js';
+import { validateContent } from './content/validator.js';
+import { parseMarkdown } from './content/parser.js';
+import { routeForLocaleSlug } from './content/scanner.js';
+import { escapeHtml, escapeXml, renderHtmlHead } from './seo/metadata.js';
+const VIRTUAL_ID = '\0virtual:flatwave/content';
+const PUBLIC_VIRTUAL_ID = 'virtual:flatwave/content';
+// Test comment for lint-staged
+export function flatwaveContent(options) {
+    const normalizedOptions = normalizeOptions(options);
+    let index = { entries: [], byId: {}, byLocale: {}, routes: [] };
+    return [
+        {
+            name: 'flatwave-react:content',
+            enforce: 'pre',
+            async buildStart() {
+                index = await buildIndex(normalizedOptions);
+                const validation = await validateContent(normalizedOptions);
+                for (const warning of validation.warnings)
+                    this.warn(warning);
+                for (const error of validation.errors)
+                    this.error(error);
+            },
+            resolveId(id) {
+                if (id === PUBLIC_VIRTUAL_ID)
+                    return VIRTUAL_ID;
+                return null;
+            },
+            load(id) {
+                if (id !== VIRTUAL_ID)
+                    return null;
+                return createVirtualModule(index, normalizedOptions.defaultLocale);
+            },
+            async handleHotUpdate(ctx) {
+                if (!ctx.file.endsWith('.md'))
+                    return;
+                index = await buildIndex(normalizedOptions);
+            },
+        },
+        {
+            name: 'flatwave-react:markdown',
+            enforce: 'pre',
+            resolveId(id) {
+                if (id.endsWith('.md')) {
+                    const resolved = path.resolve(process.cwd(), id);
+                    return resolved;
+                }
+                return null;
+            },
+            async load(id) {
+                if (!id.endsWith('.md'))
+                    return null;
+                const source = await readFile(id);
+                const parsed = parseMarkdown(source);
+                const locale = inferLocale(id, normalizedOptions.contentDir, normalizedOptions.locales) ??
+                    normalizedOptions.defaultLocale;
+                const slug = path.basename(id, '.md');
+                const route = routeForLocaleSlug(locale, slug);
+                const idValue = slug;
+                return `export default ${JSON.stringify({
+                    body: parsed.body,
+                    attributes: parsed.attributes,
+                    frontmatter: parsed.frontmatter,
+                    locale,
+                    slug,
+                    id: idValue,
+                    route,
+                    file: id,
+                }, null, 2)};`;
+            },
+        },
+        {
+            name: 'flatwave-react:ssg',
+            async generateBundle(_, bundle) {
+                const routes = index.routes;
+                const html = findIndexHtml(bundle);
+                const assets = extractAssets(html);
+                if (normalizedOptions.emitRouteManifest !== false) {
+                    this.emitFile({
+                        type: 'asset',
+                        fileName: 'route-manifest.json',
+                        source: JSON.stringify(routes, null, 2),
+                    });
+                }
+                if (normalizedOptions.emitSitemap !== false) {
+                    this.emitFile({
+                        type: 'asset',
+                        fileName: 'sitemap.xml',
+                        source: renderSitemap(routes, normalizedOptions.sitemap?.hostname ?? 'http://localhost:4173'),
+                    });
+                }
+                if (normalizedOptions.emitRobotsTxt !== false) {
+                    this.emitFile({
+                        type: 'asset',
+                        fileName: 'robots.txt',
+                        source: renderRobotsTxt(normalizedOptions.sitemap?.hostname ?? 'http://localhost:4173'),
+                    });
+                }
+                for (const route of routes) {
+                    this.emitFile({
+                        type: 'asset',
+                        fileName: `${route.path.replace(/^\//, '').replace(/\/$/, '')}/index.html`,
+                        source: renderRouteHtml(route, assets),
+                    });
+                }
+            },
+        },
+    ];
+}
+function normalizeOptions(options) {
+    if (!options.locales.includes(options.defaultLocale)) {
+        throw new Error(`defaultLocale '${options.defaultLocale}' must be included in locales.`);
+    }
+    return {
+        ...options,
+        requiredFields: options.requiredFields ?? ['title', 'slug', 'id', 'component', 'public'],
+        validateComponents: options.validateComponents ?? true,
+        componentsDir: options.componentsDir,
+        emitRouteManifest: options.emitRouteManifest ?? true,
+        emitSitemap: options.emitSitemap ?? true,
+        emitRobotsTxt: options.emitRobotsTxt ?? true,
+    };
+}
+function createVirtualModule(index, defaultLocale) {
+    const content = index.entries;
+    const routes = index.routes;
+    return `
+const content = ${JSON.stringify(content)};
+const routes = ${JSON.stringify(routes)};
+
+export function getContent(id, locale) {
+  if (locale) return content.find((entry) => entry.id === id && entry.locale === locale);
+  return content.find((entry) => entry.id === id);
+}
+
+export function getAllContent() {
+  return content;
+}
+
+export function getRoutes(locale) {
+  if (locale) return routes.filter((route) => route.locale === locale);
+  return routes;
+}
+
+export function getAlternatives(contentId, currentLocale) {
+  const entry = content.find((item) => item.id === contentId);
+  if (!entry) return {};
+  const alternatives = { ...entry.alternatives };
+  delete alternatives[currentLocale];
+  return alternatives;
+}
+
+export function getLocale(locale) {
+  return locale;
+}
+
+export function getLocales() {
+  return [...new Set(routes.map((route) => route.locale))];
+}
+
+export function getDefaultLocale() {
+  return ${JSON.stringify(defaultLocale)};
+}
+
+export const flatwaveContentIndex = ${JSON.stringify(index)};
+`;
+}
+async function readFile(file) {
+    const fs = await import('node:fs/promises');
+    return fs.readFile(file, 'utf-8');
+}
+function inferLocale(file, contentDir, locales) {
+    const relative = path.relative(path.resolve(contentDir), file);
+    const firstSegment = relative.split(path.sep)[0];
+    return locales.includes(firstSegment) ? firstSegment : undefined;
+}
+function findIndexHtml(bundle) {
+    for (const item of Object.values(bundle)) {
+        if (item &&
+            typeof item === 'object' &&
+            'fileName' in item &&
+            item.fileName === 'index.html' &&
+            'source' in item) {
+            return String(item.source);
+        }
+    }
+    return undefined;
+}
+function extractAssets(html) {
+    if (!html)
+        return { scripts: [], styles: [] };
+    const scripts = [...html.matchAll(/<script[^>]+src="([^"]+\.js)"[^>]*>/g)].map((match) => match[1]);
+    const styles = [
+        ...html.matchAll(/<link[^>]+rel="stylesheet"[^>]+href="([^"]+\.css)"[^>]*>/g),
+    ].map((match) => match[1]);
+    return { scripts, styles };
+}
+function renderSitemap(routes, hostname) {
+    const base = hostname.replace(/\/$/, '');
+    const urls = routes
+        .map((route) => {
+        const loc = `${base}${route.path}`;
+        return `<url><loc>${escapeXml(loc)}</loc><lastmod>${new Date().toISOString().slice(0, 10)}</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url>`;
+    })
+        .join('');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}</urlset>
+`;
+}
+function renderRobotsTxt(hostname) {
+    const base = hostname.replace(/\/$/, '');
+    return `User-agent: *
+Allow: /
+
+Sitemap: ${base}/sitemap.xml
+`;
+}
+function renderRouteHtml(route, assets) {
+    const scripts = assets.scripts
+        .map((src) => `<script type="module" crossorigin src="${escapeHtml(src)}"></script>`)
+        .join('\n');
+    const styles = assets.styles
+        .map((href) => `<link rel="stylesheet" href="${escapeHtml(href)}">`)
+        .join('\n');
+    const title = escapeHtml(route.metadata.title);
+    const description = route.metadata.description ? escapeHtml(route.metadata.description) : title;
+    return `<!doctype html>
+<html lang="${escapeHtml(route.locale)}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <meta name="description" content="${description}">
+  <link rel="canonical" href="${escapeHtml(route.metadata.canonical ?? route.path)}">
+  ${styles}
+  ${renderHtmlHead(route)}
+</head>
+<body>
+  <div id="root"></div>
+  ${scripts}
+</body>
+</html>
+`;
+}
+export default flatwaveContent;

package/dist/react/index.d.ts

@@ -0,0 +1,8 @@
+/// <reference path="../virtual.d.ts" />
+import { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes } from 'virtual:flatwave/content';
+export declare function useFlatwaveContent(id: string, locale?: string): import("virtual:flatwave/content").FlatwaveVirtualContent | undefined;
+export declare function useFlatwaveRoutes(locale?: string): import("virtual:flatwave/content").FlatwaveVirtualRoute[];
+export declare function useFlatwaveAlternatives(id: string, currentLocale?: string): Record<string, string>;
+export declare function useFlatwaveLocales(): string[];
+export declare function useFlatwaveLocale(locale?: string): string | undefined;
+export { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes };

package/dist/react/index.js

@@ -0,0 +1,18 @@
+import { useMemo } from 'react';
+import { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes, } from 'virtual:flatwave/content';
+export function useFlatwaveContent(id, locale) {
+    return useMemo(() => getContent(id, locale), [id, locale]);
+}
+export function useFlatwaveRoutes(locale) {
+    return useMemo(() => getRoutes(locale), [locale]);
+}
+export function useFlatwaveAlternatives(id, currentLocale) {
+    return useMemo(() => getAlternatives(id, currentLocale), [id, currentLocale]);
+}
+export function useFlatwaveLocales() {
+    return useMemo(() => getLocales(), []);
+}
+export function useFlatwaveLocale(locale) {
+    return useMemo(() => getLocale(locale), [locale]);
+}
+export { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes };

package/dist/react/virtual.d.ts

@@ -0,0 +1,41 @@
+declare module 'virtual:flatwave/content' {
+  export interface FlatwaveVirtualContent {
+    id: string;
+    locale: string;
+    slug: string;
+    path: string;
+    file: string;
+    component?: string;
+    public: boolean;
+    attributes: Record<string, unknown>;
+    frontmatter: Record<string, unknown>;
+    body: string;
+    route: string;
+    alternatives: Record<string, string>;
+  }
+
+  export interface FlatwaveVirtualRoute {
+    locale: string;
+    path: string;
+    contentId: string;
+    component?: string;
+    metadata: Record<string, unknown>;
+    frontmatter: Record<string, unknown>;
+    alternatives: Record<string, string>;
+  }
+
+  export function getContent(id: string, locale?: string): FlatwaveVirtualContent | undefined;
+  export function getAllContent(): FlatwaveVirtualContent[];
+  export function getRoutes(locale?: string): FlatwaveVirtualRoute[];
+  export function getAlternatives(
+    contentId: string,
+    currentLocale?: string
+  ): Record<string, string>;
+  export function getLocale(locale?: string): string | undefined;
+  export function getLocales(): string[];
+  export function getDefaultLocale(): string;
+  export const flatwaveContentIndex: {
+    entries: FlatwaveVirtualContent[];
+    routes: FlatwaveVirtualRoute[];
+  };
+}

package/dist/seo/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { FlatwaveRoute, SeoMetadata } from '../types';
+export declare function escapeHtml(value: string): string;
+export declare function escapeXml(value: string): string;
+export declare function renderHtmlHead(route: FlatwaveRoute): string;
+export declare function escapeJsonScript(value: string): string;
+export declare function buildSeoMetadata(metadata: SeoMetadata): string;

package/dist/seo/metadata.js

@@ -0,0 +1,57 @@
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+export function escapeXml(value) {
+    return escapeHtml(value).replace(/"/g, '&quot;');
+}
+export function renderHtmlHead(route) {
+    const metadata = route.metadata;
+    const tags = [];
+    if (metadata.description)
+        tags.push(`<meta name="description" content="${escapeHtml(metadata.description)}">`);
+    if (metadata.robots)
+        tags.push(`<meta name="robots" content="${escapeHtml(metadata.robots)}">`);
+    if (metadata.canonical)
+        tags.push(`<link rel="canonical" href="${escapeHtml(metadata.canonical)}">`);
+    if (metadata.image) {
+        tags.push(`<meta property="og:image" content="${escapeHtml(metadata.image)}">`);
+        tags.push(`<meta name="twitter:image" content="${escapeHtml(metadata.image)}">`);
+    }
+    for (const [locale, alternate] of Object.entries(route.alternatives).sort()) {
+        tags.push(`<link rel="alternate" hreflang="${escapeHtml(locale)}" href="${escapeHtml(alternate)}">`);
+    }
+    for (const [property, value] of Object.entries(metadata.og ?? {})) {
+        tags.push(`<meta property="og:${escapeHtml(property)}" content="${escapeHtml(value)}">`);
+    }
+    for (const [name, value] of Object.entries(metadata.twitter ?? {})) {
+        tags.push(`<meta name="twitter:${escapeHtml(name)}" content="${escapeHtml(value)}">`);
+    }
+    if (metadata.jsonLd) {
+        tags.push(`<script type="application/ld+json">${escapeJsonScript(JSON.stringify(metadata.jsonLd))}</script>`);
+    }
+    return tags.join('\n  ');
+}
+export function escapeJsonScript(value) {
+    return value
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+export function buildSeoMetadata(metadata) {
+    const route = {
+        locale: '',
+        path: metadata.canonical ?? '/',
+        contentId: '',
+        metadata,
+        frontmatter: {},
+        alternatives: {},
+    };
+    return renderHtmlHead(route);
+}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+export type FlatwaveFallbackPolicy = 'default' | 'warn' | 'error';
+export interface FlatwaveSitemapOptions {
+    hostname?: string;
+    changefreq?: string;
+    priority?: number;
+}
+export interface FlatwaveRobotsOptions {
+    allowAll?: boolean;
+    sitemapPath?: string;
+    rules?: string[];
+}
+export interface FlatwaveContentOptions {
+    contentDir: string;
+    locales: string[];
+    defaultLocale: string;
+    fallback?: FlatwaveFallbackPolicy;
+    strictMissingLocales?: boolean;
+    requiredFields?: string[];
+    validateComponents?: boolean;
+    componentsDir?: string | string[];
+    emitRouteManifest?: boolean;
+    emitSitemap?: boolean;
+    emitRobotsTxt?: boolean;
+    sitemap?: FlatwaveSitemapOptions;
+    robots?: FlatwaveRobotsOptions;
+}
+export interface FlatwaveFrontmatter extends Record<string, unknown> {
+    title: string;
+    slug: string;
+    id: string;
+    component: string;
+    public?: boolean | string;
+    description?: string;
+    canonical?: string;
+    image?: string;
+    robots?: string;
+    keywords?: string[];
+    jsonLd?: unknown;
+    og?: Record<string, string>;
+    twitter?: Record<string, string>;
+    menu?: string;
+    menu_position?: number | string;
+}
+export interface FlatwaveContentEntry {
+    id: string;
+    locale: string;
+    slug: string;
+    path: string;
+    file: string;
+    component?: string;
+    public: boolean;
+    attributes: FlatwaveFrontmatter;
+    frontmatter: FlatwaveFrontmatter;
+    body: string;
+    route: string;
+    alternatives: Record<string, string>;
+}
+export interface FlatwaveRoute {
+    locale: string;
+    path: string;
+    contentId: string;
+    component?: string;
+    metadata: SeoMetadata;
+    frontmatter: FlatwaveFrontmatter;
+    alternatives: Record<string, string>;
+}
+export interface FlatwaveContentIndex {
+    entries: FlatwaveContentEntry[];
+    byId: Record<string, Record<string, FlatwaveContentEntry>>;
+    byLocale: Record<string, Record<string, FlatwaveContentEntry>>;
+    routes: FlatwaveRoute[];
+}
+export interface SeoMetadata {
+    title: string;
+    description?: string;
+    canonical?: string;
+    image?: string;
+    robots?: string;
+    keywords?: string[];
+    jsonLd?: unknown;
+    og?: Record<string, string>;
+    twitter?: Record<string, string>;
+}
+export interface ValidationResult {
+    errors: string[];
+    warnings: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@kamansoft/vite-plugin-flatwave-react",
+  "version": "0.1.0",
+  "description": "Vite content plugin for Markdown-driven, i18n-aware static React sites.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./seo": {
+      "types": "./dist/seo/metadata.d.ts",
+      "import": "./dist/seo/metadata.js"
+    },
+    "./validation": {
+      "types": "./dist/content/validator.d.ts",
+      "import": "./dist/content/validator.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts"
+    },
+    "./virtual": {
+      "types": "./dist/react/virtual.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "flatwave-validate": "dist/cli/validate.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-virtual-types.js",
+    "test": "vitest run"
+  },
+  "author": "KamanaSoft",
+  "license": "MIT",
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "react",
+    "markdown",
+    "i18n",
+    "ssg",
+    "static-site-generator",
+    "content"
+  ],
+  "homepage": "https://github.com/kamansoft/vite-plugin-flatwave-react/tree/main/packages/vite-plugin-flatwave-react",
+  "bugs": {
+    "url": "https://github.com/kamansoft/vite-plugin-flatwave-react/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamansoft/vite-plugin-flatwave-react.git",
+    "directory": "packages/vite-plugin-flatwave-react"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.7"
+  }
+}