API reference

Static build

import { generateExplorer } from "@dirwell/core";
import { createPlainTheme } from "@dirwell/theme-plain";
await generateExplorer({ sourceDir: "files", outputDir: "generated", theme: createPlainTheme() });

GenerateOptions requires source, dedicated output and an explicit theme. Build awaits renderers and metadata, validates assets, then replaces the output tree. It defaults to SSG, relative links and mirrored source files. outputName can return a filename or null per directory. listing controls HTML pages and data independently. See configuration and deployment.

Directory routing

RoutingOptions contains directoryUrls: explicit (default), slash, or clean. The same Core policy is accepted by build and live server APIs. Themes receive resolved URLs and do not select the policy. See directory URLs.

resolveDirectoryUrls validates this policy and returns the resolved style. directoryRoute returns archive-relative outputPath and publicPath; it does not configure a host or authorize access. encodeLogicalPath encodes each URL path segment once. DirectoryUrls is the style union. Do not use these helpers to bypass the publisher’s collision checks; generateExplorer validates the complete output.

Core public contracts

All names below come from @dirwell/core. Source definitions live in the Core package.

Symbol	Role
ContentCounts	Direct or archive folder, file and link counts.
DirectoryAccessError	Unavailable or rejected logical filesystem path.
DirectoryData	Private root/current/parent facts and current-directory entries.
DirectoryService	Async path resolution, entry reads, directory reads and safe file handles.
SelectionBudget	Fresh scan entry/directory limits, abort signal and per-path authorization.
SelectionBudgetError	An incomplete bounded scan; callers must not expose partial results as complete.
DirectoryServiceOptions	Physical root, include/exclude rules and sort policy for live reads.
EntryKind	Directory, file, symlink or other entry.
ExplorerTheme	Renderer, optional public entry data, pagination and search capabilities.
FileMetadata	Private stat facts: size, mode, device, ownership, inode and times.
FileSystemEntry	Private Node-side name/path, kind, metadata and link facts.
FileTimes	ISO timestamps for access, change, creation and modification.
GenerateOptions	Required source/output/theme plus static selection, URLs, listing and metadata.
ImageSource	Local path, file URL or File used by a metadata provider.
JsonObject	String-keyed JSON-compatible object for public custom data.
JsonValue	Validated JSON primitive, array or object.
ListingBlock	Versioned public records with offset, total and coherent revision.
ListingContext	Current page, manifest URL and public revision passed to a theme.
ListingEntry	Public name, kind, navigation, size, modification time and safe link state.
ListingManifest	Coherent revision, URL base, sort policy and block descriptors.
ListingPage	Page number/count, offset/total and native previous/next links.
ListingPlan	Independent all/paged HTML and all/blocked data policy.
ListingPolicy	Fixed plan or synchronous per-directory planner.
ListingPolicyContext	Directory path/count/bytes, layout, operation and theme pagination capability.
MetadataContext	Public site and current-directory names, paths and counts.
MetadataImage	Image source with optional output-relative path and alt text.
MetadataImageValue	Fixed image, disabled image or async resolved-text callback.
MetadataOptions	Site URL/name, titles, descriptions and optional image selection.
MetadataProvider	Async directory metadata resolver and generated byte assets.
MetadataProviderFactory	Per-build provider created from source path and selected entry kinds.
MetadataValue	Fixed value or async public-count callback.
NameSortMode	Locale, natural or Unicode filename comparison.
OutputNameResolver	Async per-directory filename or null to skip a generated page.
PageMetadata	Resolved title, description and inert HTML head tags.
RenderedPage	Complete document plus optional string/byte assets.
ResolvedMetadataContext	Public counts and paths plus resolved title and description.
SortDirection	Ascending or descending.
SortField	Modified time, name or size.
SortOptions	Direction, field, directory grouping and filename comparison.
SymlinkMetadata	Private declared/resolved target and boundary, broken, cycle and follow state.
ThemeContext	Private Node-side directory facts and prepared safe navigation/rendering functions.
ThemeMetadataDefaults	Optional provider defaults; image presets require the share-image package.
compareEntries	Compare private entries with a resolved sort policy.
copyJsonObject	Validate and copy JSON-compatible custom public data.
createDirectoryService	Await live filesystem service creation; no output tree or watcher.
defaultOutputName	Preserve source index pages and choose an available explorer filename.
escapeHtml	Escape untrusted text before inserting it in HTML.
generateExplorer	Await static publication; requires an explicit theme.
generateExplorerSkippingPaths	Publish static output while skipping host-owned generated paths.
listingRevision	Hash public listing facts into a coherent revision.
projectListingEntry	Convert private filesystem facts into public serializable records.
readGeneratedPage	Read an available generated directory page.
validateListingPlan	Validate independent HTML/data policy and pagination support.

Publication controls

These controls are included in 0.0.1.

IgnoreFile is a path or { path, baseDir?, optional? }. resolveIgnoreFiles accepts (files, cwd) to validate and resolve ordered ignore file paths. GenerateOptions.ignoreFiles and live service options default to no ignore discovery. The CLI selects an optional cwd .gitignore unless overridden, including with [].

GenerateOptions.outputPolicy defaults to owned: missing, empty or marked outputs can be published. replace permits replacing an unowned nonempty directory. Neither permits a source-containing output or a file/symlink destination. dryRun selects and plans without writing output. generateExplorer returns a BuildReport containing selected paths, directory-page names, theme and replacement scope. Publication keeps a rollback backup until the staged output is installed.

defineConfig from @dirwell/cli preserves configuration types and rejects unknown nested options before starting either mode. CLI builds accept --force/-f and --dry-run; both modes accept repeatable --ignore-file and --no-ignore.

Browser listing loader behavior

@dirwell/core/client exports loadListing and parseListingEntries. The loader fetches coherent public records and retries once when a live revision expires. Private filesystem objects never belong in browser payloads. Data splitting is independent of HTML pagination and row rendering.

Optional packages

API	Package/guide
runCli, CliConfig	CLI and @dirwell/cli
createPlainTheme	@dirwell/theme-plain
createLedgerTheme, LedgerThemeOptions	@dirwell/theme-ledger
createCrosswaveTheme, defaultCrosswaveCategories, CrosswaveThemeOptions	@dirwell/theme-crosswave
createExplorerHandler	@dirwell/server; await creation before mounting
startExplorerServer, createNodeRequestListener	@dirwell/server/node; the standalone server owns shutdown
createMetadataProvider, createShareImage, describeContent	Metadata and @dirwell/share-image
Default build adapter factories	Build tools and @dirwell/integrations/*
buildFrameworkTheme, startAuthoringServer	Source customization and @dirwell/theme-authoring / dev

See SDK examples for executed static/live/authorization examples. Package exports include TypeScript declarations. Theme /source and /model subpaths supply framework component and row contracts; they are compiled with paired SSR/client output rather than serialized function overrides.

Theme rendering

ExplorerTheme.render(ThemeContext) owns a complete document and optional string/byte assets. Context contains private Node-side directory facts, safe link functions, sort settings, optional listing and metadata. Escape untrusted text. Use projected public entries for client data, never absolute paths or raw stat metadata. A theme may add JSON entry data, opt into native pagination and choose whether to generate an archive search index.

Public annotations and file URL mapping

entryData(entry, context) is an optional Core build/live-service callback. It receives public logical facts (id, name, kind, size, modifiedAt, link) and {operation, directoryPath}; it does not receive private source paths or raw stat records. Return a plain JSON object, synchronously or asynchronously. Values are copied and validated, then exposed as ListingEntry.data. This is a public field: publish only information intended for every reader allowed to list that directory.

The callback runs for each selected row, concurrently within a directory, on each build or live listing read. Await all results before rendering, revision calculation or publication. Cache expensive sidecar/remote work in the caller, and keep results deterministic for a coherent live revision. An annotation change affects the listing revision and SSE refresh. This hook changes display data; it does not rename paths, grant access, or expand search scope. Theme-derived presentation remains separate.

For static publication, fileHref(logicalPath) returns a synchronous HTTP(S), root-relative or relative URL, or null to omit the link. It runs once per canonical file path per build and is reused by listing and archive search. Encode each logical path segment before appending it to a CDN URL. Directory links, page/data/assets and unavailable symlink targets retain their existing rules. Combine with mirror: false when the files already exist on the host/CDN; otherwise mirroring still copies selected files. The host owns response headers and CDN access control.

await generateExplorer({
  sourceDir: "./files",
  outputDir: "./generated",
  theme: createPlainTheme(),
  mirror: false,
  fileHref: (logicalPath) =>
    "https://cdn.example.com/releases/" + logicalPath.split("/").map(encodeURIComponent).join("/"),
  entryData: (entry) => ({ description: annotations[entry.id]?.description ?? "" }),
});

Direct JavaScript validation

Core generation, DirectoryService and Server reject unknown option keys and incorrect value shapes. Diagnostics include the complete option path and a likely correction. Invalid direct options fail before publication writes, directory-service initialization or socket creation. A listing callback is evaluated after directory inspection; its returned plan is checked before output replacement. Custom theme fields remain allowed, while required render/name and known hooks must match their declared contract. Trusted async metadata and annotation callbacks are still awaited.

// Rejected: options.exlcude. Did you mean options.exclude?
await generateExplorer({
  sourceDir: "files",
  outputDir: "generated",
  theme,
  exlcude: ["drafts/**"],
});
// Rejected: mirror must be a boolean.
await generateExplorer({ sourceDir: "files", outputDir: "generated", theme, mirror: "false" });

Pass Node-specific host/port only to startExplorerServer; the Fetch handler and Core directory service have separate option contracts. Runtime validation checks configuration and callback results, not side effects performed by trusted callbacks. These checks are included in 0.0.1.

Local fonts and live queries

ShareImageFonts adds local body/headline TTF/OTF sources to createShareImage. See metadata. LiveSearchOptions enables bounded fresh archive queries on ExplorerHandlerOptions.search; see configuration.

DirectoryService.scan(SelectionBudget) streams selected canonical physical entries under entry/directory budgets, checking signal and allowPath before traversal. It throws SelectionBudgetError rather than returning an incomplete scan. It returns private filesystem facts, without annotation callbacks; project only explicit safe fields for public transport. Aliases are omitted; scans are not transactional. Host callbacks should honor the enclosing request signal.