Utilities API
Init, environment, globs, entrypoints, bundler, and dev helpers.
#Init
#async function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
interface InitProjectOptions {
cwd: string;
directory?: string;
template?: string;
packageManager?: PackageManager;
git?: boolean;
force?: boolean;
offline?: boolean;
env?: NodeJS.ProcessEnv;
downloader?: TemplateDownloader;
gitInit?: (root: string) => Promise<boolean>;
}
interface InitProjectResult {
root: string;
template: string;
label: string;
packageManager: PackageManager;
gitInitialized: boolean;
files: readonly string[];
warnings: readonly string[];
}
Constants and helpers:
const BUILTIN_TEMPLATES = ['vanilla-ts', 'vanilla-js', 'react'];
const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
const DEFAULT_TEMPLATE = 'vanilla-ts';
const TEMPLATE_LABELS: Record<BuiltinTemplate, string>;
function isBuiltinTemplate(value: unknown): value is BuiltinTemplate;
function resolveBuiltinTemplate(value: string): BuiltinTemplate | null;
function isPackageManager(value: unknown): value is PackageManager;
function detectPackageManager(options): Promise<PackageManager>;
Environment
#function loadBuildEnv(options: LoadBuildEnvOptions): BuildEnv;
interface LoadBuildEnvOptions {
root: string;
mode: BuildMode;
browser: BrowserTarget;
manifestVersion?: ManifestVersion;
}
interface BuildEnv {
values: Readonly<Record<string, string>>;
mode: BuildMode;
browser: BrowserTarget;
manifestVersion: ManifestVersion;
dev: boolean;
prod: boolean;
}
function toImportMetaEnvDefines(env: BuildEnv): Record<string, string>;
Produces defines for built-ins and exposed ADDONOVA_*/VITE_* values.
Globs
#function matchesGlob(relativePath: string, pattern: string): boolean;
function matchesAny(relativePath: string, patterns: readonly string[]): boolean;
function filterPaths(
paths: readonly string[],
include: readonly string[],
exclude: readonly string[],
): readonly string[];
function matchesDirectory(relativePath: string, patterns: readonly string[]): boolean;
function expandBraces(pattern: string): readonly string[];
Supports *, **, ?, character classes, and {a,b} alternatives. Paths use
forward slashes.
Entrypoints
#const ENTRYPOINT_TYPES: readonly EntrypointType[];
function discoverEntrypoints(options: DiscoverEntrypointsOptions): readonly DiscoveredEntrypoint[];
function detectEntrypointKind(input: string): EntrypointKind;
function inferEntrypointType(input: string): EntrypointType;
function isEntrypointForBrowser(entrypoint, browser): boolean;
function isEntrypointType(value: unknown): value is EntrypointType;
Types:
| Type | Description |
|---|---|
DiscoveredEntrypoint |
Discovered entrypoint metadata. |
DiscoverEntrypointsOptions |
Scan root, src dir, and entrypoint dir. |
EntrypointManifestOptions |
Manifest options from a define helper. |
EntrypointSelection |
Include/exclude filters. |
EntrypointType |
Manifest role union. |
Bundler
#const guchhoAdapter: BundlerAdapter;
interface BundlerAdapter {
build(input: BundlerBuildInput): Promise<BundlerBuildResult>;
dispose?(): Promise<void>;
}
Bundler types: BundlerAdapter, BundlerBuildInput, BundlerBuildResult,
BundlerContext, BundlerEntrypoint, BundlerFormat, BundlerInput,
BundlerOutput, BundlerTransform.
guchhoAdapter is the default adapter used when none is supplied. It wraps the
Guchho bundler and normalizes results.
Development
#class DevSession;
function createDevSession(options: DevSessionOptions): Promise<DevSession>;
function classifyChange(file: string, config: ResolvedConfig): ChangeKind;
type ChangeKind =
| 'config'
| 'manifest'
| 'entrypoint'
| 'source'
| 'asset'
| 'unknown';
Dev types: BrowserLauncherFactory, DevSessionOptions, DevWatcher,
DevWatcherFactory, DevWatcherOptions.
Plugin types
#interface AddonovaPlugin {
name: string;
buildStart?(): Promise<void> | void;
transform?(code: string, id: string): Promise<string | null> | string | null;
buildEnd?(): Promise<void> | void;
}
Plugin helpers: createPluginManager(), mergePluginDiagnostics(),
validatePlugins(), and the PluginManager type.