@site-index/core

Deterministic site-index pipeline for config resolution, discovery, loading, validation, deduplication, and artifact generation.

Repository README

Install

npm install @site-index/core

Requirements:

• Node.js >=22

When to use

Use @site-index/core when you need programmatic control and can provide module loading yourself.

When not to use

• Use site-index for CLI-driven workflows.
• Use @site-index/vite-plugin for Vite projects.

Public exports

export { Artifact } from "./domains/artifacts/artifact.js";
export type { LoadModule, Options } from "./domains/options/types.js";
export type * from "./domains/site-indexes/types.js";
export type { Warning, Result } from "./types.js";
export { main } from "./main.js";

Main API

main(options: Options): Promise<Result<Artifact[]>>

Options:

type Options = {
  siteUrl: string;
  rootPath: string;
  extensions?: string[] | undefined;
  loadModule: LoadModule;
};

LoadModule:

type LoadModule = (module: Module) => Promise<ModuleExports>;

Module:

type Module = {
  filePath: string;
  importId: string;
};

ModuleExports:

type ModuleExports = {
  siteIndexes: SiteIndex[];
};

Site index type

type SiteIndex = {
  url: `/${string}`;
  lastModified?: string | undefined;
  sitemap?: string | undefined;
  index?: boolean | undefined;
};

Validation rules:

• url must start with /
• url cannot contain query strings or fragments
• lastModified is optional
• lastModified must be an ISO date or an ISO datetime with offset
• sitemap is optional
• sitemap defaults to pages
• sitemap must be lowercase and can include hyphens
• index is optional
• index defaults to true
• index: false excludes the URL from sitemap artifacts and adds Disallow: <path> to robots.txt

Artifacts

Generated:

• sitemap.xml
• sitemap-<name>.xml
• robots.txt

Artifact content types:

• .xml -> application/xml; charset=utf-8
• .txt -> text/plain; charset=utf-8

Pipeline behavior

main(...):

• resolves options
• discovers *.site-index.* modules
• loads modules via caller-provided loadModule
• validates module exports
• resolves and deduplicates site index entries
• sorts output deterministically
• generates immutable artifacts
• returns warnings for recoverable issues

Warning categories include:

• no modules found
• failed module load
• invalid module exports
• duplicate URL entries

Example

Example with a runtime that can import the discovered module files:

import { main } from "@site-index/core";
import type { Module, ModuleExports } from "@site-index/core";

const result = await main({
  siteUrl: "https://example.com",
  rootPath: process.cwd(),
  extensions: [".mjs"],
  loadModule: async (module: Module): Promise<ModuleExports> => {
    const loaded = await import(module.filePath);

    return loaded.default as ModuleExports;
  },
});

Related packages

• site-index
• @site-index/vite-plugin
• @site-index/vite-runtime
• @site-index/observability