API reference

Use this page to find the TypeScript names. For accepted config values, defaults, results, and use cases, start with the configuration guide. The dirwell package root exports the values and types below from src/index.ts. The dirwell/theme subpath exposes the component contracts from src/theme-components.ts, including the generic ThemeComponent<Props> type. The dirwell/vite subpath exports the Vite adapter and its DirwellViteOptions type. Dirwell(options) returns one Vite plugin; Dirwell([options, ...]) returns a plugin array. See Vite adapter. The command-line interface is described separately under CLI. Use the configuration guide and theme guide for behavior and design examples. The code blocks on this page are imported from TypeScript files checked by the repository tests.

Start without configuration

Run dirwell . to watch the current directory, or dirwell build . to write static output to dist/. The TypeScript API needs only source and output paths:

import { generateExplorer } from "dirwell";

await generateExplorer({ sourceDir: "./public", outputDir: "./dist" });

generateExplorer() requires sourceDir and outputDir. It defaults to SSG, relative URLs, mirrored source files, the default theme, and no symlink traversal. It writes the complete output to a staging directory before replacing the previous output. In this API, urlStrategy is the field that corresponds to config urls.

Configure a build

defineConfig() preserves the input type and accepts an object or a function receiving { command: "build" | "serve" | "daemon" }. The function may be asynchronous. A dirwell.config.ts file is discovered from --cwd.

Field	Accepted input; default and effect
root	Directory path; . for resolveGenerateOptions(). The CLI positional directory takes precedence and itself defaults to ..
outDir	dist/ for build; .dirwell-preview/ for serve and daemon.
mode	"ssg"; "mpa" shares runtime assets under __dirwell/.
mirror	true; copy source files to the output.
include	All source entries; root-relative glob or array of globs. Matching directories include descendants.
exclude	No exclusions; root-relative glob or array of globs. Exclusions win over inclusions.
base	/; root-relative path or HTTP(S) URL without query or fragment.
urls	"relative"; also accepts "base" and "html-base".
outputName	Safe filename or sync/async resolver; defaultOutputName uses _dirwell.html when an index exists and skips when both names exist.
sort	field, nameMode, direction, and directoriesFirst; name, natural comparison, ascending, directories first.
symlinks	follow, boundary, and onCycle; { follow: false, boundary: "root", onCycle: "skip" }.
theme	defaultTheme.
server	Serve/daemon host 127.0.0.1, port 4173; HOST and PORT may override these.
extends	No inherited config; local path or array of local paths.

For an index rule, inspect the typed DirectoryData argument. Returning null skips generation for that directory:

import { defineConfig } from "dirwell";

export default defineConfig({
  outputName(directory) {
    return directory.entries.some((entry) => entry.name === "index.html") ? null : "index.html";
  },
});

Use a fixed name when every directory should get the same filename:

import { defineConfig } from "dirwell";

export default defineConfig({ outputName: "listing.html" });

To deploy under a path and follow only symlinks within the source root:

import { defineConfig } from "dirwell";

export default defineConfig({
  mode: "mpa",
  base: "/downloads/",
  urls: "base",
  symlinks: { follow: true, boundary: "root", onCycle: "skip" },
});

"relative" uses depth-aware links, "base" prefixes the deployment base, and "html-base" emits an HTML <base> element. Broken symlinks expose their declared target through a raw-text view; out-of-root targets have no link. See symlink behavior and deployment.

Compose a theme

createDefaultTheme() accepts colorScheme, fuzzySearch, globalSearch, keyboardNavigation, and sorting switches, all enabled by default. It also accepts virtualizeAfter (default 500), project metadata, custom icons, and one or more ordered components overrides. The theme guide explains each option and its trade-off. This example wraps the default footer and escapes added text before writing HTML:

import { createDefaultTheme, defaultThemeComponents, defineConfig, escapeHtml } from "dirwell";

const label = "Downloads & releases";

export default defineConfig({
  theme: createDefaultTheme({
    components: {
      Footer: (props) => `<p>${escapeHtml(label)}</p>${defaultThemeComponents.Footer(props)}`,
    },
  }),
});

createPlainTheme() renders complete browser-native HTML without icons, JavaScript, or a search index. Complete replacement themes implement ExplorerTheme.render(context) and may emit named assets with their HTML.

Exported values

Export	Purpose
defineConfig	Preserve the type of a configuration object or function.
loadDirwellConfig	Load and validate config for a working directory and command; return config and config-file path.
resolveGenerateOptions	Resolve config and CLI overrides into absolute generator paths and options.
generateExplorer	Generate a static explorer from GenerateOptions.
createExplorerDevServer	Build, watch, serve, and expose a close() method.
readGeneratedPage	Read a generated HTML file as text.
defaultOutputName	Use index.html, then _dirwell.html if an index exists; skip when both names exist.
compareEntries	Compare two entries with optional sort settings.
createDefaultTheme	Create the interactive default theme.
defaultTheme	Ready-made instance of the default theme.
defaultThemeComponents	The eight replaceable default HTML component functions.
createPlainTheme	Create a browser-native, no-script theme.
resolveThemeComponents	Apply ordered component override layers to a base set.
escapeHtml	Escape untrusted text before inserting it into theme HTML.

src/index.ts is the source of truth for this list. src/config.ts, src/generator.ts, src/dev-server.ts, src/theme-default.ts, src/theme-components.ts, and src/theme-plain.ts define the behavior.

Exported types

Type	Contract
DirwellConfig	Config object fields listed above.
DirwellConfigContext	Command passed to a config function.
DirwellConfigInput	Config object or synchronous/asynchronous config function.
GenerateOptions	Generator source, output, URL, symlink, sort, and theme options.
DirectoryData	Root, current directory, parent, depth, and complete entries passed to output naming and themes.
FileSystemEntry	Entry name, paths, kind, metadata, and symlink state. absolutePath is for Node-side renderers; do not put it in public HTML.
FileMetadata	Device, ownership, inode, size, mode, link count, and times.
FileTimes	Access, change, creation, and modification ISO timestamps.
EntryKind	Directory, file, symlink, or other.
SymlinkMetadata	Declared target, resolved and root-relative paths, target kind, and safety flags.
OutputNameResolver	Sync or async function from DirectoryData to a filename or null.
SortField	Name, modified time, or size.
NameSortMode	Unicode, locale-aware, or natural name comparison.
SortDirection	Ascending or descending.
SortOptions	Field, name mode, direction, and directory grouping.
ExplorerTheme	Theme name, optional search-index policy, and renderer.
ThemeContext	Prepared directory, output mode, URL helpers, sort state, and link decisions.
RenderedPage	HTML plus optional named text or byte assets.
PlainThemeOptions	Optional plain-theme project metadata.
DirwellThemeComponents	The eight typed HTML component functions.
DirwellThemeComponentOverrides	Partial component layer.
DefaultThemeIconSet	Light and optional dark SVG icon sets with attribution.
DefaultThemeIconVariant	File, folder, and extension-specific SVG markup for one color scheme.
ThemeComponent<Props>	Function that renders typed props to an HTML string; available from dirwell/theme.
DefaultThemeRuntimeConfig	Serialized default-theme browser controls and asset links.
BreadcrumbItem	Label, link, and current-page state.
EntryNavigation	Link and whether navigation leaves the explorer.
EntryListItem	Entry, position, and navigation data.
PageShellProps	Full-document component inputs.
BreadcrumbsProps	Breadcrumb component inputs.
ToolbarProps	Search, sorting, keyboard, and appearance-control inputs.
EntryListProps	List markup, directory, parent link, and sorting state.
EntryRowProps	One entry’s data, navigation, and icon.
EmptyStateProps	Empty-state message.
FooterProps	Project metadata, shortcuts, and notice link.
IconName	Built-in control icon names.
IconProps	Icon name, optional label, size, and file-type image source.

The types are re-exported from src/model.ts, src/config.ts, src/theme-components.ts, and src/theme-plain.ts. Component functions return HTML strings; call escapeHtml() for untrusted entry or project text.

CLI options

Option	Commands	Default or effect
[directory]	build, serve, dev, daemon start	.; positional source directory.
--cwd	All commands	.; config discovery and daemon state directory.
--base	build, serve, dev, daemon start	Config base, otherwise /.
--mode	build, serve, dev, daemon start	ssg or mpa; config or SSG default.
--urls	build, serve, dev, daemon start	relative, base, or html-base; config or relative default.
-o, --outDir	build, serve, dev, daemon start	Output path; build defaults to dist/, server to .dirwell-preview/.
--host	serve, dev, daemon start	HOST, config, or 127.0.0.1.
-p, --port	serve, dev, daemon start	PORT, config, or 4173.

daemon status and daemon stop accept --cwd. daemon defaults to start; dev aliases serve, and a bare directory also invokes serve. Run dirwell <command> --help for generated help and current flag spelling.