@hagicode/hagilight 0.4.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @hagicode/hagilight
 
-Astro integrations and components for HagiCode sites without Starlight. Provides sitemap and `robots.txt` generation, optional localized RSS feeds and favicon, and a reusable SEO head component.
+Astro integrations and components for HagiCode sites without Starlight. Provides sitemap and `robots.txt` generation, localized RSS feeds (enabled by default) and favicon, and a reusable SEO head component.
 
 ## Install
 
@@ -23,8 +23,8 @@ export default defineConfig({
 });
 ```
 
-`hagilight()` generates a sitemap and `robots.txt` when the site does not already provide them. Set an absolute HTTP(S) `site` URL. `hagilightFavicon()` adds the bundled icon unless the site already declares one.
+`hagilight()` generates a sitemap and `robots.txt` when the site does not already provide them, and localized RSS feeds (`/rss.xml`, `/rss.<language>.xml`) by default. Set an absolute HTTP(S) `site` URL. `hagilightFavicon()` adds the bundled icon unless the site already declares one.
 
-For localized RSS, use `hagilightRss({ locales, getFeed: './src/rss-feed.ts' })` from the same `/integration` entry point; `getFeed` points to a project-root-relative module exporting a feed callback. Import `@hagicode/hagilight/SEOHead` for SEO metadata in an Astro page or layout.
+RSS is on by default: `hagilight()` derives feed locales from the Astro `i18n` config and serves a built-in empty feed. Customize it with the `rss` option, for example `hagilight({ rss: { getFeed: './src/rss-feed.ts' } })`; `getFeed` points to a project-root-relative module exporting a feed callback. Pass `rss: false` to disable RSS. Import `@hagicode/hagilight/SEOHead` for SEO metadata in an Astro page or layout.
 
-See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for RSS configuration, feed callback types, and integration behavior.
+See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for RSS configuration, feed callback types, and integration behavior.

package/dist/integration.d.ts

@@ -1,33 +1,34 @@
 import type { AstroIntegration } from 'astro';
 import { type FaviconOptions } from '@hagicode/hagilight-core/favicon';
 import { type RssLocalesInput } from '@hagicode/hagilight-core/rss';
-import { RSS_OWNER, type RssOwnerClaim } from '@hagicode/hagilight-core/rss-ownership';
 export type { RssFeedCallback, RssFeedContent, RssFeedRequest, RssFooterContext, } from './rss-config.js';
 export interface HagilightOptions {
     /** Generate `sitemap-index.xml` and `robots.txt`. Defaults to `true`. */
     enabled?: boolean;
+    /**
+     * Generate localized `/rss.xml` and `/rss.<language>.xml` feeds. Defaults to
+     * `true`, so integrating `hagilight()` is enough to publish an RSS feed.
+     * Pass `false` to disable, or an options object to customize the feed:
+     * - `locales`: Starlight-shaped locale map. Derived from the Astro `i18n`
+     *   config when omitted.
+     * - `getFeed`: project-root-relative module whose default export is an
+     *   `RssFeedCallback`. A built-in empty feed is used when omitted.
+     */
+    rss?: boolean | HagilightRssOptions;
 }
 export interface HagilightRssOptions {
-    /** Starlight-shaped locale map, for example `{ root: { lang: 'en-US' }, 'zh-CN': { lang: 'zh-CN' } }`. */
-    locales: RssLocalesInput;
-    /** Project-root-relative module whose default export is an `RssFeedCallback`. */
-    getFeed: string;
+    /** Starlight-shaped locale map, for example `{ root: { lang: 'en-US' }, 'zh-CN': { lang: 'zh-CN' } }`. Derived from Astro `i18n` when omitted. */
+    locales?: RssLocalesInput;
+    /** Project-root-relative module whose default export is an `RssFeedCallback`. A built-in empty feed is used when omitted. */
+    getFeed?: string;
 }
 export type HagilightFaviconOptions = FaviconOptions;
-export type HagilightRssIntegration = AstroIntegration & {
-    readonly [RSS_OWNER]: RssOwnerClaim;
-};
 /**
- * Generate a sitemap and `robots.txt` for a plain Astro site. An existing
- * `@astrojs/sitemap` or Starlight integration owns sitemap generation, and a
- * consumer-owned robots page or public file takes precedence.
+ * Generate a sitemap and `robots.txt` for a plain Astro site, and (by default)
+ * localized RSS feeds. An existing `@astrojs/sitemap` or Starlight integration
+ * owns sitemap generation, a consumer-owned robots page or public file takes
+ * precedence, and an enabled Starlight Hagilight integration owns RSS feeds.
  */
-export declare function hagilight({ enabled }?: HagilightOptions): AstroIntegration;
+export declare function hagilight({ enabled, rss }?: HagilightOptions): AstroIntegration;
 /** Inject the bundled HagiCode favicon unless the site head already declares an icon. */
 export declare function hagilightFavicon(options?: HagilightFaviconOptions): AstroIntegration;
-/**
- * Generate localized `/rss.xml`, `/rss.en.xml`, and `/rss.<language>.xml`
- * routes and expose their URLs to the plain-Astro Footer. An enabled Starlight
- * Hagilight RSS integration in the same project owns the routes instead.
- */
-export declare function hagilightRss(input: HagilightRssOptions): HagilightRssIntegration;

package/dist/integration.js

@@ -4,7 +4,7 @@ import { extname, isAbsolute, resolve, win32 } from 'node:path';
 import sitemap from '@astrojs/sitemap';
 import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
 import { resolveRssLocales } from '@hagicode/hagilight-core/rss';
-import { RSS_OWNER, resolvePlainAstroRssOwner, } from '@hagicode/hagilight-core/rss-ownership';
+import { resolvePlainAstroRssOwner } from '@hagicode/hagilight-core/rss-ownership';
 const VIRTUAL_RSS_CONFIG = 'virtual:hagilight/rss-config';
 const VIRTUAL_RSS_CONFIG_RESOLVED = `\0${VIRTUAL_RSS_CONFIG}`;
 const PAGE_SOURCE_EXTENSIONS = new Set(['.astro', '.html', '.js', '.jsx', '.md', '.mdx', '.ts', '.tsx']);
@@ -31,18 +31,41 @@ function resolveDiscoverySite(site) {
     return parsed;
 }
 /**
- * Generate a sitemap and `robots.txt` for a plain Astro site. An existing
- * `@astrojs/sitemap` or Starlight integration owns sitemap generation, and a
- * consumer-owned robots page or public file takes precedence.
+ * Built-in RSS feed used when a consumer does not supply a `getFeed` module.
+ * It is serialized into the generated virtual module, so it must stay a pure
+ * function with no external references.
  */
-export function hagilight({ enabled = true } = {}) {
+const BUILTIN_RSS_FEED = async () => ({
+    title: 'Site Updates',
+    description: 'RSS feed for this site.',
+    items: [],
+});
+const BUILTIN_RSS_FEED_SOURCE = BUILTIN_RSS_FEED.toString();
+/**
+ * Generate a sitemap and `robots.txt` for a plain Astro site, and (by default)
+ * localized RSS feeds. An existing `@astrojs/sitemap` or Starlight integration
+ * owns sitemap generation, a consumer-owned robots page or public file takes
+ * precedence, and an enabled Starlight Hagilight integration owns RSS feeds.
+ */
+export function hagilight({ enabled = true, rss } = {}) {
     if (typeof enabled !== 'boolean') {
         throw new TypeError('Hagilight sitemap and robots enabled option must be a boolean.');
     }
+    if (rss !== undefined && typeof rss !== 'boolean' && !isRecord(rss)) {
+        throw new TypeError('Hagilight RSS option must be a boolean or an options object.');
+    }
+    if (isRecord(rss)) {
+        if (rss.locales !== undefined && !isRecord(rss.locales)) {
+            throw new TypeError('Hagilight RSS locales must be an object.');
+        }
+        if (rss.getFeed !== undefined && (typeof rss.getFeed !== 'string' || !rss.getFeed.trim())) {
+            throw new TypeError('Hagilight RSS getFeed must be a non-empty module path.');
+        }
+    }
     return {
         name: '@hagicode/hagilight:discovery',
         hooks: {
-            'astro:config:setup'({ config, injectRoute, updateConfig }) {
+            'astro:config:setup'({ config, injectRoute, addMiddleware, updateConfig }) {
                 if (!enabled)
                     return;
                 resolveDiscoverySite(config.site);
@@ -64,37 +87,65 @@ export function hagilight({ enabled = true } = {}) {
                         prerender: true,
                     });
                 }
+                if (rss === false)
+                    return;
+                if (resolvePlainAstroRssOwner(config.integrations) === 'starlight')
+                    return;
+                const rssOptions = rss === true || rss === undefined ? {} : rss;
+                const locales = resolveRssLocales(deriveRssLocales(rssOptions.locales, config), { requireNonEmpty: false });
+                const modulePath = rssOptions.getFeed
+                    ? resolveFeedModule(config.root, rssOptions.getFeed)
+                    : null;
+                const site = resolveSite(config.site);
+                assertNoRouteCollisions(config, locales);
+                const baseSegments = `${config.base || '/'}`.split('/').filter(Boolean);
+                const baseUrl = baseSegments.length > 0 ? `/${baseSegments.join('/')}/` : '/';
+                const baseLocation = new URL(baseUrl, site);
+                const defaultFeedUrl = new URL('rss.xml', baseLocation).href;
+                const localeFeedUrls = Object.fromEntries(locales
+                    .filter(({ filename }) => filename !== 'en')
+                    .map(({ lang, filename }) => [lang, new URL(`rss.${filename}.xml`, baseLocation).href]));
+                injectRoute({ pattern: '/rss.xml', entrypoint: routeEntrypoint('rss.xml.ts'), prerender: true });
+                injectRoute({ pattern: '/rss.[language].xml', entrypoint: routeEntrypoint('rss.[language].xml.ts'), prerender: true });
+                addMiddleware({ entrypoint: fileURLToPath(new URL('./rss-middleware.js', import.meta.url)), order: 'pre' });
+                updateConfig({
+                    vite: {
+                        plugins: [createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUrl, localeFeedUrls })],
+                    },
+                });
             },
         },
     };
 }
-/** Inject the bundled HagiCode favicon unless the site head already declares an icon. */
-export function hagilightFavicon(options = {}) {
-    if (!isRecord(options)) {
-        throw new TypeError('Hagilight favicon options must be an object.');
+function deriveRssLocales(locales, config) {
+    if (locales !== undefined)
+        return locales;
+    const i18n = config.i18n;
+    if (!i18n?.locales?.length)
+        return undefined;
+    const defaultLocale = i18n.defaultLocale ?? String(i18n.locales[0]);
+    const map = {};
+    for (const entry of i18n.locales) {
+        const lang = typeof entry === 'string' ? entry : entry.codes?.[0]
+            ?? entry.path;
+        if (typeof lang !== 'string' || !lang.trim())
+            continue;
+        if (lang === defaultLocale)
+            map.root = { lang };
+        else
+            map[lang] = { lang };
     }
-    return {
-        name: '@hagicode/hagilight:favicon',
-        hooks: {
-            'astro:config:setup'({ config, updateConfig }) {
-                const head = config.head;
-                const entry = resolveFaviconHeadEntry(head, options);
-                if (!entry)
-                    return;
-                updateConfig({ head: [...(head ?? []), entry] });
-            },
-        },
-    };
+    return map;
 }
-function resolveRssOptions(options) {
-    if (!isRecord(options)) {
-        throw new TypeError('Hagilight RSS integration options must be an object.');
+function resolveFeedModule(root, reference) {
+    if (reference.startsWith('file:') || isAbsolute(reference) || win32.isAbsolute(reference)) {
+        throw new TypeError('Hagilight RSS getFeed must be a path relative to the Astro project root.');
     }
-    const locales = resolveRssLocales(options.locales, { requireNonEmpty: true });
-    if (typeof options.getFeed !== 'string' || !options.getFeed.trim()) {
-        throw new TypeError('Hagilight RSS getFeed must be a non-empty module path such as "./src/rss-feed.mjs".');
+    const modulePath = resolve(fileURLToPath(root), reference);
+    if (!existsSync(modulePath) || !statSync(modulePath).isFile()) {
+        throw new Error(`Hagilight RSS getFeed module "${reference}" was not found relative to the Astro project root.`);
     }
-    return { locales, getFeed: options.getFeed.trim() };
+    return modulePath;
 }
 function resolveSite(site) {
     let parsed;
@@ -109,16 +160,6 @@ function resolveSite(site) {
     }
     return parsed.href;
 }
-function resolveFeedModule(root, reference) {
-    if (reference.startsWith('file:') || isAbsolute(reference) || win32.isAbsolute(reference)) {
-        throw new TypeError('Hagilight RSS getFeed must be a path relative to the Astro project root.');
-    }
-    const modulePath = resolve(fileURLToPath(root), reference);
-    if (!existsSync(modulePath) || !statSync(modulePath).isFile()) {
-        throw new Error(`Hagilight RSS getFeed module "${reference}" was not found relative to the Astro project root.`);
-    }
-    return modulePath;
-}
 function assertNoRouteCollisions(config, locales) {
     const expectedFiles = new Set(['rss.xml', 'rss.en.xml', ...locales.map(({ filename }) => `rss.${filename}.xml`)]);
     const pageRoot = resolve(fileURLToPath(config.srcDir), 'pages');
@@ -159,10 +200,12 @@ function assertNoRouteCollisions(config, locales) {
             collisions.push(publicFile);
     }
     if (collisions.length > 0) {
-        throw new Error(`Hagilight RSS route conflicts with consumer-owned file(s): ${collisions.join(', ')}. Remove the conflicting route or do not enable hagilightRss().`);
+        throw new Error(`Hagilight RSS route conflicts with consumer-owned file(s): ${collisions.join(', ')}. Remove the conflicting route or disable RSS with rss: false.`);
     }
 }
 function createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUrl, localeFeedUrls }) {
+    const feedImport = modulePath ? `import * as siteFeedModule from ${JSON.stringify(modulePath)};` : '';
+    const getFeedExpr = modulePath ? 'siteFeedModule.default' : `(${BUILTIN_RSS_FEED_SOURCE})`;
     return {
         name: '@hagicode/hagilight:rss',
         resolveId(id) {
@@ -172,12 +215,12 @@ function createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUr
             if (id !== VIRTUAL_RSS_CONFIG_RESOLVED)
                 return null;
             return [
-                `import * as siteFeedModule from ${JSON.stringify(modulePath)};`,
+                feedImport,
                 'const config = {',
                 `  site: ${JSON.stringify(site)},`,
                 `  baseUrl: ${JSON.stringify(baseUrl)},`,
                 `  locales: ${JSON.stringify(locales)},`,
-                '  getFeed: siteFeedModule.default,',
+                `  getFeed: ${getFeedExpr},`,
                 `  footer: ${JSON.stringify({ defaultFeedUrl, localeFeedUrls, locales })},`,
                 '};',
                 'export default config;',
@@ -185,58 +228,20 @@ function createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUr
         },
     };
 }
-/**
- * Generate localized `/rss.xml`, `/rss.en.xml`, and `/rss.<language>.xml`
- * routes and expose their URLs to the plain-Astro Footer. An enabled Starlight
- * Hagilight RSS integration in the same project owns the routes instead.
- */
-export function hagilightRss(input) {
-    const options = resolveRssOptions(input);
+/** Inject the bundled HagiCode favicon unless the site head already declares an icon. */
+export function hagilightFavicon(options = {}) {
+    if (!isRecord(options)) {
+        throw new TypeError('Hagilight favicon options must be an object.');
+    }
     return {
-        name: '@hagicode/hagilight:rss',
-        [RSS_OWNER]: { package: 'astro', enabled: true },
+        name: '@hagicode/hagilight:favicon',
         hooks: {
-            'astro:config:setup'({ config, injectRoute, addMiddleware, updateConfig }) {
-                if (resolvePlainAstroRssOwner(config.integrations) === 'starlight')
+            'astro:config:setup'({ config, updateConfig }) {
+                const head = config.head;
+                const entry = resolveFaviconHeadEntry(head, options);
+                if (!entry)
                     return;
-                const site = resolveSite(config.site);
-                const modulePath = resolveFeedModule(config.root, options.getFeed);
-                assertNoRouteCollisions(config, options.locales);
-                const baseSegments = `${config.base || '/'}`
-                    .split('/')
-                    .filter(Boolean);
-                const baseUrl = baseSegments.length > 0 ? `/${baseSegments.join('/')}/` : '/';
-                const baseLocation = new URL(baseUrl, site);
-                const defaultFeedUrl = new URL('rss.xml', baseLocation).href;
-                const localeFeedUrls = Object.fromEntries(options.locales
-                    .filter(({ filename }) => filename !== 'en')
-                    .map(({ lang, filename }) => [lang, new URL(`rss.${filename}.xml`, baseLocation).href]));
-                injectRoute({
-                    pattern: '/rss.xml',
-                    entrypoint: routeEntrypoint('rss.xml.ts'),
-                    prerender: true,
-                });
-                injectRoute({
-                    pattern: '/rss.[language].xml',
-                    entrypoint: routeEntrypoint('rss.[language].xml.ts'),
-                    prerender: true,
-                });
-                addMiddleware({
-                    entrypoint: fileURLToPath(new URL('./rss-middleware.js', import.meta.url)),
-                    order: 'pre',
-                });
-                updateConfig({
-                    vite: {
-                        plugins: [createVirtualPlugin({
-                                modulePath,
-                                site,
-                                baseUrl,
-                                locales: options.locales,
-                                defaultFeedUrl,
-                                localeFeedUrls,
-                            })],
-                    },
-                });
+                updateConfig({ head: [...(head ?? []), entry] });
             },
         },
     };

package/dist/rss-config.d.ts

@@ -10,7 +10,7 @@ export interface RssFeedContent {
     description: string;
     items: readonly RssFeedItem[];
 }
-/** Default export of the module referenced by `hagilightRss({ getFeed })`. */
+/** Default export of the module referenced by `hagilight({ rss: { getFeed } })`. */
 export type RssFeedCallback = (request: RssFeedRequest) => RssFeedContent | Promise<RssFeedContent>;
 /** Request-local feed URLs that the plain-Astro Footer reads from `Astro.locals.hagilightRss`. */
 export interface RssFooterContext {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Astro integrations and components for HagiCode sites",
   "repository": {
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.7.4",
-    "@hagicode/hagilight-core": "0.4.0"
+    "@hagicode/hagilight-core": "0.4.1"
   },
   "keywords": [
     "astro-component",