@stacksjs/stx 0.2.154 → 0.2.156

package/dist/ssg.d.ts

@@ -1,160 +1,303 @@
-/// <reference path="./stx.d.ts" />
 /**
- * Generate static site
- */
-export declare function generateStaticSite(options?: SSGConfig): Promise<SSGResult>;
-/**
- * Create ISR handler for runtime revalidation
- */
-export declare function createISRHandler(options?: SSGConfig): {
-  get: (route: string) => Promise<{ html: string; headers: Record<string, string> } | null>
-  revalidate: (route: string) => Promise<void>
-  invalidate: (route: string | RegExp) => Promise<void>
-};
-/**
- * Define static paths for dynamic routes (used in templates)
+ * Static Site Generation (SSG) with Incremental Static Regeneration (ISR)
+ *
+ * Pre-renders pages at build time for optimal performance and SEO.
+ * Supports on-demand revalidation for dynamic content.
+ *
+ * ## Features
+ *
+ * - Build-time page generation from file-based routes
+ * - Dynamic route handling with getStaticPaths()
+ * - Incremental Static Regeneration (ISR)
+ * - Automatic sitemap generation
+ * - RSS feed generation
+ * - Content source integrations (Markdown, CMS, API)
+ * - Parallel page generation
+ * - Build caching for faster rebuilds
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { generateStaticSite, defineStaticPaths } from 'stx/ssg'
+ *
+ * // Generate entire site
+ * await generateStaticSite({
+ *   pagesDir: 'pages',
+ *   outputDir: 'dist',
+ *   revalidate: 3600, // ISR: revalidate every hour
+ * })
+ * ```
+ *
+ * For dynamic routes, export getStaticPaths in your template:
+ * ```html
+ * <script server>
+ * export async function getStaticPaths() {
+ *   const posts = await fetchPosts()
+ *   return posts.map(post => ({
+ *     params: { slug: post.slug },
+ *     props: { post }
+ *   }))
+ * }
+ * </script>
+ * ```
+ *
+ * @module ssg
  */
-export declare function defineStaticPaths(pathsFn: () => Promise<StaticPath[]> | StaticPath[]): () => Promise<StaticPathsResult>;
-/**
- * Create a markdown content loader
- */
-export declare function createMarkdownLoader(): ContentLoader;
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface SSGConfig {
-  pagesDir?: string
-  outputDir?: string
-  baseUrl?: string
-  domain?: string
-  revalidate?: number | false
-  sitemap?: boolean
-  rss?: boolean | RSSConfig
-  concurrency?: number
-  cache?: boolean
-  cacheDir?: string
-  contentLoaders?: ContentLoader[]
-  hooks?: SSGHooks
-  minify?: boolean
-  generate404?: boolean
-  publicDir?: string
-  trailingSlash?: boolean
-  cleanOutput?: boolean
-  chunkIslands?: boolean
-  prefetchIslands?: boolean
-  integrityIslands?: boolean
+export interface SSGConfig {
+    /** Directory containing pages (default: 'pages') */
+    pagesDir?: string;
+    /** Output directory for generated files (default: 'dist') */
+    outputDir?: string;
+    /** Base URL for the site (default: '/') */
+    baseUrl?: string;
+    /** Site domain for absolute URLs */
+    domain?: string;
+    /** Enable ISR with revalidation time in seconds */
+    revalidate?: number | false;
+    /** Generate sitemap.xml */
+    sitemap?: boolean;
+    /**
+     * Routes to keep out of sitemap.xml (#1866).
+     *
+     * Strings match a URL exactly or as a `/prefix/` when they end in `/`;
+     * RegExps are tested against the URL. A page can also exclude itself with
+     * `definePageMeta({ sitemap: false })` or by declaring a `noindex` robots
+     * meta, which is checked without needing this list.
+     *
+     * @example
+     * ```ts
+     * sitemapExclude: ['/login', '/account/', /^\/admin/]
+     * ```
+     */
+    sitemapExclude?: (string | RegExp)[];
+    /**
+     * Generate robots.txt (default: true).
+     *
+     * Written from the same resolved site URL as the sitemap, with a `Sitemap:`
+     * line pointing at it, and a `Disallow` for every `sitemapExclude` entry —
+     * so the two files cannot disagree about what is public.
+     */
+    robots?: boolean | RobotsConfig;
+    /** Generate RSS feed */
+    rss?: boolean | RSSConfig;
+    /** Parallel page generation limit (default: 10) */
+    concurrency?: number;
+    /** Enable build caching (default: true) */
+    cache?: boolean;
+    /** Cache directory (default: `ssg-cache` inside the state directory) */
+    cacheDir?: string;
+    /** Custom content loaders */
+    contentLoaders?: ContentLoader[];
+    /** Pre-render hooks */
+    hooks?: SSGHooks;
+    /** Minify HTML output (default: true in production) */
+    minify?: boolean;
+    /** Generate 404 page */
+    generate404?: boolean;
+    /** Additional files to copy to output */
+    publicDir?: string;
+    /** Trailing slash behavior */
+    trailingSlash?: boolean;
+    /** Clean output directory before build */
+    cleanOutput?: boolean;
+    /**
+     * Per-island chunking (#1746): lift each `client="<trigger>"` island's inline
+     * setup script into a content-hashed chunk under `_stx/islands/` that the
+     * runtime fetches only on the hydration trigger. Default `false` (opt-in) —
+     * when off, builds are byte-identical and islands stay inline.
+     */
+    chunkIslands?: boolean;
+    /**
+     * Emit `<link rel="prefetch" as="script">` hints for `visible`/`idle` island
+     * chunks so they warm in cache before the trigger fires (instant hydration,
+     * still no inline JS). `interaction`/`media:` islands are skipped. Requires
+     * `chunkIslands`. Default `false` — trades some idle bandwidth for latency.
+     */
+    prefetchIslands?: boolean;
+    /**
+     * Stamp Subresource Integrity (`sha384`) on island chunks so the runtime pins
+     * them against tampering and a strict CSP can require SRI. Requires
+     * `chunkIslands`. Default `false` — only enable when chunks are served
+     * byte-for-byte unchanged (no CDN/proxy transform).
+     */
+    integrityIslands?: boolean;
 }
-export declare interface RSSConfig {
-  title: string
-  description: string
-  link: string
-  language?: string
-  copyright?: string
-  getItems?: () => Promise<RSSItem[]>
+/** robots.txt options for the static build (#1866). */
+export interface RobotsConfig {
+    /** Extra paths to disallow, on top of `sitemapExclude`. */
+    disallow?: string[];
+    /** Paths to explicitly allow. Defaults to `['/']`. */
+    allow?: string[];
+    /** User agent the rules apply to. Defaults to `*`. */
+    userAgent?: string;
+    /** Emit the `Sitemap:` line (default: true when a sitemap is generated). */
+    sitemap?: boolean;
 }
-export declare interface RSSItem {
-  title: string
-  link: string
-  description?: string
-  pubDate?: Date
-  author?: string
-  categories?: string[]
-  guid?: string
+export interface RSSConfig {
+    title: string;
+    description: string;
+    link: string;
+    language?: string;
+    copyright?: string;
+    /** Function to get items for RSS feed */
+    getItems?: () => Promise<RSSItem[]>;
 }
-export declare interface StaticPath {
-  params: Record<string, string>
-  props?: Record<string, unknown>
-  revalidate?: number | false
+export interface RSSItem {
+    title: string;
+    link: string;
+    description?: string;
+    pubDate?: Date;
+    author?: string;
+    categories?: string[];
+    guid?: string;
 }
-export declare interface StaticPathsResult {
-  paths: StaticPath[]
-  fallback?: 'blocking' | 'static' | false
+export interface StaticPath {
+    /** Route parameters */
+    params: Record<string, string>;
+    /** Props to pass to the page */
+    props?: Record<string, unknown>;
+    /** Page-specific revalidation time (overrides global) */
+    revalidate?: number | false;
 }
-export declare interface ContentLoader {
-  name: string
-  extensions: string[]
-  load: (filePath: string) => Promise<ContentResult>
+export interface StaticPathsResult {
+    paths: StaticPath[];
+    /** Fallback behavior for paths not returned */
+    fallback?: 'blocking' | 'static' | false;
 }
-export declare interface ContentResult {
-  content: string
-  data: Record<string, unknown>
-  toc?: TocItem[]
+export interface ContentLoader {
+    /** Name of the loader */
+    name: string;
+    /** File extensions this loader handles */
+    extensions: string[];
+    /** Load content from file */
+    load: (filePath: string) => Promise<ContentResult>;
 }
-export declare interface TocItem {
-  id: string
-  text: string
-  level: number
-  children?: TocItem[]
+export interface ContentResult {
+    /** Rendered HTML content */
+    content: string;
+    /** Frontmatter/metadata */
+    data: Record<string, unknown>;
+    /** Table of contents (for markdown) */
+    toc?: TocItem[];
 }
-export declare interface SSGHooks {
-  onBuildStart?: () => void | Promise<void>
-  onBuildEnd?: (result: SSGResult) => void | Promise<void>
-  onPageStart?: (route: string) => void | Promise<void>
-  onPageEnd?: (route: string, html: string) => void | Promise<void>
-  onError?: (error: Error, route?: string) => void | Promise<void>
+export interface TocItem {
+    id: string;
+    text: string;
+    level: number;
+    children?: TocItem[];
 }
-export declare interface SSGResult {
-  totalPages: number
-  successCount: number
-  failedCount: number
-  cachedCount: number
-  buildTime: number
-  sitemapPath?: string
-  rssPath?: string
-  pages: PageResult[]
-  errors: PageError[]
-  islandChunks?: { count: number, totalBytes: number }
+export interface SSGHooks {
+    /** Called before build starts */
+    onBuildStart?: () => void | Promise<void>;
+    /** Called after build completes */
+    onBuildEnd?: (result: SSGResult) => void | Promise<void>;
+    /** Called before each page is rendered */
+    onPageStart?: (route: string) => void | Promise<void>;
+    /** Called after each page is rendered */
+    onPageEnd?: (route: string, html: string) => void | Promise<void>;
+    /** Called on build error */
+    onError?: (error: Error, route?: string) => void | Promise<void>;
 }
-export declare interface PageResult {
-  route: string
-  outputPath: string
-  size: number
-  cached: boolean
-  revalidateAt?: number
+export interface SSGResult {
+    /** Total pages generated */
+    totalPages: number;
+    /** Successfully generated pages */
+    successCount: number;
+    /** Failed pages */
+    failedCount: number;
+    /** Pages that were cached */
+    cachedCount: number;
+    /** Build time in milliseconds */
+    buildTime: number;
+    /** Generated sitemap path */
+    sitemapPath?: string;
+    /** Generated RSS path */
+    rssPath?: string;
+    /** Individual page results */
+    pages: PageResult[];
+    /** Errors encountered */
+    errors: PageError[];
+    /**
+     * Per-island chunking stats (#1746), present only when `chunkIslands` emitted
+     * any chunks: `count` unique (content-addressed) chunk files and `totalBytes`
+     * of island JS moved out of inline HTML into lazily-fetched chunks.
+     */
+    islandChunks?: {
+        count: number;
+        totalBytes: number;
+    };
 }
-export declare interface PageError {
-  route: string
-  error: Error
+export interface PageResult {
+    route: string;
+    outputPath: string;
+    size: number;
+    cached: boolean;
+    revalidateAt?: number;
 }
-export declare interface ISRCache {
-  get: (route: string) => Promise<CachedPage | null>
-  set: (route: string, page: CachedPage) => Promise<void>
-  invalidate: (route: string) => Promise<void>
-  invalidatePattern: (pattern: RegExp) => Promise<void>
-  needsRevalidation: (route: string) => Promise<boolean>
+export interface PageError {
+    route: string;
+    error: Error;
 }
-export declare interface CachedPage {
-  html: string
-  generatedAt: number
-  revalidateAfter: number
-  etag: string
-  headers?: Record<string, string>
+export interface ISRCache {
+    /** Get cached page */
+    get: (route: string) => Promise<CachedPage | null>;
+    /** Set cached page */
+    set: (route: string, page: CachedPage) => Promise<void>;
+    /** Invalidate cached page */
+    invalidate: (route: string) => Promise<void>;
+    /** Invalidate all pages matching pattern */
+    invalidatePattern: (pattern: RegExp) => Promise<void>;
+    /** Check if page needs revalidation */
+    needsRevalidation: (route: string) => Promise<boolean>;
 }
-declare class BuildCache {
-  constructor(cacheDir: string);
-  load(): Promise<void>;
-  save(): Promise<void>;
-  getHash(filePath: string, dependencies: string[]): string;
-  get(route: string, filePath: string): string | null;
-  set(route: string, filePath: string, dependencies: string[], html: string): void;
+export interface CachedPage {
+    html: string;
+    generatedAt: number;
+    revalidateAfter: number;
+    etag: string;
+    headers?: Record<string, string>;
 }
-// =============================================================================
-// ISR Cache Implementation
-// =============================================================================
-declare class FileISRCache implements ISRCache {
-  constructor(cacheDir: string);
-  get(route: string): Promise<CachedPage | null>;
-  set(route: string, page: CachedPage): Promise<void>;
-  invalidate(route: string): Promise<void>;
-  invalidatePattern(pattern: RegExp): Promise<void>;
-  needsRevalidation(route: string): Promise<boolean>;
-}
-// =============================================================================
-// Exports
-// =============================================================================
-export default {
-  generateStaticSite,
-  createISRHandler,
-  defineStaticPaths,
-  createMarkdownLoader,
+/**
+ * Generate sitemap.xml
+ */
+/**
+ * Whether a generated page should stay out of sitemap.xml (#1866).
+ *
+ * Three independent ways to say no, because they are declared in three
+ * different places: the build config (`sitemapExclude`), the page itself
+ * (`definePageMeta({ sitemap: false })`), and the page's own robots meta — a
+ * page already marked `noindex` asking to be listed in a sitemap is a
+ * contradiction, and apps were adding that meta by hand precisely because the
+ * sitemap ignored them.
+ */
+export declare function isExcludedFromSitemap(url: string, html: string, pageMeta: Record<string, any> | null | undefined, exclude: (string | RegExp)[]): boolean;
+/**
+ * Generate static site
+ */
+export declare function generateStaticSite(options?: SSGConfig): Promise<SSGResult>;
+/**
+ * Create ISR handler for runtime revalidation
+ */
+export declare function createISRHandler(options?: SSGConfig): {
+    get: (route: string) => Promise<{
+        html: string;
+        headers: Record<string, string>;
+    } | null>;
+    revalidate: (route: string) => Promise<void>;
+    invalidate: (route: string | RegExp) => Promise<void>;
+};
+/**
+ * Define static paths for dynamic routes (used in templates)
+ */
+export declare function defineStaticPaths(pathsFn: () => Promise<StaticPath[]> | StaticPath[]): () => Promise<StaticPathsResult>;
+/**
+ * Create a markdown content loader
+ */
+export declare function createMarkdownLoader(): ContentLoader;
+declare const _default: {
+    generateStaticSite: typeof generateStaticSite;
+    createISRHandler: typeof createISRHandler;
+    defineStaticPaths: typeof defineStaticPaths;
+    createMarkdownLoader: typeof createMarkdownLoader;
 };
+export default _default;