api #

(callback: (navigation: (NavigationGoto & { type: "goto" | "enter" | "form" | "link" | "popstate"; willUnload: false; }) | (NavigationFormSubmit & { type: "goto" | ... 3 more ... | "popstate"; willUnload: false; }) | (NavigationPopState & { ...; }) | (NavigationLink & { ...; }) | (NavigationEnter & { ...; })) => voi...

import {afterNavigate} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

analyze_gen_result
#

(file: GenFile): Promise<AnalyzedGenResult> import {analyze_gen_result} from '@fuzdev/gro/gen.js';

`file`

type GenFile

returns

Promise<AnalyzedGenResult>

analyze_gen_results
#

(gen_results: GenResults): Promise<AnalyzedGenResult[]> import {analyze_gen_results} from '@fuzdev/gro/gen.js';

`gen_results`

type GenResults

returns

Promise<AnalyzedGenResult[]>

AnalyzedGenResult
#

sveltekit_shim_app_forms.ts view source

AnalyzedGenResult

type { file: GenFile; existing_content: string; is_new: false; has_changed: boolean; } | { file: GenFile; existing_content: null; is_new: true; has_changed: true; }

import type {AnalyzedGenResult} from '@fuzdev/gro/gen.js';

applyAction
#

<Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined>(result: ActionResult<Success, Failure>) => Promise<void>

import {applyAction} from '@fuzdev/gro/sveltekit_shim_app_forms.js';

asset
#

sveltekit_shim_app_paths.ts view source

(file: ".nojekyll" | "CNAME" | "favicon.png" | "logo.svg" | "robots.txt"): string import {asset} from '@fuzdev/gro/sveltekit_shim_app_paths.js';

`file`

type AssetPath

returns

string

base_path_to_path_id
#

(base_path: string, p?: Paths): PathId import {base_path_to_path_id} from '@fuzdev/gro/paths.js';

`base_path`

type string

`p`

type Paths

default infer_paths(base_path)

returns

PathId

beforeNavigate
#

(callback: (navigation: BeforeNavigate) => void) => void import {beforeNavigate} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

browser
#

false import {browser} from '@fuzdev/gro/sveltekit_shim_app_env.js';

BUILD_CACHE_METADATA_FILENAME
#

"build.json" import {BUILD_CACHE_METADATA_FILENAME} from '@fuzdev/gro/build_cache.js';

BUILD_CACHE_VERSION
#

"1" import {BUILD_CACHE_VERSION} from '@fuzdev/gro/build_cache.js';

BuildCacheMetadata
#

value + type

{ version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; }

import {BuildCacheMetadata} from '@fuzdev/gro/build_cache.js';

Metadata stored in .gro/ directory to track build cache validity. Schema validates structure at load time to catch corrupted cache files.

`version`

type string

`git_commit`

type string | null

`build_cache_config_hash`

type string

`timestamp`

type string

`outputs`

type BuildOutputEntry[]

building
#

false import {building} from '@fuzdev/gro/sveltekit_shim_app_env.js';

BuildOutputEntry
#

value + type

{ path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; } import {BuildOutputEntry} from '@fuzdev/gro/build_cache.js';

Metadata about a single build output file. Includes cryptographic hash for validation plus filesystem stats for debugging and optimization.

`path`

type string

`hash`

type string

`size`

type number

`mtime`

type number

`ctime`

type number

`mode`

type number

CHANGESET_CLI
#

"changeset" import {CHANGESET_CLI} from '@fuzdev/gro/changeset_helpers.js';

CHANGESET_DIR
#

".changeset" import {CHANGESET_DIR} from '@fuzdev/gro/changeset_helpers.js';

CHANGESET_PUBLIC_ACCESS
#

"public" import {CHANGESET_PUBLIC_ACCESS} from '@fuzdev/gro/changeset_helpers.js';

CHANGESET_RESTRICTED_ACCESS
#

"restricted" import {CHANGESET_RESTRICTED_ACCESS} from '@fuzdev/gro/changeset_helpers.js';

ChangesetAccess
#

value + type

"restricted" | "public"

type "restricted" | "public"

import {ChangesetAccess} from '@fuzdev/gro/changeset_helpers.js';

ChangesetBump
#

value + type

"patch" | "minor" | "major"

type "patch" | "minor" | "major"

import {ChangesetBump} from '@fuzdev/gro/changeset_helpers.js';

clean_fs
#

clean_fs.ts view source

({ build, build_dev, build_dist, sveltekit, nodemodules }: { build?: boolean | undefined; build_dev?: boolean | undefined; build_dist?: boolean | undefined; sveltekit?: boolean | undefined; nodemodules?: boolean | undefined; }, rm_options?: RmOptions): Promise<...>

import {clean_fs} from '@fuzdev/gro/clean_fs.js';

`__0`

type

{ build?: boolean | undefined; build_dev?: boolean | undefined; build_dist?: boolean | undefined; sveltekit?: boolean | undefined; nodemodules?: boolean | undefined; }

`rm_options`

type RmOptions

default { force: true, recursive: true }

returns

Promise<void>

Cli
#

Cli

type { kind: "local"; name: string; id: PathId; } | { kind: "global"; name: string; id: PathId; }

import type {Cli} from '@fuzdev/gro/cli.js';

collect_build_outputs
#

(build_dirs: string[]): Promise<{ path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]>

import {collect_build_outputs} from '@fuzdev/gro/build_cache.js';

Collects information about all files in build output directories. Returns an array of entries with path, hash, size, mtime, ctime, and mode.

Files are hashed in parallel for performance. For very large builds (10k+ files), this may take several seconds but ensures complete cache validation.

`build_dirs`

array of output directories to scan (e.g., ['build', 'dist', 'dist_server'])

type string[]

returns

Promise<BuildOutputEntry[]>

compute_build_cache_key
#

child_process_logging.ts view source

(config: GroConfig, log: Logger, git_commit?: string | null | undefined): Promise<{ git_commit: string | null; build_cache_config_hash: string; }>

import {compute_build_cache_key} from '@fuzdev/gro/build_cache.js';

Computes the cache key components for a build. This determines whether a cached build can be reused.

`config`

Gro config (build_cache_config_hash is already computed during config load)

type GroConfig

`log`

Logger

type Logger

`git_commit?`

optional pre-computed git commit hash (optimization to avoid re-reading)

type string | null

optional

returns

Promise<{ git_commit: string | null; build_cache_config_hash: string; }>

configure_colored_output_with_path_replacement
#

(child_process: ChildProcess, replacement?: string, cwd?: string): void import {configure_colored_output_with_path_replacement} from '@fuzdev/gro/child_process_logging.js';

Configures process output handling with path replacements while preserving ANSI colors.

`child_process`

type ChildProcess

`replacement`

type string

default '.'

`cwd`

type string

default process.cwd()

returns

void

cook_gro_config
#

(raw_config: RawGroConfig): Promise<GroConfig> import {cook_gro_config} from '@fuzdev/gro/gro_config.js';

Transforms a RawGroConfig to the more strict GroConfig. This allows users to provide a more relaxed config. Hashes the build_cache_config and deletes the raw value for security.

`raw_config`

type RawGroConfig

returns

Promise<GroConfig>

create_build_cache_metadata
#

(config: GroConfig, log: Logger, git_commit?: string | null | undefined, build_dirs?: string[] | undefined): Promise<{ version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { ...; }[]; }>

import {create_build_cache_metadata} from '@fuzdev/gro/build_cache.js';

Creates build cache metadata after a successful build. Automatically discovers all build output directories (build/, dist/, dist_*).

`config`

Gro config

type GroConfig

`log`

Logger

type Logger

`git_commit?`

optional pre-computed git commit hash (optimization)

type string | null

optional

`build_dirs?`

optional pre-discovered build directories (optimization to avoid redundant filesystem scans)

type string[]

optional

returns

Promise<BuildCacheMetadata>

create_empty_gro_config
#

(): GroConfig import {create_empty_gro_config} from '@fuzdev/gro/gro_config.js';

returns

GroConfig

create_gen_context
#

(base: GenContextBase, origin_id: PathId, changed_file_id?: PathId | undefined): GenContext import {create_gen_context} from '@fuzdev/gro/gen.js';

Builds a GenContext for one genfile, so generating and resolving dependencies see the same context - notably the lazy svelte_config, which is a getter rather than a value so a genfile that ignores it never resolves it.

`base`

type GenContextBase

`origin_id`

type PathId

`changed_file_id?`

type PathId

optional

returns

GenContext

create_paths
#

(root_dir: string): Paths import {create_paths} from '@fuzdev/gro/paths.js';

`root_dir`

type string

returns

Paths

CreateGroConfig
#

CreateGroConfig import type {CreateGroConfig} from '@fuzdev/gro/gro_config.js';

`(call)`

type (base_config: GroConfig): RawGroConfig | Promise<RawGroConfig>

`base_config`

type GroConfig

returns RawGroConfig | Promise<RawGroConfig>

CreateOutpaths
#

CreateOutpaths import type {CreateOutpaths} from '@fuzdev/gro/gro_plugin_server.js';

`(call)`

type (dev: boolean): Outpaths

`dev`

type boolean

returns Outpaths

CSS_MATCHER
#

esbuild_helpers.ts view source

RegExp import {CSS_MATCHER} from '@fuzdev/gro/constants.js';

default_ts_transform_options
#

TransformOptions import {default_ts_transform_options} from '@fuzdev/gro/esbuild_helpers.js';

deserialize
#

sveltekit_shim_app_forms.ts view source

<Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined>(result: string): ActionResult<Success, Failure>

import {deserialize} from '@fuzdev/gro/sveltekit_shim_app_forms.js';

`result`

type string

returns

ActionResult

dev
#

true import {dev} from '@fuzdev/gro/sveltekit_shim_app_env.js';

DevTaskContext
#

dev.task.ts view source

DevTaskContext

type PluginContext<Args>

import type {DevTaskContext} from '@fuzdev/gro/dev.task.js';

`dev`

type boolean

`watch`

type boolean

`args`

type { watch: boolean; 'no-watch': boolean; sync: boolean; 'no-sync': boolean; install: boolean; }

`config`

type GroConfig

`svelte_config`

Resolved on first access, so tasks that don't touch it never pay to read the SvelteKit config.

type Promise<ParsedSvelteConfig>

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

`invoke_task`

type <TName extends string>(task_name: InvokeTaskName<TName>, ...rest: InvokeTaskRest<TName>): Promise<void>

`task_name`

type InvokeTaskName<TName>

`rest`

type InvokeTaskRest<TName>

returns Promise<void>

disableScrollHandling
#

() => void import {disableScrollHandling} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

discover_build_output_dirs
#

(): Promise<string[]> import {discover_build_output_dirs} from '@fuzdev/gro/build_cache.js';

Discovers all build output directories in the current working directory. Returns an array of directory names that exist: build/, dist/, dist_*

returns

Promise<string[]>

Disknode
#

disknode.ts view source

Disknode import type {Disknode} from '@fuzdev/gro/disknode.js';

`id`

type PathId

`contents`

null contents means it doesn't exist. We create the file in memory to track its dependents regardless of its existence on disk.

type string | null

`external`

Is the source file outside of the root_dir or excluded by watch_dir_options.filter?

type boolean

`ctime`

type number | null

`mtime`

type number | null

`content_hash`

SHA-256 hash of contents. null iff contents is null. Used for content-based change detection and caching.

type string | null

`dependents`

type Map<PathId, Disknode>

`dependencies`

type Map<PathId, Disknode>

EMPTY_BUILD_CACHE_CONFIG_HASH
#

sveltekit_shim_app_forms.ts view source

"af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262" import {EMPTY_BUILD_CACHE_CONFIG_HASH} from '@fuzdev/gro/gro_config.js';

BLAKE3 hash of empty string, used for configs without build_cache_config. This ensures consistent cache behavior when no custom config is provided.

enhance
#

<Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined>(form_element: HTMLFormElement, submit?: SubmitFunction<Success, Failure> | undefined): { ...; }

import {enhance} from '@fuzdev/gro/sveltekit_shim_app_forms.js';

`form_element`

type HTMLFormElement

`submit?`

type SubmitFunction<Success, Failure>

optional

returns

{ destroy(): void; }

env_var_has_visibility
#

(config: EnvVarConfig<any>, visibility: EnvVisibility): boolean import {env_var_has_visibility} from '@fuzdev/gro/env.js';

Whether a declared env var belongs to visibility - SvelteKit's vars are private unless declared public: true.

`config`

type EnvVarConfig<any>

`visibility`

type EnvVisibility

returns

boolean

EnvVarDeclarations
#

EnvVarDeclarations import type {EnvVarDeclarations} from '@fuzdev/gro/env.js';

The variables a project's src/env.ts exports via SvelteKit's defineEnvVars.

`[key: string]`

type EnvVarConfig<any>

EnvVisibility
#

esbuild_plugin_external_worker.ts view source

EnvVisibility

type "public" | "private"

import type {EnvVisibility} from '@fuzdev/gro/env.js';

esbuild_plugin_external_worker
#

({ dev, build_options, dir, svelte_compile_options, svelte_compile_module_options, svelte_preprocessors, base_url, assets_url, version_name, src_path, env_dir, env_files, ambient_env, log }: EsbuildPluginExternalWorkerOptions): Plugin

import {esbuild_plugin_external_worker} from '@fuzdev/gro/esbuild_plugin_external_worker.js';

`__0`

type EsbuildPluginExternalWorkerOptions

returns

Plugin

esbuild_plugin_svelte
#

esbuild_plugin_svelte.ts view source

(options: EsbuildPluginSvelteOptions): Plugin import {esbuild_plugin_svelte} from '@fuzdev/gro/esbuild_plugin_svelte.js';

`options`

type EsbuildPluginSvelteOptions

returns

Plugin

esbuild_plugin_sveltekit_local_imports
#

esbuild_plugin_sveltekit_local_imports.ts view source

(): Plugin import {esbuild_plugin_sveltekit_local_imports} from '@fuzdev/gro/esbuild_plugin_sveltekit_local_imports.js';

Adds support for imports to both .ts and .js, as well as imports without extensions that resolve to .js or .ts. Prefers .ts over any .js, and falls back to .ts if no file is found.

returns

Plugin

esbuild_plugin_sveltekit_shim_app
#

esbuild_plugin_sveltekit_shim_app.ts view source

({ dev, base_url, assets_url, version_name }: EsbuildPluginSveltekitShimAppOptions): Plugin import {esbuild_plugin_sveltekit_shim_app} from '@fuzdev/gro/esbuild_plugin_sveltekit_shim_app.js';

`__0`

type EsbuildPluginSveltekitShimAppOptions

returns

Plugin

esbuild_plugin_sveltekit_shim_app_env_vars
#

esbuild_plugin_sveltekit_shim_app_env_vars.ts view source

({ dev, dir, src_path, env_dir, env_files, ambient_env }: EsbuildPluginSveltekitShimAppEnvVarsOptions): Plugin import {esbuild_plugin_sveltekit_shim_app_env_vars} from '@fuzdev/gro/esbuild_plugin_sveltekit_shim_app_env_vars.js';

`__0`

type EsbuildPluginSveltekitShimAppEnvVarsOptions

returns

Plugin

EsbuildPluginExternalWorkerOptions
#

esbuild_plugin_external_worker.ts view source

EsbuildPluginExternalWorkerOptions import type {EsbuildPluginExternalWorkerOptions} from '@fuzdev/gro/esbuild_plugin_external_worker.js';

`dev`

type boolean

`build_options`

type BuildOptions

`dir?`

type string

`svelte_compile_options?`

type CompileOptions

`svelte_compile_module_options?`

type ModuleCompileOptions

`svelte_preprocessors?`

type PreprocessorGroup | PreprocessorGroup[]

`base_url?`

type "" | `/${string}`

`assets_url?`

type "" | `http://${string}` | `https://${string}`

`version_name?`

type string

`src_path?`

type string

`env_dir?`

type string

`env_files?`

type string[]

`ambient_env?`

type Record<string, string>

`log?`

type Logger

EsbuildPluginSveltekitShimAppEnvVarsOptions
#

esbuild_plugin_sveltekit_shim_app_env_vars.ts view source

EsbuildPluginSveltekitShimAppEnvVarsOptions

import type {EsbuildPluginSveltekitShimAppEnvVarsOptions} from '@fuzdev/gro/esbuild_plugin_sveltekit_shim_app_env_vars.js';

`dev`

type boolean

`dir?`

type string

`src_path?`

The SvelteKit files.src, where the env.ts declarations live.

type string

`env_dir?`

type string

`env_files?`

type string[]

`ambient_env?`

type Record<string, string>

EsbuildPluginSveltekitShimAppOptions
#

esbuild_plugin_sveltekit_shim_app.ts view source

EsbuildPluginSveltekitShimAppOptions import type {EsbuildPluginSveltekitShimAppOptions} from '@fuzdev/gro/esbuild_plugin_sveltekit_shim_app.js';

`dev`

type boolean

`base_url`

type "" | `/${string}` | undefined

`assets_url`

type "" | `http://${string}` | `https://${string}` | undefined

`version_name?`

type string

EsbuildPluginSvelteOptions
#

esbuild_plugin_svelte.ts view source

EsbuildPluginSvelteOptions import type {EsbuildPluginSvelteOptions} from '@fuzdev/gro/esbuild_plugin_svelte.js';

`dev`

type boolean

`base_url`

type "" | `/${string}` | undefined

`dir?`

type string

`svelte_compile_options?`

Defaults to Gro's baseline, not the project's compilerOptions - reading those is async, so callers pass svelte_compile_options off a ParsedSvelteConfig to honor them.

type CompileOptions

default `SVELTE_COMPILE_OPTIONS_DEFAULT`

`svelte_compile_module_options?`

type ModuleCompileOptions

`svelte_preprocessors?`

type PreprocessorGroup | PreprocessorGroup[]

`ts_transform_options?`

type TransformOptions

`is_ts?`

type (filename: string): boolean

`filename`

type string

returns boolean

EVERYTHING_MATCHER
#

RegExp import {EVERYTHING_MATCHER} from '@fuzdev/gro/constants.js';

Filer
#

import {Filer} from '@fuzdev/gro/filer.js';

`root_dir`

type PathId

readonly

`files`

type Map<PathId, Disknode>

readonly

`constructor`

type new (options?: FilerOptions): Filer

`options`

type FilerOptions

default EMPTY_OBJECT

`get_by_id`

type (id: PathId) => Disknode | undefined

`get_or_create`

type (id: PathId) => Disknode

`filter`

type (predicate: (disknode: Disknode) => boolean): Disknode[] | null

`predicate`

type (disknode: Disknode) => boolean

returns Disknode[] | null

`init`

Initialize the filer to populate files without watching. Safe to call multiple times - subsequent calls are no-ops. Used by gen files to access the file graph.

type (): Promise<void>

returns Promise<void>

`watch`

type (listener: OnFilerChange): Promise<() => void>

`listener`

type OnFilerChange

returns Promise<() => void>

`close`

type (): Promise<void>

returns Promise<void>

`inited`

type boolean

getter

FilerOptions
#

FilerOptions import type {FilerOptions} from '@fuzdev/gro/filer.js';

`watch_dir?`

type ({ dir, on_change, filter, absolute, chokidar, ignored }: WatchDirOptions): WatchNodeFs

`__0`

type WatchDirOptions

returns WatchNodeFs

`watch_dir_options?`

type Partial<OmitStrict<WatchDirOptions, "on_change">>

`package_json_cache?`

type Record<string, PackageJson>

`log?`

type Logger

filter_dependents
#

(disknode: Disknode, get_by_id: (id: PathId) => Disknode | undefined, filter?: FileFilter | undefined, results?: Set<PathId>, searched?: Set<...>, log?: Logger | undefined): Set<...>

import {filter_dependents} from '@fuzdev/gro/filer.js';

`disknode`

type Disknode

`get_by_id`

type (id: PathId) => Disknode | undefined

`filter?`

type FileFilter

optional

`results`

type Set<PathId>

default new Set()

`searched`

type Set<PathId>

default new Set()

`log?`

type Logger

optional

returns

Set<PathId>

find_cli
#

(name: string, cwd?: string | URL, options?: SpawnOptions | undefined): Promise<Cli | null> import {find_cli} from '@fuzdev/gro/cli.js';

Searches the filesystem for the CLI name, first local to the cwd and then globally.

`name`

type string

`cwd`

type string | URL

default process.cwd()

`options?`

type SpawnOptions

optional

returns

Promise<Cli | null>

null if not found locally or globally

find_genfiles
#

(input_paths: InputPath[], root_dirs: PathId[], config: GroConfig, timings?: Timings | undefined): Promise<FindGenfilesResult>

import {find_genfiles} from '@fuzdev/gro/gen.js';

Finds modules from input paths. (see input_path.ts for more)

`input_paths`

type InputPath[]

`root_dirs`

type PathId[]

`config`

type GroConfig

`timings?`

type Timings

optional

returns

Promise<FindGenfilesResult>

find_tasks
#

(input_paths: InputPath[], task_root_dirs: PathId[], config: GroConfig, timings?: Timings | undefined): Promise<FindTasksResult>

import {find_tasks} from '@fuzdev/gro/task.js';

Finds modules from input paths. (see input_path.ts for more)

`input_paths`

type InputPath[]

`task_root_dirs`

type PathId[]

`config`

type GroConfig

`timings?`

type Timings

optional

returns

Promise<FindTasksResult>

FindGenfilesFailure
#

FindGenfilesFailure

type { type: "unmapped_input_paths"; unmapped_input_paths: InputPath[]; resolved_input_paths: ResolvedInputPath[]; reasons: string[]; } | { type: "input_directories_with_no_files"; input_directories_with_no_files: InputPath[]; resolved_input_files: ResolvedInputFile[]; resolved_input_files_by_root_dir: Map<PathId, ResolvedInputFile[]>; resolved_input_paths: ResolvedInputPath[]; reasons: string[]; }

import type {FindGenfilesFailure} from '@fuzdev/gro/gen.js';

FindGenfilesResult
#

FindGenfilesResult

type ({ ok: true; } & { value: FoundGenfiles; }) | (({ ok: false; } & { type: "unmapped_input_paths"; unmapped_input_paths: InputPath[]; resolved_input_paths: ResolvedInputPath[]; reasons: string[]; }) | ({ ok: false; } & { type: "input_directories_with_no_files"; input_directories_with_no_files: InputPath[]; resolved_input_files: ResolvedInputFile[]; resolved_input_files_by_root_dir: Map<PathId, ResolvedInputFile[]>; resolved_input_paths: ResolvedInputPath[]; reasons: string[]; }))

import type {FindGenfilesResult} from '@fuzdev/gro/gen.js';

FindModulesFailure
#

FindModulesFailure

type { type: "unmapped_input_paths"; unmapped_input_paths: InputPath[]; resolved_input_paths: ResolvedInputPath[]; input_paths: InputPath[]; task_root_dirs: PathId[]; reasons: string[]; } | { type: "input_directories_with_no_files"; input_directories_with_no_files: InputPath[]; resolved_input_files: ResolvedInputFile[]; resolved_input_files_by_root_dir: Map<PathId, ResolvedInputFile[]>; resolved_input_paths: ResolvedInputPath[]; input_paths: InputPath[]; task_root_dirs: PathId[]; reasons: string[]; }

import type {FindModulesFailure} from '@fuzdev/gro/task.js';

FindTasksResult
#

format_directory.ts view source

FindTasksResult

type ({ ok: true; } & { value: FoundTasks; }) | (({ ok: false; } & { type: "unmapped_input_paths"; unmapped_input_paths: InputPath[]; resolved_input_paths: ResolvedInputPath[]; input_paths: InputPath[]; task_root_dirs: PathId[]; reasons: string[]; }) | ({ ok: false; } & { type: "input_directories_with_no_files"; input_directories_with_no_files: InputPath[]; resolved_input_files: ResolvedInputFile[]; resolved_input_files_by_root_dir: Map<PathId, ResolvedInputFile[]>; resolved_input_paths: ResolvedInputPath[]; input_paths: InputPath[]; task_root_dirs: PathId[]; reasons: string[]; }))

import type {FindTasksResult} from '@fuzdev/gro/task.js';

format_directory
#

(log: Logger, dir: string, check?: boolean, filter?: PathFilter | PathFilter[] | undefined, patterns?: string[] | undefined): Promise<FormatDirectoryResult>

import {format_directory} from '@fuzdev/gro/format_directory.js';

Formats files on the filesystem in-process via format_file. When patterns is provided, formats those specific files/globs. Otherwise formats dir (recursively, respecting filter) plus the root files when dir is paths.source. In both modes, files matched by the project root's .formatignore or .prettierignore are skipped.

Files the formatter rejects (e.g. a syntax error) are reported and fail the run in both modes rather than being silently skipped.

This is separated from ./format_file so modules that only need directory traversal don't pull in the formatter (which loads the tsv native addon).

`log`

type Logger

`dir`

type string

`check`

when true, reports unformatted files instead of writing them

type boolean

default false

`filter?`

directory filters (e.g. config.search_filters) to skip; also prunes patterns results so an explicit glob can't reach node_modules

type (PathFilter) | (PathFilter)[]

optional

`patterns?`

type string[]

optional

returns

Promise<FormatDirectoryResult>

format_file
#

format_file.ts view source

(content: string, options?: FormatFileOptions): string import {format_file} from '@fuzdev/gro/format_file.js';

Formats a string of source code in-process. Passes the input through unchanged when the language is unsupported (an expected no-op), but throws when the formatter rejects the source — e.g. a syntax error — so callers can decide whether to log, skip, or fail rather than silently treating broken input as already-formatted.

`content`

the source to format

type string

`options`

a filepath to infer the language, or an explicit lang

type FormatFileOptions

default {}

returns

string

FormatDirectoryResult
#

format_directory.ts view source

FormatDirectoryResult import type {FormatDirectoryResult} from '@fuzdev/gro/format_directory.js';

`ok`

type boolean

`formatted`

The files that were formatted (or, in check mode, that need formatting).

type string[]

`errored`

Files the formatter rejected (e.g. a syntax error), left untouched.

type { id: string; error: unknown; }[]

FormatFileOptions
#

format_file.ts view source

FormatFileOptions import type {FormatFileOptions} from '@fuzdev/gro/format_file.js';

`filepath?`

The file path, used to infer the language from its extension.

type string

`lang?`

The language to format as, overriding any inference from filepath.

type FormatLang

FormatLang
#

format_file.ts view source

FormatLang

type "typescript" | "svelte" | "css" | "json"

import type {FormatLang} from '@fuzdev/gro/format_file.js';

The source languages Gro can format in-process, backed by @fuzdev/tsv (typescript/svelte/css) plus a builtin json formatter. Anything else passes through unchanged.

FoundGenfiles
#

FoundGenfiles import type {FoundGenfiles} from '@fuzdev/gro/gen.js';

`resolved_input_files`

type ResolvedInputFile[]

`resolved_input_files_by_root_dir`

type Map<PathId, ResolvedInputFile[]>

`resolved_input_paths`

type ResolvedInputPath[]

FoundTask
#

FoundTask import type {FoundTask} from '@fuzdev/gro/task.js';

`input_path`

type InputPath

`id`

type PathId

`task_root_dir`

type PathId

FoundTasks
#

FoundTasks import type {FoundTasks} from '@fuzdev/gro/task.js';

`resolved_input_files`

type ResolvedInputFile[]

`resolved_input_files_by_root_dir`

type Map<PathId, ResolvedInputFile[]>

`resolved_input_paths`

type ResolvedInputPath[]

`input_paths`

type InputPath[]

`task_root_dirs`

type PathId[]

Gen
#

Gen

type (GenFunction) | GenConfig

import type {Gen} from '@fuzdev/gro/gen.js';

GEN_FILE_PATTERN
#

string import {GEN_FILE_PATTERN} from '@fuzdev/gro/gen.js';

GEN_FILE_PATTERN_TEXT
#

"gen" import {GEN_FILE_PATTERN_TEXT} from '@fuzdev/gro/gen.js';

GEN_NO_PROD_MESSAGE
#

run_gen.ts view source

"gen runs only during development" import {GEN_NO_PROD_MESSAGE} from '@fuzdev/gro/run_gen.js';

gen_task_registry
#

GenConfig import {gen_task_registry} from '@fuzdev/gro/task_registry.js';

The genfile config that types a project's tasks for invoke_task. Export it as gen from a genfile like src/gro_tasks.gen.ts, which writes src/gro_tasks.ts augmenting ProjectTasks. In gro dev it regenerates when a task file is added or changed; gro dev ignores deletes, so run gro gen after removing a task.

GenConfig
#

GenConfig import type {GenConfig} from '@fuzdev/gro/gen.js';

`generate`

type (ctx: GenContext): RawGenResult | Promise<RawGenResult>

`ctx`

type GenContext

returns RawGenResult | Promise<RawGenResult>

`dependencies?`

type GenDependencies

GenContext
#

GenContext import type {GenContext} from '@fuzdev/gro/gen.js';

`config`

type GroConfig

`svelte_config`

Resolved on first access, so genfiles that don't touch it never pay to read the SvelteKit config.

type Promise<ParsedSvelteConfig>

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

`invoke_task`

type <TName extends string>(task_name: InvokeTaskName<TName>, ...rest: InvokeTaskRest<TName>): Promise<void>

`task_name`

type InvokeTaskName<TName>

`rest`

type InvokeTaskRest<TName>

returns Promise<void>

`origin_id`

Same as import.meta.url but in path form.

type PathId

`origin_path`

The origin_id relative to the root dir.

type string

`changed_file_id`

The file that triggered dependency checking. Only available when resolving dependencies dynamically. undefined during actual generation.

type PathId | undefined

GenContextBase
#

GenContextBase import type {GenContextBase} from '@fuzdev/gro/gen.js';

The GenContext values that are the same for every genfile in a run, as opposed to the per-genfile ones create_gen_context derives.

`config`

type GroConfig

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

`invoke_task`

type <TName extends string>(task_name: InvokeTaskName<TName>, ...rest: InvokeTaskRest<TName>): Promise<void>

`task_name`

type InvokeTaskName<TName>

`rest`

type InvokeTaskRest<TName>

returns Promise<void>

GenDependencies
#

GenDependencies

type "all" | GenDependenciesConfig | (GenDependenciesResolver)

import type {GenDependencies} from '@fuzdev/gro/gen.js';

GenDependenciesConfig
#

GenDependenciesConfig import type {GenDependenciesConfig} from '@fuzdev/gro/gen.js';

`patterns?`

type RegExp[]

`files?`

type PathId[]

GenDependenciesResolver
#

GenDependenciesResolver import type {GenDependenciesResolver} from '@fuzdev/gro/gen.js';

`(call)`

`ctx`

type GenContext

GenFile
#

GenFile import type {GenFile} from '@fuzdev/gro/gen.js';

`id`

type PathId

`content`

type string

`origin_id`

type PathId

`format`

type boolean

GenfileModule
#

GenfileModule import type {GenfileModule} from '@fuzdev/gro/gen.js';

`gen`

type Gen

GenfileModuleMeta
#

GenfileModuleMeta

type ModuleMeta<GenfileModule>

import type {GenfileModuleMeta} from '@fuzdev/gro/gen.js';

`id`

type PathId

`mod`

type GenfileModule

GenfileModuleResult
#

GenfileModuleResult

type GenfileModuleResultSuccess | GenfileModuleResultFailure

import type {GenfileModuleResult} from '@fuzdev/gro/gen.js';

GenfileModuleResultFailure
#

GenfileModuleResultFailure import type {GenfileModuleResultFailure} from '@fuzdev/gro/gen.js';

`ok`

type false

`id`

type PathId

`reason`

type string

`error`

type Error

`elapsed`

type number

GenfileModuleResultSuccess
#

GenfileModuleResultSuccess import type {GenfileModuleResultSuccess} from '@fuzdev/gro/gen.js';

`ok`

type true

`id`

type PathId

`files`

type GenFile[]

`elapsed`

type number

GenFunction
#

GenFunction import type {GenFunction} from '@fuzdev/gro/gen.js';

`(call)`

type (ctx: GenContext): RawGenResult | Promise<RawGenResult>

`ctx`

type GenContext

returns RawGenResult | Promise<RawGenResult>

GenResult
#

GenResult import type {GenResult} from '@fuzdev/gro/gen.js';

`origin_id`

type PathId

`files`

type GenFile[]

GenResults
#

GenResults import type {GenResults} from '@fuzdev/gro/gen.js';

`input_count`

type number

`output_count`

type number

`elapsed`

type number

get_possible_paths
#

(input_path: InputPath, root_dirs: PathId[], extensions: string[]): Promise<PossiblePath[]> import {get_possible_paths} from '@fuzdev/gro/input_path.js';

Gets a list of possible source ids for each input path with extensions, duplicating each under root_dirs, without checking the filesystem.

`input_path`

type InputPath

`root_dirs`

type PathId[]

`extensions`

type string[]

returns

Promise<PossiblePath[]>

GIT_DIRNAME
#

build.task.ts view source

".git" import {GIT_DIRNAME} from '@fuzdev/gro/constants.js';

GIT_SHORT_HASH_LENGTH
#

7 import {GIT_SHORT_HASH_LENGTH} from '@fuzdev/gro/build.task.js';

Length of git commit hash when displayed in logs (standard git convention).

github_fetch_commit_prs
#

github.ts view source

(owner: string, repo: string, commit_sha: string, token?: string | undefined, log?: Logger | undefined, cache?: Map<string, { key: string; url: string; params: any; value: any; etag: string | null; last_modified: string | null; }> | undefined, api_version?: string | undefined): Promise<...>

import {github_fetch_commit_prs} from '@fuzdev/gro/github.js';

`owner`

type string

`repo`

type string

`commit_sha`

type string

`token?`

type string

optional

`log?`

type Logger

optional

`cache?`

type Map<string, { key: string; url: string; params: any; value: any; etag: string | null; last_modified: string | null; }>

optional

`api_version?`

type string

optional

returns

Promise<GithubPullRequest[] | null>

GITHUB_REPO_MATCHER
#

github.ts view source

RegExp import {GITHUB_REPO_MATCHER} from '@fuzdev/gro/github.js';

GithubPullRequest
#

github.ts view source

value + type

{ [x: string]: unknown; url: string; id: number; html_url: string; number: number; user: { [x: string]: unknown; login: string; }; }

import {GithubPullRequest} from '@fuzdev/gro/github.js';

`url`

type string

`id`

type number

`html_url`

type string

`number`

type number

`user`

type { [x: string]: unknown; login: string; }

`[key: string]`

type unknown

goto
#

(url: string | URL, opts?: GotoOptions | undefined) => Promise<void> import {goto} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

GRO_CONFIG_FILENAME
#

"gro.config.ts" import {GRO_CONFIG_FILENAME} from '@fuzdev/gro/constants.js';

GRO_DEV_DIR
#

string import {GRO_DEV_DIR} from '@fuzdev/gro/constants.js';

GRO_DEV_DIRNAME
#

string import {GRO_DEV_DIRNAME} from '@fuzdev/gro/constants.js';

GRO_DIR
#

string import {GRO_DIR} from '@fuzdev/gro/constants.js';

GRO_DIRNAME
#

".gro" import {GRO_DIRNAME} from '@fuzdev/gro/constants.js';

GRO_DIST_DIR
#

string import {GRO_DIST_DIR} from '@fuzdev/gro/paths.js';

GRO_DIST_PREFIX
#

"dist_" import {GRO_DIST_PREFIX} from '@fuzdev/gro/constants.js';

GRO_PACKAGE_DIR
#

"gro/" import {GRO_PACKAGE_DIR} from '@fuzdev/gro/paths.js';

gro_paths
#

gro_plugin_deno_server.ts view source

Paths import {gro_paths} from '@fuzdev/gro/paths.js';

Paths for the Gro package being used by the user repo.

gro_plugin_deno_server
#

(options?: GroPluginDenoServerOptions): Plugin<PluginContext<object>> import {gro_plugin_deno_server} from '@fuzdev/gro/gro_plugin_deno_server.js';

Creates a gro plugin that runs a Deno server during development. The server is started during setup and stopped on teardown.

In dev mode, Vite should proxy API requests to this server.

`options`

type GroPluginDenoServerOptions

default {}

returns

Plugin<PluginContext<object>>

gro_plugin_gen
#

gro_plugin_gen.ts view source

({ input_paths, root_dirs, flush_debounce_delay }?: GroPluginGenOptions): Plugin<PluginContext<object>> import {gro_plugin_gen} from '@fuzdev/gro/gro_plugin_gen.js';

`__0`

type GroPluginGenOptions

default EMPTY_OBJECT

returns

Plugin<PluginContext<object>>

gro_plugin_server
#

gro_plugin_sveltekit_app.ts view source

({ entry_points, dir, outpaths, env_files, ambient_env, svelte_config, target, esbuild_build_options, rebuild_throttle_delay, cli_command, run }?: GroPluginServerOptions): Plugin<PluginContext<object>>

import {gro_plugin_server} from '@fuzdev/gro/gro_plugin_server.js';

`__0`

type GroPluginServerOptions

default {}

returns

Plugin<PluginContext<object>>

gro_plugin_sveltekit_app
#

({ vite_cli }?: GroPluginSveltekitAppOptions): Plugin<PluginContext<object>> import {gro_plugin_sveltekit_app} from '@fuzdev/gro/gro_plugin_sveltekit_app.js';

`__0`

type GroPluginSveltekitAppOptions

default {}

returns

Plugin<PluginContext<object>>

gro_plugin_sveltekit_library
#

gro_plugin_sveltekit_library.ts view source

({ svelte_package_options, svelte_package_cli }?: GroPluginSveltekitLibraryOptions): Plugin<PluginContext<object>> import {gro_plugin_sveltekit_library} from '@fuzdev/gro/gro_plugin_sveltekit_library.js';

`__0`

type GroPluginSveltekitLibraryOptions

default {}

returns

Plugin<PluginContext<object>>

GroBuiltinTasks
#

gro_builtin_tasks.ts view source

GroBuiltinTasks import type {GroBuiltinTasks} from '@fuzdev/gro/gro_builtin_tasks.js';

Gro's builtin tasks by name, mapped to their module types.

`build`

type typeof import("build.task.ts", { with: { "resolution-mode": "import" } })

`changeset`

type typeof import("changeset.task.ts", { with: { "resolution-mode": "import" } })

`check`

type typeof import("check.task.ts", { with: { "resolution-mode": "import" } })

`clean`

type typeof import("clean.task.ts", { with: { "resolution-mode": "import" } })

`commit`

type typeof import("commit.task.ts", { with: { "resolution-mode": "import" } })

`deploy`

type typeof import("deploy.task.ts", { with: { "resolution-mode": "import" } })

`dev`

type typeof import("dev.task.ts", { with: { "resolution-mode": "import" } })

`format`

type typeof import("format.task.ts", { with: { "resolution-mode": "import" } })

`gen`

type typeof import("gen.task.ts", { with: { "resolution-mode": "import" } })

`lint`

type typeof import("lint.task.ts", { with: { "resolution-mode": "import" } })

`publish`

type typeof import("publish.task.ts", { with: { "resolution-mode": "import" } })

`reinstall`

type typeof import("reinstall.task.ts", { with: { "resolution-mode": "import" } })

`release`

type typeof import("release.task.ts", { with: { "resolution-mode": "import" } })

`resolve`

type typeof import("resolve.task.ts", { with: { "resolution-mode": "import" } })

`run`

type typeof import("run.task.ts", { with: { "resolution-mode": "import" } })

`sync`

type typeof import("sync.task.ts", { with: { "resolution-mode": "import" } })

`test`

type typeof import("test.task.ts", { with: { "resolution-mode": "import" } })

`typecheck`

type typeof import("typecheck.task.ts", { with: { "resolution-mode": "import" } })

`upgrade`

type typeof import("upgrade.task.ts", { with: { "resolution-mode": "import" } })

GroConfig
#

GroConfig import type {GroConfig} from '@fuzdev/gro/gro_config.js';

The config that users can extend via gro.config.ts. This is exposed to users in places like tasks and genfiles.

inheritance

extends: RawGroConfig

`plugins`

type (ctx: PluginContext<object>): Plugin<PluginContext<object>>[] | Promise<Plugin<PluginContext<object>>[]>

`ctx`

type PluginContext<object>

returns Plugin<PluginContext<object>>[] | Promise<Plugin<PluginContext<object>>[]>

see also

https://github.com/fuzdev/gro/blob/main/src/docs/plugin.md

`map_package_json`

Maps the project's package.json before writing it to the filesystem. The package_json argument may be mutated, but the return value is what's used by the caller. Returning null is a no-op for the caller.

type (PackageJsonMapper) | null

`task_root_dirs`

The root directories to search for tasks given implicit relative input paths. Defaults to ./src/lib, then the cwd, then the Gro package dist.

type PathId[]

`search_filters`

When searching the filesystem for tasks and genfiles, directories and files are included if they pass all of these filters.

type PathFilter[]

`js_cli`

The CLI to use that's compatible with node.

type string

`pm_cli`

The CLI to use that's compatible with npm install and npm link. Defaults to 'npm'.

type string

`build_cache_config_hash`

SHA-256 hash of the user's build_cache_config from gro.config.ts. This is computed during config normalization and the raw value is immediately deleted. If no build_cache_config was provided, this is the hash of an empty string.

type string

see also

``RawGroConfig.build_cache_config``

`filer_options`

Options passed to the Filer for file watching and import resolution.

type Partial<FilerOptions> | null

see also

``FilerOptions``

GroConfigModule
#

gro_plugin_deno_server.ts view source

GroConfigModule import type {GroConfigModule} from '@fuzdev/gro/gro_config.js';

`default`

type (CreateGroConfig) | RawGroConfig

readonly

GroPluginDenoServerOptions
#

GroPluginDenoServerOptions import type {GroPluginDenoServerOptions} from '@fuzdev/gro/gro_plugin_deno_server.js';

`entry?`

Entry point TypeScript file for the Deno server.

type string

default 'src/lib/backend/server.ts'

`port?`

Port for the Deno server.

type number

default 4041

`host?`

Host for the Deno server.

type string

default 'localhost'

`permissions?`

Deno permissions to grant.

type string[]

default ['--allow-net', '--allow-read', '--allow-env']

`flags?`

Additional deno run flags (e.g. --sloppy-imports, --no-check).

type string[]

default []

`watch?`

Whether to watch for file changes and restart. Uses Deno's built-in --watch flag.

type boolean

default true in `dev`

`env_file?`

Env file to load via Deno's --env flag. Set to null to disable env file loading.

type string | null

default '.env.development'

`env?`

Additional environment variables to pass to the child process. Always merged with the parent process.env (for PATH, HOME, etc.). PORT, HOST, and NODE_ENV are set automatically from the plugin options.

type Record<string, string>

default {}

GroPluginGenOptions
#

gro_plugin_gen.ts view source

GroPluginGenOptions import type {GroPluginGenOptions} from '@fuzdev/gro/gro_plugin_gen.js';

`input_paths?`

type string[]

`root_dirs?`

type string[]

`flush_debounce_delay?`

type number

GroPluginServerOptions
#

gro_plugin_sveltekit_app.ts view source

GroPluginServerOptions import type {GroPluginServerOptions} from '@fuzdev/gro/gro_plugin_server.js';

`entry_points?`

same as esbuild's entryPoints

type string[]

default ```[to_server_source_id()]```

`dir?`

type string

default cwd

`outpaths?`

Returns the Outpaths given a dev param. Decoupling this from plugin creation allows it to be created generically, so the build and dev tasks can be the source of truth for dev.

type (dev: boolean): Outpaths

default `to_default_outpaths`

`dev`

type boolean

returns Outpaths

`env_files?`

type string[]

default ```SvelteKit's `.env`, `.env.development`, and `.env.production````

`ambient_env?`

type Record<string, string>

default process.env

`svelte_config?`

An already-loaded Svelte config, to skip resolving the project's Vite config.

type Config

default ```resolved from the project's Vite config````

`target?`

type string

default 'esnext'

`esbuild_build_options?`

Optionally map the esbuild options.

type (base_options: BuildOptions): BuildOptions

default `identity`

`base_options`

type BuildOptions

returns BuildOptions

`rebuild_throttle_delay?`

Milliseconds to throttle rebuilds. Should be longer than it takes to build to avoid backpressure.

type number

default 1000

`cli_command?`

The CLI command to run the server, like 'node' or 'bun' or 'deno'. Receives the path to the server js file as its argument.

type string

default 'node'

`run?`

Whether to run the server or not after building.

type boolean

default `dev`

GroPluginSveltekitAppOptions
#

GroPluginSveltekitAppOptions import type {GroPluginSveltekitAppOptions} from '@fuzdev/gro/gro_plugin_sveltekit_app.js';

`vite_cli?`

The Vite CLI to use.

type string

GroPluginSveltekitLibraryOptions
#

gro_plugin_sveltekit_library.ts view source

GroPluginSveltekitLibraryOptions import type {GroPluginSveltekitLibraryOptions} from '@fuzdev/gro/gro_plugin_sveltekit_library.js';

`svelte_package_options?`

The options passed to the SvelteKit packaging CLI.

type SveltePackageOptions

see also

https://svelte.dev/docs/kit/packaging#options

`svelte_package_cli?`

The SvelteKit packaging CLI to use. Defaults to svelte-package.

type string

see also

https://svelte.dev/docs/kit/packaging

has_server
#

(path?: string | undefined): Promise<Result<object, { message: string; }>> import {has_server} from '@fuzdev/gro/gro_plugin_server.js';

`path?`

the server entry point to look for, defaults to to_server_source_id()

type string

optional

returns

Promise<Result>

has_sveltekit_app
#

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }): Result<...>

import {has_sveltekit_app} from '@fuzdev/gro/sveltekit_helpers.js';

Detected from package.json rather than the Svelte config, because reading the config costs a full Vite config resolution. Peer deps don't count - a package peered on SvelteKit is built to work with one, not to be one, and counting them would run vite build over a library that has no app.

`package_json`

type PackageJson

returns

Result

has_sveltekit_library
#

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }): Promise<...>

import {has_sveltekit_library} from '@fuzdev/gro/sveltekit_helpers.js';

`package_json`

type PackageJson

returns

Promise<Result>

has_vite_config
#

parse_imports.ts view source

(dir?: string): boolean import {has_vite_config} from '@fuzdev/gro/svelte_config.js';

Whether the project in dir has a Vite config, and so anything to read a Svelte config through. Exported because it's what makes a config read worth caching - a project without one never pays for a resolution to begin with.

`dir`

type string

default process.cwd()

returns

boolean

ImportSpecifier
#

ImportSpecifier

type string & Flavor<"ImportSpecifier">

import type {ImportSpecifier} from '@fuzdev/gro/parse_imports.js';

external types

Flavored<string, 'ImportSpecifier'>

infer_paths
#

(id: PathId): Paths import {infer_paths} from '@fuzdev/gro/paths.js';

`id`

type PathId

returns

Paths

InputPath
#

value + type

InputPath

type string & Flavor<"InputPath">

import {InputPath} from '@fuzdev/gro/input_path.js';

external types

Flavored<z.infer<typeof InputPath>, 'InputPath'>

install_with_cache_healing
#

(pm_cli: string, options?: InstallCacheHealingOptions): Promise<NpmCommandResult> import {install_with_cache_healing} from '@fuzdev/gro/npm_install_helpers.js';

Installs dependencies, self-healing the stale-cache (ETARGET) failure mode.

Strategy:

First attempt: ${pm_cli} install [...install_args].
On an npm ETARGET-class failure (stale cache): npm cache clean --force then retry the same install once.
On any other failure — or any failure under a non-npm pm_cli — return immediately without healing.

Why ETARGET happens: right after a dependency is published and the registry has propagated, npm's local cache may still hold stale "404"/no-version metadata for it; clearing the cache forces a fresh metadata fetch. This makes installs safe to run immediately after publishing an upstream package — e.g. picking up a just-released dep in a dependency-ordered publish chain, or gro upgrade-ing to a fresh @latest.

npm only: the heal uses npm-specific syntax (cache clean --force), so it's gated on pm_cli === 'npm'. A non-npm pm_cli surfaces the failure unchanged rather than running a command it can't understand.

The env is always passed through sanitize_install_env so the build's devDependencies survive.

`pm_cli`

the npm-compatible CLI to run (e.g. config.pm_cli)

type string

`options`

cwd, env, logger, extra install args, and an injectable runner

type InstallCacheHealingOptions

default {}

returns

Promise<NpmCommandResult>

the result of the (possibly retried) install

install_with_cache_healing_or_throw
#

(pm_cli: string, options?: InstallCacheHealingOptions & { context?: string | undefined; }): Promise<void> import {install_with_cache_healing_or_throw} from '@fuzdev/gro/npm_install_helpers.js';

install_with_cache_healing that throws a TaskError on failure instead of returning the result — the shape every task callsite wants. The thrown message names the exact command (including install_args), an optional context clause, and the failure detail.

`pm_cli`

the npm-compatible CLI to run (e.g. config.pm_cli)

type string

`options`

same as install_with_cache_healing, plus an optional context clause appended after the command (e.g. 'after version bump')

type InstallCacheHealingOptions & { context?: string | undefined; }

default {}

returns

Promise<void>

throws

TaskError - when the install fails, even after a cache-heal retry

InstallCacheHealingOptions
#

InstallCacheHealingOptions import type {InstallCacheHealingOptions} from '@fuzdev/gro/npm_install_helpers.js';

Options for install_with_cache_healing.

`cwd?`

working directory for the install; defaults to the current directory

type string

`env?`

base env; devDependency-pruning vars are stripped via sanitize_install_env

type ProcessEnv

`log?`

logger for cache-heal progress

type Logger

`run?`

injectable command runner for tests; defaults to a live-teeing spawn

type (command: string, args: readonly string[], options?: { cwd?: string | undefined; env?: ProcessEnv | undefined; } | undefined): Promise<NpmCommandResult>

`command`

type string

`args`

type readonly string[]

`options?`

type { cwd?: string | undefined; env?: ProcessEnv | undefined; }

optional

returns Promise<NpmCommandResult>

`install_args?`

Extra args appended after install, e.g. package specs and flags for gro upgrade (['foo@latest', '--force']) or a single dep for gro changeset (['-D', '@changesets/changelog-git']). The same args are reused on the post-cache-clean retry.

type readonly string[]

invalidate
#

(resource: string | URL | ((url: URL) => boolean), keepState?: boolean | undefined) => Promise<void> import {invalidate} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

invalidateAll
#

invoke_task.ts view source

() => Promise<void> import {invalidateAll} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

invoke_task
#

(task_name: RawInputPath, args: Args | undefined, config: GroConfig, initial_filer?: Filer | undefined, initial_timings?: Timings | null | undefined, parent_log?: Logger | undefined): Promise<...>

import {invoke_task} from '@fuzdev/gro/invoke_task.js';

Invokes Gro tasks by name using the filesystem as the source.

When a task is invoked, Gro first searches for tasks in the current working directory. and falls back to searching Gro's directory, if the two are different. See input_path.ts for info about what "task_name" can refer to. If it matches a directory, all of the tasks within it are logged, both in the current working directory and Gro.

This code is particularly hairy because we're accepting a wide range of user input and trying to do the right thing. Precise error messages are especially difficult and there are some subtle differences in the complex logical branches. The comments describe each condition.

`task_name`

the name of the task to invoke

type RawInputPath

`args`

the CLI args to pass to the task

type Args | undefined

`config`

the Gro configuration

type GroConfig

`initial_filer?`

type Filer

optional

`initial_timings?`

the timings to use for the top-level task, null for composed tasks

type Timings | null

optional

`parent_log?`

type Logger

optional

returns

Promise<void>

InvokeTask
#

InvokeTask import type {InvokeTask} from '@fuzdev/gro/task.js';

Invokes a task by name with Gro's task resolution, so local overrides of builtins apply.

Names are checked against TaskRegistry and args against the named task's Args schema input. A name widened to string (dynamic, a path, or a directory) opts out with loose Args.

`(call)`

type <TName extends string>(task_name: InvokeTaskName<TName>, ...rest: InvokeTaskRest<TName>): Promise<void>

`task_name`

type InvokeTaskName<TName>

`rest`

type InvokeTaskRest<TName>

returns Promise<void>

InvokeTaskArgs
#

InvokeTaskArgs<TName>

type TName extends TaskName ? TaskArgsInput<TName> : Args

import type {InvokeTaskArgs} from '@fuzdev/gro/task.js';

generics

InvokeTaskArgs<TName extends string>

`TName`

constraint string

InvokeTaskName
#

InvokeTaskName<TName>

type string extends TName ? TName : TName extends TaskName ? TName : TaskName

import type {InvokeTaskName} from '@fuzdev/gro/task.js';

A literal name must be in TaskRegistry, a widened string passes through.

generics

InvokeTaskName<TName extends string>

`TName`

constraint string

InvokeTaskRest
#

InvokeTaskRest<TName>

type {} extends InvokeTaskArgs<TName> ? [args?: InvokeTaskArgs<TName> | undefined, config?: GroConfig | undefined] : [args: InvokeTaskArgs<TName>, config?: GroConfig | undefined]

import type {InvokeTaskRest} from '@fuzdev/gro/task.js';

Makes args required when the task's Args has required fields.

generics

InvokeTaskRest<TName extends string>

`TName`

constraint string

is_build_cache_valid
#

(config: GroConfig, log: Logger, git_commit?: string | null | undefined): Promise<boolean> import {is_build_cache_valid} from '@fuzdev/gro/build_cache.js';

Main function to check if the build cache is valid. Returns true if the cached build can be used, false if a fresh build is needed.

`config`

Gro config

type GroConfig

`log`

Logger

type Logger

`git_commit?`

optional pre-computed git commit hash (optimization)

type string | null

optional

returns

Promise<boolean>

is_etarget_error
#

(message: string, stderr: string): boolean import {is_etarget_error} from '@fuzdev/gro/npm_install_helpers.js';

Checks if an npm install failure is caused by stale cache (ETARGET).

Detects the several shapes npm uses for "the requested version isn't there": code ETARGET, ETARGET, notarget, and No matching version found.

`message`

the short outcome string (e.g. code 1)

type string

`stderr`

the captured stderr of the failed command

type string

returns

boolean

true when the failure looks like an ETARGET-class staleness error

is_external_module
#

module.ts view source

(module_name: string): boolean import {is_external_module} from '@fuzdev/gro/module.js';

`module_name`

type string

returns

boolean

is_gen_path
#

(path: string): boolean import {is_gen_path} from '@fuzdev/gro/gen.js';

`path`

type string

returns

boolean

is_gro_id
#

(id: PathId): boolean import {is_gro_id} from '@fuzdev/gro/paths.js';

`id`

type PathId

returns

boolean

is_task_path
#

(path: string): boolean import {is_task_path} from '@fuzdev/gro/task.js';

`path`

type string

returns

boolean

IS_THIS_GRO
#

boolean import {IS_THIS_GRO} from '@fuzdev/gro/paths.js';

JS_CLI_DEFAULT
#

"node" import {JS_CLI_DEFAULT} from '@fuzdev/gro/constants.js';

JS_MATCHER
#

RegExp import {JS_MATCHER} from '@fuzdev/gro/constants.js';

JSON_MATCHER
#

RegExp import {JSON_MATCHER} from '@fuzdev/gro/constants.js';

LIB_DIR
#

string import {LIB_DIR} from '@fuzdev/gro/constants.js';

LIB_DIRNAME
#

"lib" import {LIB_DIRNAME} from '@fuzdev/gro/constants.js';

The library directory - SvelteKit has no files.lib option, so it's always here. Lives here rather than in ./paths.ts because it's a constant that reads no config.

LIB_PATH
#

string import {LIB_PATH} from '@fuzdev/gro/constants.js';

LIBRARY_CACHE_FILENAME
#

"library.json" import {LIBRARY_CACHE_FILENAME} from '@fuzdev/gro/library_load.js';

Cache filename inside a repo's .gro directory for library_load_from_repo.

library_cache_key
#

(repo_dir: string): Promise<string | null> import {library_cache_key} from '@fuzdev/gro/library_load.js';

Computes the cache key for a repo at repo_dir: the git HEAD commit hash.

Returns null (uncacheable — analysis still runs, caching is skipped) when the dir is not a git repo OR when the working tree is dirty. A dirty tree is deliberately uncacheable: the commit hash doesn't capture uncommitted edits, so a single -dirty key would serve a stale analysis across successive edits. Skipping the cache while dirty guarantees fresh metadata; clean commits cache.

`repo_dir`

type string

returns

Promise<string | null>

library_cache_read
#

(cache_path: string, key: string, log?: Logger | undefined): Promise<LibraryLoadResult | null> import {library_cache_read} from '@fuzdev/gro/library_load.js';

Reads and validates the .gro/library.json cache at cache_path.

Returns the cached {library_json, package_json} only when the file exists, its stored hash matches key, and its version and svelte_docinfo_version stamps match the current LIBRARY_CACHE_VERSION and SVELTE_DOCINFO_VERSION. Returns null on every miss - absent, stale (different hash or stamps), or unreadable/corrupt - signalling the caller to re-analyze.

`cache_path`

absolute path to the cache file

type string

`key`

the expected cache key (a clean git commit hash)

type string

`log?`

type Logger

optional

returns

Promise<LibraryLoadResult | null>

the cached result, or null on any miss

LIBRARY_CACHE_VERSION
#

2 import {LIBRARY_CACHE_VERSION} from '@fuzdev/gro/library_load.js';

Format version for the .gro/library.json cache. The cache key is the git commit hash, which does NOT change when the cached *shape* changes — so bump this whenever LibraryCache's shape changes (e.g. the LibraryJson / PkgJson split, then slimming LibraryJson to the raw pkg_json/source_json pair) to self-invalidate stale caches across the ecosystem rather than serve old-shaped data at an unchanged commit. Upstream analyzer changes need no bump: each record also stamps SVELTE_DOCINFO_VERSION and self-invalidates when the installed svelte-docinfo moves.

library_cache_write
#

(cache_path: string, key: string, result: LibraryLoadResult, log?: Logger | undefined): Promise<void> import {library_cache_write} from '@fuzdev/gro/library_load.js';

Writes result to the .gro/library.json cache at cache_path, keyed by key and stamped with the current LIBRARY_CACHE_VERSION and SVELTE_DOCINFO_VERSION, creating the parent directory as needed.

Best effort: caching is optional, so write failures are logged as a warning and swallowed rather than thrown.

`cache_path`

absolute path to the cache file

type string

`key`

the cache key to store (a clean git commit hash)

type string

`result`

the {library_json, package_json} to cache

type LibraryLoadResult

`log?`

type Logger

optional

returns

Promise<void>

library_load_from_repo
#

(repo_dir: string, options?: LibraryLoadOptions | undefined): Promise<LibraryLoadResult> import {library_load_from_repo} from '@fuzdev/gro/library_load.js';

Loads a repo's library metadata via svelte-docinfo, with a .gro cache keyed by git hash.

Analyzes repo_dir with analyzeFromFiles and combines the result with the repo's package.json into a LibraryJson, returned alongside the full package.json. Results are cached at <repo_dir>/.gro/library.json keyed by the current git HEAD, so repeated loads at the same commit skip the (potentially slow) analysis. A dirty working tree (or a non-git dir) is uncacheable, so analysis re-runs on every load until the changes are committed - see library_cache_key.

Refuses to analyze a repo whose tsconfig.json extends $app/tsconfig but that hasn't been synced (see sveltekit_tsconfig_is_unsynced): its analysis would read external types as any. The check runs only on a cache miss - a cache hit is served as written. svelte-docinfo logs to a child of log labelled with the repo dir's name: its diagnostics as warnings and errors, its progress at debug level.

`repo_dir`

absolute path to the repo to analyze

type string

`options?`

type LibraryLoadOptions

optional

returns

Promise<LibraryLoadResult>

the repo's LibraryLoadResult (library_json + full package_json)

throws

Error - if the repo extends `$app/tsconfig` without `node_modules/$app/tsconfig.json` - install its dependencies if needed, then run `gro sync` in it

LibraryCache
#

LibraryCache import type {LibraryCache} from '@fuzdev/gro/library_load.js';

On-disk shape of the .gro/library.json cache file. The hash is the git-based cache key the result was computed at; version is the LIBRARY_CACHE_VERSION it was written under; svelte_docinfo_version is the SVELTE_DOCINFO_VERSION that analyzed it.

inheritance

extends: LibraryLoadResult

`hash`

type string

`version`

type number

`svelte_docinfo_version`

type string

LibraryLoadOptions
#

LibraryLoadOptions import type {LibraryLoadOptions} from '@fuzdev/gro/library_load.js';

`log?`

type Logger

`cache?`

Set to false to bypass the .gro cache (always re-analyze, but still write the result).

type boolean

LibraryLoadResult
#

LibraryLoadResult import type {LibraryLoadResult} from '@fuzdev/gro/library_load.js';

Result of loading a repo's library metadata: the curated LibraryJson (carrying the publish-safe pkg_json) plus the repo's full package.json.

The full package_json is kept alongside — not folded into LibraryJson — because tooling like fuz_gitops needs dependencies/devDependencies, which the curated LibraryJson.pkg_json deliberately omits.

`library_json`

type LibraryJson

`package_json`

type PackageJson

load_build_cache_metadata
#

(): Promise<{ version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; } | null>

import {load_build_cache_metadata} from '@fuzdev/gro/build_cache.js';

Loads build cache metadata from .gro/ directory. Invalid or corrupted cache files are automatically deleted.

returns

Promise<BuildCacheMetadata | null>

load_default_svelte_config
#

(): Promise<ParsedSvelteConfig> import {load_default_svelte_config} from '@fuzdev/gro/svelte_config.js';

The parsed Svelte config for the project in the cwd, memoized.

Reading it costs a full Vite config resolution, which runs every Vite plugin's config hooks, so callers pull it in on demand instead of paying for it on every Gro invocation.

returns

Promise<ParsedSvelteConfig>

load_env
#

(dev: boolean, env_dir?: string | undefined, env_files?: string[], ambient_env?: Record<string, string | undefined>): Record<string, string>

import {load_env} from '@fuzdev/gro/env.js';

Loads every env var from the env files plus the ambient env, later sources winning, so the ambient env overrides the files.

`dev`

picks the development or production mode files for the default env_files

type boolean

`env_dir?`

the directory the env files are resolved against, defaults to the cwd

type string

optional

`env_files`

the env files to load, in order, defaults to the same files as Vite

type string[]

default to_default_env_files(dev)

`ambient_env`

the env merged in last

type Record<string, string | undefined>

default process.env

returns

Record<string, string>

all loaded vars, unfiltered - resolve_env_vars picks out the declared ones

load_from_env
#

(key: string, paths?: string[]): string | undefined import {load_from_env} from '@fuzdev/gro/env.js';

Loads a single env value without merging it into process.env. By default searches process.env, then a local .env if one exists, then ../.env if it exists. Empty strings are semantically the same as undefined for more ergonomic fallbacks.

`key`

type string

`paths`

type string[]

default ['.env', '../.env']

returns

string | undefined

load_genfiles
#

(found_genfiles: FoundGenfiles, timings?: Timings | undefined): Promise<LoadGenfilesResult> import {load_genfiles} from '@fuzdev/gro/gen.js';

`found_genfiles`

type FoundGenfiles

`timings?`

type Timings

optional

returns

Promise<LoadGenfilesResult>

load_gro_config
#

(dir?: string): Promise<GroConfig> import {load_gro_config} from '@fuzdev/gro/gro_config.js';

`dir`

type string

default paths.root

returns

Promise<GroConfig>

load_module
#

<TModule extends Record<string, any>>(id: PathId, validate?: ((mod: Record<string, any>) => mod is TModule) | undefined, bust_cache?: boolean | undefined): Promise<LoadModuleResult<TModule>>

import {load_module} from '@fuzdev/gro/modules.js';

`id`

type PathId

`validate?`

type (mod: Record<string, any>) => mod is TModule

optional

`bust_cache?`

type boolean

optional

returns

Promise<LoadModuleResult>

generics

load_module<TModule extends Record<string, any>>

`TModule`

constraint Record<string, any>

load_modules
#

<TModule extends Record<string, any>, TModuleMeta extends ModuleMeta<TModule>>(resolved_input_files: ResolvedInputFile[], validate: (mod: any) => mod is TModule, map_module_meta: (resolved_input_file: ResolvedInputFile, mod: TModule) => TModuleMeta, timings?: Timings | undefined): Promise<...>

import {load_modules} from '@fuzdev/gro/modules.js';

`resolved_input_files`

type ResolvedInputFile[]

`validate`

type (mod: any) => mod is TModule

`map_module_meta`

type (resolved_input_file: ResolvedInputFile, mod: TModule) => TModuleMeta

`timings?`

type Timings

optional

returns

Promise<LoadModulesResult>

generics

load_modules<TModule extends Record<string, any>, TModuleMeta extends ModuleMeta<TModule>>

`TModule`

constraint Record<string, any>

`TModuleMeta`

constraint ModuleMeta<TModule>

load_svelte_config
#

(): Promise<Config | null> import {load_svelte_config} from '@fuzdev/gro/svelte_config.js';

Loads the Svelte config of the project in the cwd by resolving its Vite config.

returns

Promise<Config | null>

null if the project has no Vite config, or one that configures no Svelte plugin

throws

if - the project has a Vite config but Vite isn't installed, or if it fails to resolve

load_sveltekit_env_declarations
#

(entry_id: string, fresh?: boolean): Promise<EnvVarDeclarations> import {load_sveltekit_env_declarations} from '@fuzdev/gro/sveltekit_shim_app_env_vars.js';

Imports the variables declared in a project's env entry module. The shims render static exports, so the declared names are needed before rendering - the values aren't, those resolve when the rendered module runs.

`entry_id`

the env entry module

type string

`fresh`

re-import the entry when it has changed on disk, for long-lived processes that rebuild, at the cost of a new module instance per change

type boolean

default false

returns

Promise<EnvVarDeclarations>

throws

if - the entry doesn't export a `variables` object, or declares an invalid name

load_tasks
#

(found_tasks: FoundTasks, root_path?: PathId): Promise<LoadTasksResult> import {load_tasks} from '@fuzdev/gro/task.js';

`found_tasks`

type FoundTasks

`root_path`

type PathId

default process.cwd()

returns

Promise<LoadTasksResult>

LoadedGenfiles
#

LoadedGenfiles import type {LoadedGenfiles} from '@fuzdev/gro/gen.js';

`modules`

type GenfileModuleMeta[]

`found_genfiles`

type FoundGenfiles

LoadedTasks
#

LoadedTasks import type {LoadedTasks} from '@fuzdev/gro/task.js';

`modules`

type TaskModuleMeta[]

`found_tasks`

type FoundTasks

LoadGenfilesFailure
#

LoadGenfilesFailure

type LoadModulesFailure<GenfileModuleMeta>

import type {LoadGenfilesFailure} from '@fuzdev/gro/gen.js';

`type`

type "load_module_failures"

`load_module_failures`

type LoadModuleFailure[]

`reasons`

type string[]

`modules`

type GenfileModuleMeta[]

LoadGenfilesResult
#

LoadGenfilesResult

type ({ ok: true; } & { value: LoadedGenfiles; }) | ({ ok: false; } & LoadGenfilesFailure)

import type {LoadGenfilesResult} from '@fuzdev/gro/gen.js';

LoadModuleFailure
#

LoadModuleFailure

type { ok: false; type: "failed_import"; id: PathId; error: Error; } | { ok: false; type: "failed_validation"; id: PathId; mod: Record<string, any>; validation: string; }

import type {LoadModuleFailure} from '@fuzdev/gro/modules.js';

LoadModuleResult
#

LoadModuleResult<TModule>

type ({ ok: true; } & { id: PathId; mod: TModule; }) | (({ ok: false; } & { ok: false; type: "failed_import"; id: PathId; error: Error; }) | ({ ok: false; } & { ok: false; type: "failed_validation"; id: PathId; mod: Record<string, any>; validation: string; }))

import type {LoadModuleResult} from '@fuzdev/gro/modules.js';

generics

LoadModuleResult<TModule>

`TModule`

LoadModulesFailure
#

LoadModulesFailure<TModuleMeta> import type {LoadModulesFailure} from '@fuzdev/gro/modules.js';

generics

LoadModulesFailure<TModuleMeta extends ModuleMeta>

`TModuleMeta`

constraint ModuleMeta

`type`

type "load_module_failures"

`load_module_failures`

type LoadModuleFailure[]

`reasons`

type string[]

`modules`

type TModuleMeta[]

LoadModulesResult
#

LoadModulesResult<TModuleMeta>

type ({ ok: true; } & { modules: TModuleMeta[]; }) | ({ ok: false; } & LoadModulesFailure<TModuleMeta>)

import type {LoadModulesResult} from '@fuzdev/gro/modules.js';

generics

LoadModulesResult<TModuleMeta extends ModuleMeta>

`TModuleMeta`

constraint ModuleMeta

LoadTasksFailure
#

LoadTasksFailure

type LoadModulesFailure<TaskModuleMeta>

import type {LoadTasksFailure} from '@fuzdev/gro/task.js';

`type`

type "load_module_failures"

`load_module_failures`

type LoadModuleFailure[]

`reasons`

type string[]

`modules`

type TaskModuleMeta[]

LoadTasksResult
#

LoadTasksResult

type ({ ok: true; } & { value: LoadedTasks; }) | ({ ok: false; } & LoadTasksFailure)

import type {LoadTasksResult} from '@fuzdev/gro/task.js';

LOCKFILE_FILENAME
#

task_logging.ts view source

"package-lock.json" import {LOCKFILE_FILENAME} from '@fuzdev/gro/constants.js';

log_error_reasons
#

(log: Logger, reasons: string[]): void import {log_error_reasons} from '@fuzdev/gro/task_logging.js';

`log`

type Logger

`reasons`

type string[]

returns

void

log_task_help
#

task_logging.ts view source

(log: Logger, meta: TaskModuleMeta): void import {log_task_help} from '@fuzdev/gro/task_logging.js';

`log`

type Logger

`meta`

type TaskModuleMeta

returns

void

log_tasks
#

task_logging.ts view source

(log: Logger, loaded_tasks: LoadedTasks, log_intro?: boolean): void import {log_tasks} from '@fuzdev/gro/task_logging.js';

`log`

type Logger

`loaded_tasks`

type LoadedTasks

`log_intro`

type boolean

default true

returns

void

map_child_process_output
#

child_process_logging.ts view source

(child_process: ChildProcess, transform: (data: string) => string): void import {map_child_process_output} from '@fuzdev/gro/child_process_logging.js';

Maps child process output through a transform function.

`child_process`

type ChildProcess

`transform`

type (data: string) => string

returns

void

match
#

sveltekit_shim_app_paths.ts view source

(url: string | URL): Promise<{ id: "/"; params: Record<string, never>; } | { id: "/about"; params: Record<string, never>; } | { id: "/docs"; params: Record<string, never>; } | ... 5 more ... | null>

import {match} from '@fuzdev/gro/sveltekit_shim_app_paths.js';

`url`

type string | URL

returns

Promise<{ id: "/"; params: Record<string, never>; } | { id: "/about"; params: Record<string, never>; } | { id: "/docs"; params: Record<string, never>; } | { id: "/docs/api"; params: Record<string, never>; } | { id: "/docs/api/[...module_path]"; params: { module_path: string; }; } | { id: "/docs/introduction"; params: Record<string, never>; } | { id: "/docs/library"; params: Record<string, never>; } | { id: "/history"; params: Record<string, never>; } | null>

MODULE_PATH_LIB_PREFIX
#

module.ts view source

"#lib/" import {MODULE_PATH_LIB_PREFIX} from '@fuzdev/gro/module.js';

MODULE_PATH_SRC_PREFIX
#

module.ts view source

string import {MODULE_PATH_SRC_PREFIX} from '@fuzdev/gro/module.js';

ModuleMeta
#

sveltekit_shim_app_state.ts view source

ModuleMeta<TModule> import type {ModuleMeta} from '@fuzdev/gro/modules.js';

generics

ModuleMeta<TModule extends Record<string, any> = Record<string, any>>

`TModule`

constraint Record<string, any>

default Record<string, any>

`id`

type PathId

`mod`

type TModule

navigating
#

Navigation | { from: null; to: null; type: null; willUnload: null; delta: null; complete: null; }

type Navigation | { from: null; to: null; type: null; willUnload: null; delta: null; complete: null; }

import {navigating} from '@fuzdev/gro/sveltekit_shim_app_state.js';

NODE_MODULES_DIRNAME
#

"node_modules" import {NODE_MODULES_DIRNAME} from '@fuzdev/gro/constants.js';

normalize_gen_config
#

(gen: Gen): GenConfig import {normalize_gen_config} from '@fuzdev/gro/gen.js';

`gen`

type Gen

returns

GenConfig

NpmCommandResult
#

NpmCommandResult import type {NpmCommandResult} from '@fuzdev/gro/npm_install_helpers.js';

Result of one install or cache-clean attempt.

`ok`

type boolean

`stderr`

captured stderr; the default runner also tees this live to the terminal

type string

`detail`

short human-readable outcome, e.g. code 1 or error: spawn ENOENT

type string

NpmCommandRunner
#

NpmCommandRunner import type {NpmCommandRunner} from '@fuzdev/gro/npm_install_helpers.js';

Runs an npm-compatible command and reports ok plus captured stderr. Injected by install_with_cache_healing for testing; the default implementation spawns a real subprocess.

`(call)`

type (command: string, args: readonly string[], options?: { cwd?: string | undefined; env?: ProcessEnv | undefined; } | undefined): Promise<NpmCommandResult>

`command`

type string

`args`

type readonly string[]

`options?`

type { cwd?: string | undefined; env?: ProcessEnv | undefined; }

optional

returns Promise<NpmCommandResult>

OnFilerChange
#

OnFilerChange import type {OnFilerChange} from '@fuzdev/gro/filer.js';

`(call)`

type (change: WatcherChange, disknode: Disknode): void

`change`

type WatcherChange

`disknode`

type Disknode

returns void

onNavigate
#

(callback: (navigation: (NavigationGoto & { type: "goto" | "form" | "link" | "popstate"; willUnload: false; }) | (NavigationFormSubmit & { type: "goto" | "form" | "link" | "popstate"; willUnload: false; }) | (NavigationPopState & { ...; }) | (NavigationLink & { ...; })) => MaybePromise<...>) => void

import {onNavigate} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

Outpaths
#

Outpaths import type {Outpaths} from '@fuzdev/gro/gro_plugin_server.js';

`outdir`

type string

default '.gro/dev' or 'dist_server'

`outbase`

type string

default `src/lib`

`outname`

type string

default 'server.js'

PACKAGE_JSON_EMPTY
#

{ [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; logo?: string | undefined; ... 23 more ...; exports?: string | ... 2 more ... | undefined; }

type PackageJson

import {PACKAGE_JSON_EMPTY} from '@fuzdev/gro/package_json.js';

package_json_extract_dependencies
#

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }): PackageJsonDep[]

import {package_json_extract_dependencies} from '@fuzdev/gro/package_json.js';

`package_json`

type PackageJson

returns

PackageJsonDep[]

PACKAGE_JSON_FILENAME
#

"package.json" import {PACKAGE_JSON_FILENAME} from '@fuzdev/gro/constants.js';

package_json_has_dependency
#

(dep_name: string, package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }, include_peer?: boolean): boolean

import {package_json_has_dependency} from '@fuzdev/gro/package_json.js';

`dep_name`

type string

`package_json`

type PackageJson

`include_peer`

whether a peerDependencies entry counts. Pass false when detecting what a project *is*, since a peer dep declares what it works alongside - a plugin package peered on @sveltejs/kit isn't itself a SvelteKit app.

type boolean

default true

returns

boolean

package_json_load
#

(dir?: string, cache?: Record<string, { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; ... 25 more ...; exports?: string | ... 2 more ... | undefined; }> | undefined, parse?: boolean, log?: Logger | undefined): Promise<...>

import {package_json_load} from '@fuzdev/gro/package_json.js';

`dir`

type string

default IS_THIS_GRO ? gro_paths.root : paths.root

`cache?`

type Record<string, PackageJson>

optional

`parse`

type boolean

default true

`log?`

type Logger

optional

returns

Promise<PackageJson>

package_json_load_for_gro
#

(): Promise<{ [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }>

import {package_json_load_for_gro} from '@fuzdev/gro/package_json.js';

returns

Promise<PackageJson>

package_json_parse_repo_url
#

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }): { ...; } | undefined

import {package_json_parse_repo_url} from '@fuzdev/gro/package_json.js';

`package_json`

type PackageJson

returns

{ owner: string; repo: string; } | undefined

package_json_serialize
#

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }): string

import {package_json_serialize} from '@fuzdev/gro/package_json.js';

`package_json`

type PackageJson

returns

string

package_json_sync
#

(map_package_json: PackageJsonMapper, log: Logger, write?: boolean, dir?: string, exports_dir?: string | undefined): Promise<{ package_json: { [x: string]: unknown; name: string; ... 29 more ...; exports?: string | ... 2 more ... | undefined; } | null; changed: boolean; }>

import {package_json_sync} from '@fuzdev/gro/package_json.js';

`map_package_json`

type PackageJsonMapper

`log`

type Logger

`write`

type boolean

default true

`dir`

type string

default paths.root

`exports_dir?`

the directory whose files become the exports, defaults to LIB_PATH

type string

optional

returns

Promise<{ package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; } | null; changed: boolean; }>

package_json_to_exports
#

(paths: string[]): string | Record<string, unknown> | null import {package_json_to_exports} from '@fuzdev/gro/package_json.js';

`paths`

type string[]

returns

PackageJsonExports

package_json_update
#

(update: (package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }) => { ...; } | ... 1 more ... | null, dir?: string, write?: boolean): Promise<...>

import {package_json_update} from '@fuzdev/gro/package_json.js';

Updates package.json. Writes to the filesystem only when contents change.

`update`

type

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }) => { ...; } | ... 1 more ... | null

`dir`

type string

default paths.root

`write`

type boolean

default true

returns

package_json_write
#

(serialized_package_json: string): Promise<void> import {package_json_write} from '@fuzdev/gro/package_json.js';

`serialized_package_json`

type string

returns

Promise<void>

PackageJsonDep
#

PackageJsonDep import type {PackageJsonDep} from '@fuzdev/gro/package_json.js';

`name`

type string

`version`

type string

PackageJsonMapper
#

sveltekit_shim_app_state.ts view source

PackageJsonMapper import type {PackageJsonMapper} from '@fuzdev/gro/package_json.js';

`(call)`

type (package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }): { ...; } | ... 1 more ... | null

`package_json`

type PackageJson

returns PackageJson | Promise<PackageJson | null> | null

page
#

Page<{ module_path?: string | undefined; }, "/" | "/about" | "/docs" | "/docs/api" | "/docs/api/[...module_path]" | "/docs/introduction" | "/docs/library" | "/history" | null>

type Page<{ module_path?: string | undefined; }, "/" | "/about" | "/docs" | "/docs/api" | "/docs/api/[...module_path]" | "/docs/introduction" | "/docs/library" | "/history" | null>

import {page} from '@fuzdev/gro/sveltekit_shim_app_state.js';

parse_imports
#

parse_imports.ts view source

(id: PathId, contents: string, ignore_types?: boolean): ImportSpecifier[] import {parse_imports} from '@fuzdev/gro/parse_imports.js';

`id`

type PathId

`contents`

type string

`ignore_types`

type boolean

default true

returns

ImportSpecifier[]

parse_svelte_config
#

(options?: ParseSvelteConfigOptions): Promise<ParsedSvelteConfig> import {parse_svelte_config} from '@fuzdev/gro/svelte_config.js';

Returns Gro-relevant properties of a SvelteKit config as a convenience wrapper around load_svelte_config.

`options`

type ParseSvelteConfigOptions

default EMPTY_OBJECT

returns

Promise<ParsedSvelteConfig>

ParsedSvelteConfig
#

ParsedSvelteConfig import type {ParsedSvelteConfig} from '@fuzdev/gro/svelte_config.js';

A subset of SvelteKit's config in a form that Gro uses. Flattens things out to keep them simple and easy to pass around, and doesn't deal with most properties, but includes the full svelte_config. The base and assets in particular are renamed for clarity with Gro's internal systems, so these properties become first-class vocabulary inside Gro.

`svelte_config`

type Config | null

`base_url`

type "" | `/${string}` | undefined

`assets_url`

type "" | `http://${string}` | `https://${string}` | undefined

`assets_path`

Same as the SvelteKit files.assets, relative to the project directory.

type string

`routes_path`

Same as the SvelteKit files.routes, relative to the project directory.

type string

`src_path`

Same as the SvelteKit files.src, relative to the project directory. The env declarations entry env.ts lives here.

type string

`env_dir`

type string | undefined

`version_name`

Same as the SvelteKit version.name, exposed as version by the $app/env shim.

type string | undefined

`svelte_compile_options`

type CompileOptions

`svelte_compile_module_options`

type ModuleCompileOptions

`svelte_preprocessors`

type PreprocessorGroup | PreprocessorGroup[] | undefined

ParseSvelteConfigOptions
#

ParseSvelteConfigOptions import type {ParseSvelteConfigOptions} from '@fuzdev/gro/svelte_config.js';

`svelte_config?`

An already-loaded config to parse instead of resolving the project's Vite config.

type Config

path_id_to_base_path
#

(path_id: PathId, p?: Paths): string import {path_id_to_base_path} from '@fuzdev/gro/paths.js';

`path_id`

type PathId

`p`

type Paths

default infer_paths(path_id)

returns

string

paths
#

Paths import {paths} from '@fuzdev/gro/paths.js';

Paths for the user repo.

Paths
#

Paths import type {Paths} from '@fuzdev/gro/paths.js';

`root`

type string

`source`

type string

`lib`

type string

`build`

type string

`build_dev`

type string

`config`

type string

Plugin
#

Plugin<TPluginContext> import type {Plugin} from '@fuzdev/gro/plugin.js';

Gro Plugins enable custom behavior during gro dev and gro build. In contrast, Adapters use the results of gro build to produce final artifacts.

generics

Plugin<TPluginContext extends PluginContext = PluginContext>

`TPluginContext`

constraint PluginContext

default PluginContext

`name`

type string

`setup?`

type (ctx: TPluginContext): void | Promise<void>

`ctx`

type TPluginContext

returns void | Promise<void>

`adapt?`

type (ctx: TPluginContext): void | Promise<void>

`ctx`

type TPluginContext

returns void | Promise<void>

`teardown?`

type (ctx: TPluginContext): void | Promise<void>

`ctx`

type TPluginContext

returns void | Promise<void>

plugin_replace
#

(plugins: Plugin<PluginContext<object>>[], new_plugin: Plugin<PluginContext<object>>, name?: string): Plugin<PluginContext<object>>[]

import {plugin_replace} from '@fuzdev/gro/plugin.js';

Replaces a plugin by name in plugins without mutating the param. Throws if the plugin name cannot be found.

`plugins`

accepts the same types as the return value of PluginsCreateConfig

type Plugin<PluginContext<object>>[]

`new_plugin`

type Plugin<PluginContext<object>>

`name`

type string

default new_plugin.name

returns

Plugin<PluginContext<object>>[]

plugins with new_plugin at the index of the plugin with name

PluginContext
#

PluginContext<TArgs> import type {PluginContext} from '@fuzdev/gro/plugin.js';

generics

PluginContext<TArgs = object>

`TArgs`

default object

inheritance

extends: TaskContext<TArgs>

`dev`

type boolean

`watch`

type boolean

Plugins
#

import {Plugins} from '@fuzdev/gro/plugin.js';

See Plugins.create for a usage example.

generics

Plugins<TPluginContext extends PluginContext>

`TPluginContext`

constraint PluginContext

`ctx`

type TPluginContext

readonly

`instances`

type Plugin<TPluginContext>[]

readonly

`constructor`

type new <TPluginContext extends PluginContext>(ctx: TPluginContext, instances: Plugin<PluginContext<object>>[]): Plugins<TPluginContext>

`ctx`

type TPluginContext

`instances`

type Plugin<PluginContext<object>>[]

`create`

type <TPluginContext extends PluginContext>(ctx: TPluginContext): Promise<Plugins<TPluginContext>>

static

`ctx`

type TPluginContext

returns Promise<Plugins<TPluginContext>>

`setup`

type (): Promise<void>

returns Promise<void>

`adapt`

type (): Promise<void>

returns Promise<void>

`teardown`

type (): Promise<void>

returns Promise<void>

PluginsCreateConfig
#

PluginsCreateConfig<TPluginContext> import type {PluginsCreateConfig} from '@fuzdev/gro/plugin.js';

generics

PluginsCreateConfig<TPluginContext extends PluginContext = PluginContext>

`TPluginContext`

constraint PluginContext

default PluginContext

`(call)`

type (ctx: TPluginContext): Plugin<TPluginContext>[] | Promise<Plugin<TPluginContext>[]>

`ctx`

type TPluginContext

returns Plugin<TPluginContext>[] | Promise<Plugin<TPluginContext>[]>

PM_CLI_DEFAULT
#

"npm" import {PM_CLI_DEFAULT} from '@fuzdev/gro/constants.js';

PossiblePath
#

PossiblePath import type {PossiblePath} from '@fuzdev/gro/input_path.js';

`id`

type PathId

`input_path`

type InputPath

`root_dir`

type PathId

preloadCode
#

(id: "/" | "/about" | "/docs" | "/docs/api" | "/docs/api/[...module_path]" | "/docs/introduction" | "/docs/library" | "/history") => Promise<void>

import {preloadCode} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

preloadData
#

esbuild_helpers.ts view source

(href: string) => Promise<({ type: "loaded"; data: Record<string, any>; } | { type: "redirect"; location: string; } | { type: "error"; error: Error; }) & { status: number; }>

import {preloadData} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

print_build_result
#

(log: Logger, build_result: BuildResult<BuildOptions>): void import {print_build_result} from '@fuzdev/gro/esbuild_helpers.js';

`log`

type Logger

`build_result`

type BuildResult<BuildOptions>

returns

void

print_command_args
#

(serialized_args: string[]): string import {print_command_args} from '@fuzdev/gro/args.js';

`serialized_args`

type string[]

returns

string

print_path
#

(path: string, p?: Paths): string import {print_path} from '@fuzdev/gro/paths.js';

`path`

type string

`p`

type Paths

default infer_paths(path)

returns

string

ProjectTasks
#

ProjectTasks import type {ProjectTasks} from '@fuzdev/gro/task_registry.js';

The project's own tasks by name, empty until augmented by a generated file. Create a genfile like src/gro_tasks.gen.ts exporting gen_task_registry as gen to type the project's task names and args for invoke_task.

pushState
#

(url: string | URL, state: PageState) => Promise<void> import {pushState} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

RawGenFile
#

RawGenFile import type {RawGenFile} from '@fuzdev/gro/gen.js';

`content`

type string

`filename?`

type string

`format?`

type boolean

RawGenResult
#

RawGenResult

type string | RawGenFile | RawGenResult[] | null

import type {RawGenResult} from '@fuzdev/gro/gen.js';

RawGroConfig
#

RawGroConfig import type {RawGroConfig} from '@fuzdev/gro/gro_config.js';

The relaxed variant of GroConfig that users can provide via gro.config.ts. Superset of GroConfig.

`plugins?`

type (ctx: PluginContext<object>): Plugin<PluginContext<object>>[] | Promise<Plugin<PluginContext<object>>[]>

`ctx`

type PluginContext<object>

returns Plugin<PluginContext<object>>[] | Promise<Plugin<PluginContext<object>>[]>

`map_package_json?`

type (PackageJsonMapper) | null

`task_root_dirs?`

type string[]

`search_filters?`

type (PathFilter) | (PathFilter)[] | null

`js_cli?`

type string

`pm_cli?`

type string

`build_cache_config?`

Optional object defining custom build inputs for cache invalidation. This value is hashed during config normalization and used to detect when builds need to be regenerated due to non-source changes.

Use cases:

Environment variables baked into build: {api_url: process.env.PUBLIC_API_URL}
External data files: {data: fs.readFileSync('data.json', 'utf-8')}
Build feature flags: {enable_analytics: true}

Can be a static object or an async function that returns an object.

IMPORTANT: It's safe to include secrets here because they are hashed and deleted during config normalization. The raw value is never logged or persisted.

type Record<string, unknown> | (() => Record<string, unknown> | Promise<Record<string, unknown>>)

`filer_options?`

Options passed to the Filer for file watching and import resolution.

type Partial<FilerOptions> | null

see also

``FilerOptions``

RawInputPath
#

format_directory.ts view source

value + type

RawInputPath

type string & Flavor<"RawInputPath">

import {RawInputPath} from '@fuzdev/gro/input_path.js';

external types

Flavored<z.infer<typeof RawInputPath>, 'RawInputPath'>

read_format_ignore
#

(root: string): Set<string> import {read_format_ignore} from '@fuzdev/gro/format_directory.js';

Reads the root ignore files (.formatignore and .prettierignore) and expands their merged gitignore-style globs to a set of absolute paths the format sweep skips. A pattern with no / matches at any depth (*.md becomes ** /*.md); a pattern with / is anchored to the root. Blank lines and # comments are ignored, and absent files yield an empty set (skip nothing).

`root`

type string

returns

Set<string>

refreshAll
#

() => Promise<void> import {refreshAll} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

render_sveltekit_shim_app_env
#

(dev: boolean, version_name?: string | undefined): string import {render_sveltekit_shim_app_env} from '@fuzdev/gro/sveltekit_shim_app.js';

`dev`

type boolean

`version_name`

type string | undefined

default ''

returns

string

render_sveltekit_shim_app_env_vars
#

({ visibility, variables, entry_specifier, env_module_specifier, dev, env_dir, env_files, ambient_env }: RenderSveltekitShimAppEnvVarsOptions): string

import {render_sveltekit_shim_app_env_vars} from '@fuzdev/gro/sveltekit_shim_app_env_vars.js';

Generates a module shim for SvelteKit's $app/env/public and $app/env/private. Values resolve when the module runs, validated against the declarations, so unlike SvelteKit's build, static vars aren't inlined - a bundled server reads them from its env files and ambient env at startup, and imports the declarations module and Gro's env module at runtime.

`__0`

type RenderSveltekitShimAppEnvVarsOptions

returns

string

render_sveltekit_shim_app_paths
#

(base_url?: "" | `/${string}` | undefined, assets_url?: "" | `http://${string}` | `https://${string}` | undefined): string

import {render_sveltekit_shim_app_paths} from '@fuzdev/gro/sveltekit_shim_app.js';

`base_url`

type "" | `/${string}` | undefined

default ''

`assets_url`

type "" | `http://${string}` | `https://${string}` | undefined

default ''

returns

string

RenderSveltekitShimAppEnvVarsOptions
#

RenderSveltekitShimAppEnvVarsOptions import type {RenderSveltekitShimAppEnvVarsOptions} from '@fuzdev/gro/sveltekit_shim_app_env_vars.js';

`visibility`

type EnvVisibility

`variables`

The declarations from load_sveltekit_env_declarations, null if the project has none.

type EnvVarDeclarations | null

`entry_specifier`

How the rendered module imports the env entry - a file URL for Node, a path for esbuild.

type string | null

`env_module_specifier?`

How the rendered module imports Gro's env module.

type string

default `'@fuzdev/gro/env.js'`

`dev`

type boolean

`env_dir?`

type string

`env_files?`

type string[]

`ambient_env?`

type Record<string, string | undefined>

replace_extension
#

(path: string, new_extension: string): string import {replace_extension} from '@fuzdev/gro/paths.js';

`path`

type string

`new_extension`

type string

returns

string

replaceState
#

sveltekit_shim_app_paths.ts view source

(url: string | URL, state: PageState) => Promise<void> import {replaceState} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

resolve
#

<T extends RouteIdWithSearchOrHash | PathnameWithSearchOrHash>(...args: ResolveArgs<T>): "/" | "/about" | "/docs" | "/docs/api" | "/docs/introduction" | "/docs/library" | ... 9 more ... | `/${string}/history`

import {resolve} from '@fuzdev/gro/sveltekit_shim_app_paths.js';

`args`

type ResolveArgs<T>

returns

ResolvedPathname

resolve_cli
#

(name_or_cli: string | Cli, args: string[] | undefined, cwd: string | URL | undefined, log?: Logger | undefined, options?: SpawnOptions | undefined): Promise<...>

import {resolve_cli} from '@fuzdev/gro/cli.js';

`name_or_cli`

type string | Cli

`args`

type string[]

default []

`cwd`

type string | URL | undefined

`log?`

type Logger

optional

`options?`

type SpawnOptions

optional

returns

Promise<Cli | undefined>

resolve_env_vars
#

gro_helpers.ts view source

(variables: EnvVarDeclarations, visibility: EnvVisibility, env: Record<string, string | undefined>): Record<string, unknown>

import {resolve_env_vars} from '@fuzdev/gro/env.js';

Resolves the declared env vars of one visibility from env, validating each the way SvelteKit does: a var with no schema must be present, and one with a schema gets its Standard Schema result, so validators can transform values and make them optional.

`variables`

the declarations from the project's src/env.ts

type EnvVarDeclarations

`visibility`

which of the declared vars to resolve

type EnvVisibility

`env`

the values to resolve them from, usually from load_env

type Record<string, string | undefined>

returns

Record<string, unknown>

the resolved values keyed by var name

throws

listing - every invalid var, so a misconfigured env fails all at once

resolve_gro_module_path
#

(path?: string): string import {resolve_gro_module_path} from '@fuzdev/gro/gro_helpers.js';

Resolves a path to an internal Gro file. Prefers any local installation of Gro and falls back to the current CLI context.

Uses heuristics to find path, so may fail in some rare corner cases. Currently looks for gro.ts as a sibling to the path arg for detection. If this fails for your usecases, rename gro.ts or open an issue/PR!

Used by the CLI and gro run.

case 1:

We're in a directory that has a local installation of Gro at node_modules/.bin/gro. Use this local version instead of the global.

case 2:

We're running Gro inside the Gro repo itself.

In this case, we use the build directory instead of dist. There's a paradox here for using Gro inside itself - ideally we use the dist directory because that's what's shipped, but the build directory has all of the tests, and loading two instances of its modules causes problems like instanceof checks failing. For now we'll just run from build and see if it causes any problems. There's probably a better design in here somewhere.

case 3:

Fall back to invoking Gro from wherever the CLI is being executed. When using the global CLI, this uses the global Gro installation.

`path`

type string

default ''

returns

string

resolve_input_files
#

(resolved_input_paths: ResolvedInputPath[], search?: (dir: string) => Promise<ResolvedPath[]>): Promise<ResolvedInputFiles>

import {resolve_input_files} from '@fuzdev/gro/input_path.js';

Finds all of the matching files for the given input paths. De-dupes source ids.

`resolved_input_paths`

type ResolvedInputPath[]

`search`

type (dir: string) => Promise<ResolvedPath[]>

default fs_search

returns

Promise<ResolvedInputFiles>

resolve_input_paths
#

resolve_specifier.ts view source

(input_paths: InputPath[], root_dirs: PathId[], extensions: string[]): Promise<ResolvedInputPaths> import {resolve_input_paths} from '@fuzdev/gro/input_path.js';

Gets the path data for each input path, checking the filesystem for the possibilities and stopping at the first existing file or falling back to the first existing directory. If none is found for an input path, it's added to unmapped_input_paths.

`input_paths`

type InputPath[]

`root_dirs`

type PathId[]

`extensions`

type string[]

returns

Promise<ResolvedInputPaths>

resolve_specifier
#

(specifier: string, dir: string): Promise<ResolvedSpecifier> import {resolve_specifier} from '@fuzdev/gro/resolve_specifier.js';

Maps an import specifier relative to dir, and infer the correct extension following Vite conventions. If no .js file is found for the specifier on the filesystem, it assumes .ts.

`specifier`

type string

`dir`

type string

returns

Promise<ResolvedSpecifier>

resolve_sveltekit_env_entry
#

(src_path: string, dir?: string): string | null import {resolve_sveltekit_env_entry} from '@fuzdev/gro/sveltekit_shim_app_env_vars.js';

The project's env var declarations module, like src/env.ts, if it has one. SvelteKit has no env vars without one, so neither does the shim.

`src_path`

the SvelteKit files.src, relative to dir

type string

`dir`

the project directory

type string

default process.cwd()

returns

string | null

ResolvedInputFile
#

ResolvedInputFile import type {ResolvedInputFile} from '@fuzdev/gro/input_path.js';

`id`

type PathId

`input_path`

type InputPath

`resolved_input_path`

type ResolvedInputPath

ResolvedInputFiles
#

ResolvedInputFiles import type {ResolvedInputFiles} from '@fuzdev/gro/input_path.js';

`resolved_input_files`

type ResolvedInputFile[]

`resolved_input_files_by_root_dir`

type Map<PathId, ResolvedInputFile[]>

`input_directories_with_no_files`

type InputPath[]

ResolvedInputPath
#

ResolvedInputPath import type {ResolvedInputPath} from '@fuzdev/gro/input_path.js';

`input_path`

type InputPath

`id`

type PathId

`is_directory`

type boolean

`root_dir`

type PathId

ResolvedInputPaths
#

resolve_specifier.ts view source

ResolvedInputPaths import type {ResolvedInputPaths} from '@fuzdev/gro/input_path.js';

`resolved_input_paths`

type ResolvedInputPath[]

`possible_paths_by_input_path`

type Map<InputPath, PossiblePath[]>

`unmapped_input_paths`

type InputPath[]

ResolvedSpecifier
#

ResolvedSpecifier import type {ResolvedSpecifier} from '@fuzdev/gro/resolve_specifier.js';

`path_id`

The resolved filesystem path for the specifier.

type PathId

`path_id_with_querystring`

Same as path_id but includes ?raw and other querystrings. (currently none)

type string

`specifier`

type string

`mapped_specifier`

type string

`namespace`

type "sveltekit_local_imports_ts" | "sveltekit_local_imports_js" | undefined

`raw`

type boolean

rewrite_dist_imports
#

(dist_dir?: string, log?: Logger | undefined): Promise<RewriteDistImportsResult> import {rewrite_dist_imports} from '@fuzdev/gro/dist_rewrite_imports.js';

Walks dist_dir and rewrites relative .ts import specifiers to .js in every .js runtime file and .d.ts declaration file (whole-file) and .svelte file (<script> blocks only). Source maps (*.map) are skipped.

`dist_dir`

the packaged output directory; defaults to dist

type string

default SVELTEKIT_DIST_DIRNAME

`log?`

type Logger

optional

returns

Promise<RewriteDistImportsResult>

counts of files scanned and rewritten

rewrite_relative_ts_imports
#

(content: string): string import {rewrite_relative_ts_imports} from '@fuzdev/gro/dist_rewrite_imports.js';

Rewrites relative .ts (and .svelte.ts) import specifiers to .js (and .svelte.js) across a chunk of TypeScript source — a whole .d.ts file or a .svelte <script> block.

`content`

type string

returns

string

rewrite_svelte_ts_imports
#

(content: string): string import {rewrite_svelte_ts_imports} from '@fuzdev/gro/dist_rewrite_imports.js';

Rewrites relative .ts import specifiers to .js inside each <script> block of a .svelte file, leaving template markup untouched.

`content`

type string

returns

string

RewriteDistImportsResult
#

RewriteDistImportsResult import type {RewriteDistImportsResult} from '@fuzdev/gro/dist_rewrite_imports.js';

`scanned`

Number of files scanned (.js, .d.ts, and .svelte).

type number

`rewritten`

Number of scanned files whose contents changed.

type number

run_gen
#

run_gen.ts view source

(gen_modules: GenfileModuleMeta[], config: GroConfig, filer: Filer, log: Logger, timings: Timings, invoke_task: InvokeTask, format_file?: ((content: string, options?: FormatFileOptions) => string) | undefined): Promise<...>

import {run_gen} from '@fuzdev/gro/run_gen.js';

`gen_modules`

type GenfileModuleMeta[]

`config`

type GroConfig

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

`invoke_task`

type InvokeTask

`format_file?`

type (content: string, options?: FormatFileOptions) => string

optional

returns

Promise<GenResults>

run_svelte_package
#

(package_json: { [x: string]: unknown; name: string; version?: string | undefined; private?: boolean | undefined; description?: string | undefined; tagline?: string | undefined; glyph?: string | undefined; ... 24 more ...; exports?: string | ... 2 more ... | undefined; }, options: SveltePackageOptions | undefined, cli: string | Cli, log: Logger, pm_cli: string): Promise<...>

import {run_svelte_package} from '@fuzdev/gro/sveltekit_helpers.js';

`package_json`

type PackageJson

`options`

type SveltePackageOptions | undefined

`cli`

type string | Cli

`log`

type Logger

`pm_cli`

type string

returns

Promise<void>

run_task
#

run_task.ts view source

(task_meta: TaskModuleMeta, unparsed_args: Args, invoke_task: (task_name: RawInputPath, args: Args | undefined, config: GroConfig, initial_filer?: Filer | undefined, initial_timings?: Timings | ... 1 more ... | undefined, parent_log?: Logger | undefined) => Promise<...>, config: GroConfig, filer: Filer, log: Logger, timings: Timings): Promise<...>

import {run_task} from '@fuzdev/gro/run_task.js';

`task_meta`

type TaskModuleMeta

`unparsed_args`

type Args

`invoke_task`

type

(task_name: RawInputPath, args: Args | undefined, config: GroConfig, initial_filer?: Filer | undefined, initial_timings?: Timings | null | undefined, parent_log?: Logger | undefined) => Promise<...>

`config`

type GroConfig

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

returns

Promise<RunTaskResult>

RunTaskResult
#

run_task.ts view source

RunTaskResult

type { ok: true; output: unknown; } | { ok: false; reason: string; error: Error; }

import type {RunTaskResult} from '@fuzdev/gro/run_task.js';

sanitize_install_env
#

(env: ProcessEnv): ProcessEnv import {sanitize_install_env} from '@fuzdev/gro/npm_install_helpers.js';

Returns a copy of env with the devDependency-pruning vars removed.

`env`

the source environment to sanitize

type ProcessEnv

returns

ProcessEnv

a fresh env object; the input is not mutated

save_build_cache_metadata
#

(metadata: { version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; }, log?: Logger | undefined): Promise<...>

import {save_build_cache_metadata} from '@fuzdev/gro/build_cache.js';

Saves build cache metadata to .gro/ directory. Errors are logged but don't fail the build (cache is optional).

`metadata`

type BuildCacheMetadata

`log?`

type Logger

optional

returns

Promise<void>

SEARCH_EXCLUDER_DEFAULT
#

RegExp import {SEARCH_EXCLUDER_DEFAULT} from '@fuzdev/gro/gro_config.js';

The regexp used by default to exclude directories and files when searching the filesystem for tasks and genfiles. Customize via search_filters in the GroConfig. See the test cases for the exact behavior.

SERVER_DIST_PATH
#

"dist_server" import {SERVER_DIST_PATH} from '@fuzdev/gro/constants.js';

SERVER_SOURCE_PATH
#

gen_helpers.ts view source

"server/server.ts" import {SERVER_SOURCE_PATH} from '@fuzdev/gro/gro_plugin_server.js';

The server entry point, relative to the project's lib directory.

should_trigger_gen
#

(gen_file_id: PathId, changed_file_id: PathId, config: GroConfig, filer: Filer, log: Logger, timings: Timings, invoke_task: InvokeTask): Promise<...>

import {should_trigger_gen} from '@fuzdev/gro/gen_helpers.js';

Check if a file change should trigger a gen file.

`gen_file_id`

type PathId

`changed_file_id`

type PathId

`config`

type GroConfig

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

`invoke_task`

type InvokeTask

returns

Promise<boolean>

SilentError
#

import {SilentError} from '@fuzdev/gro/task.js';

This is used to tell Gro to exit silently, usually still with with a non-zero exit code. Using it means error logging is handled by the code that threw it.

inheritance

extends: Error

snapshot
#

<T>(options: { id?: string | undefined; capture: () => T; restore: (value: T) => void; reset?: (() => void) | undefined; }) => void

import {snapshot} from '@fuzdev/gro/sveltekit_shim_app_navigation.js';

SOURCE_DIR
#

string import {SOURCE_DIR} from '@fuzdev/gro/constants.js';

SOURCE_DIRNAME
#

"src" import {SOURCE_DIRNAME} from '@fuzdev/gro/constants.js';

spawn_cli
#

(name_or_cli: string | Cli, args?: string[], log?: Logger | undefined, options?: SpawnOptions | undefined): Promise<SpawnResult | undefined>

import {spawn_cli} from '@fuzdev/gro/cli.js';

Spawns a CLI if available using fuz_util's spawn. If a string is provided for name_or_cli, it checks first local to the cwd and then globally.

`name_or_cli`

type string | Cli

`args`

type string[]

default []

`log?`

type Logger

optional

`options?`

type SpawnOptions

optional

returns

Promise<SpawnResult | undefined>

undefined if no CLI is found, or the spawn result

spawn_cli_process
#

gro_helpers.ts view source

(name_or_cli: string | Cli, args?: string[], log?: Logger | undefined, options?: SpawnOptions | undefined): Promise<SpawnedProcess | undefined>

import {spawn_cli_process} from '@fuzdev/gro/cli.js';

Spawns a CLI if available using fuz_util's spawn_process. If a string is provided for name_or_cli, it checks first local to the cwd and then globally.

`name_or_cli`

type string | Cli

`args`

type string[]

default []

`log?`

type Logger

optional

`options?`

type SpawnOptions

optional

returns

Promise<SpawnedProcess | undefined>

undefined if no CLI is found, or the spawn result

spawn_with_loader
#

(loader_path: string, invoke_path: string, argv: string[], js_cli?: string): Promise<SpawnResult> import {spawn_with_loader} from '@fuzdev/gro/gro_helpers.js';

Runs a file using the Gro loader.

Uses conditional exports to correctly set up esm-env as development by default, so if you want production set NODE_ENV=production.

`loader_path`

path to loader

type string

`invoke_path`

path to file to spawn with node

type string

`argv`

type string[]

`js_cli`

type string

default JS_CLI_DEFAULT

returns

Promise<SpawnResult>

spawn_with_loader_args
#

gro_helpers.ts view source

(loader_path: string, invoke_path: string, argv: string[]): string[] import {spawn_with_loader_args} from '@fuzdev/gro/gro_helpers.js';

The Node args that run invoke_path with Gro's loader registered.

`loader_path`

type string

`invoke_path`

type string

`argv`

type string[]

returns

string[]

SVELTE_CHECK_CLI
#

"svelte-check" import {SVELTE_CHECK_CLI} from '@fuzdev/gro/constants.js';

SVELTE_COMPILE_OPTIONS_DEFAULT
#

CompileOptions import {SVELTE_COMPILE_OPTIONS_DEFAULT} from '@fuzdev/gro/svelte_config.js';

Gro compiles for the server by default, because SvelteKit handles the client in the normal cases. Frozen because it's handed out as a default value.

SVELTE_DOCINFO_VERSION
#

string import {SVELTE_DOCINFO_VERSION} from '@fuzdev/gro/library_load.js';

The installed svelte-docinfo version — read from the same copy that analyzeFromFiles resolves to. Stamped into each cache record and compared on read, so caches analyzed by a different svelte-docinfo self-invalidate: source_json.modules is cached verbatim, and the cache key (the analyzed repo's commit hash) doesn't move when the *analyzer's* dependency changes its output shape.

SVELTE_MATCHER
#

RegExp import {SVELTE_MATCHER} from '@fuzdev/gro/constants.js';

SVELTE_PACKAGE_CLI
#

"svelte-package" import {SVELTE_PACKAGE_CLI} from '@fuzdev/gro/constants.js';

SVELTE_PACKAGE_DEP_NAME
#

"@sveltejs/package" import {SVELTE_PACKAGE_DEP_NAME} from '@fuzdev/gro/constants.js';

SVELTE_RUNES_MATCHER
#

RegExp import {SVELTE_RUNES_MATCHER} from '@fuzdev/gro/constants.js';

SVELTE_SCRIPT_MATCHER
#

RegExp import {SVELTE_SCRIPT_MATCHER} from '@fuzdev/gro/constants.js';

Extracts the script content from Svelte files.

SVELTEKIT_APP_ENV_VARS_MATCHER
#

RegExp import {SVELTEKIT_APP_ENV_VARS_MATCHER} from '@fuzdev/gro/sveltekit_shim_app_env_vars.js';

Matches the SvelteKit env var modules, capturing the visibility.

SVELTEKIT_BUILD_DIRNAME
#

"build" import {SVELTEKIT_BUILD_DIRNAME} from '@fuzdev/gro/constants.js';

SVELTEKIT_CLI
#

"svelte-kit" import {SVELTEKIT_CLI} from '@fuzdev/gro/constants.js';

SVELTEKIT_DEP_NAME
#

"@sveltejs/kit" import {SVELTEKIT_DEP_NAME} from '@fuzdev/gro/constants.js';

SVELTEKIT_DEV_DIRNAME
#

".svelte-kit" import {SVELTEKIT_DEV_DIRNAME} from '@fuzdev/gro/constants.js';

SVELTEKIT_DIST_DIRNAME
#

"dist" import {SVELTEKIT_DIST_DIRNAME} from '@fuzdev/gro/constants.js';

SVELTEKIT_GLOBAL_SPECIFIER
#

RegExp import {SVELTEKIT_GLOBAL_SPECIFIER} from '@fuzdev/gro/constants.js';

SVELTEKIT_SHIM_APP_ENV_MATCHER
#

RegExp import {SVELTEKIT_SHIM_APP_ENV_MATCHER} from '@fuzdev/gro/sveltekit_shim_app.js';

SVELTEKIT_SHIM_APP_PATHS_MATCHER
#

RegExp import {SVELTEKIT_SHIM_APP_PATHS_MATCHER} from '@fuzdev/gro/sveltekit_shim_app.js';

sveltekit_shim_app_specifiers
#

Map<string, string>

type Map<string, string>

import {sveltekit_shim_app_specifiers} from '@fuzdev/gro/sveltekit_shim_app.js';

Maps SvelteKit $app specifiers to their Gro shims. $app/env/public and $app/env/private aren't files, see sveltekit_shim_app_env_vars.ts.

sveltekit_sync
#

(sveltekit_cli?: string | Cli, pm_cli?: string): Promise<void> import {sveltekit_sync} from '@fuzdev/gro/sveltekit_helpers.js';

`sveltekit_cli`

type string | Cli

default SVELTEKIT_CLI

`pm_cli`

type string

default PM_CLI_DEFAULT

returns

Promise<void>

sveltekit_sync_if_available
#

(sveltekit_cli?: string | Cli): Promise<void> import {sveltekit_sync_if_available} from '@fuzdev/gro/sveltekit_helpers.js';

If the SvelteKit CLI is found, run svelte-kit sync.

`sveltekit_cli`

type string | Cli

default SVELTEKIT_CLI

returns

Promise<void>

sveltekit_sync_if_obviously_needed
#

(sveltekit_cli?: string | Cli): Promise<void> import {sveltekit_sync_if_obviously_needed} from '@fuzdev/gro/sveltekit_helpers.js';

If the SvelteKit CLI is found and either its .svelte-kit directory or its generated $app/tsconfig is not, run svelte-kit sync. The tsconfig is checked because it lives in node_modules, which reinstalls wipe.

`sveltekit_cli`

type string | Cli

default SVELTEKIT_CLI

returns

Promise<void>

sveltekit_tsconfig_is_unsynced
#

(dir: string): Promise<boolean> import {sveltekit_tsconfig_is_unsynced} from '@fuzdev/gro/sveltekit_helpers.js';

Whether dir's tsconfig.json extends SvelteKit's $app/tsconfig while the generated node_modules/$app/tsconfig.json is missing - the project was never synced, or a reinstall wiped node_modules. TypeScript doesn't fail on an unresolved extends, so tools reading such a tsconfig silently run on default compiler options and read external types as any.

Reads the tsconfig as JSONC with TypeScript's own parser and accepts a string or array extends. Only dir's own tsconfig.json is checked, not configs it extends. A missing tsconfig, or one TypeScript's tolerant parser recovers no extends from, returns false, left to whatever reads it next.

`dir`

absolute path to the project root

type string

returns

Promise<boolean>

true when the project needs svelte-kit sync

SVELTEKIT_TSCONFIG_PATH
#

string import {SVELTEKIT_TSCONFIG_PATH} from '@fuzdev/gro/constants.js';

The tsconfig SvelteKit generates for projects to extend as $app/tsconfig.

SVELTEKIT_TSCONFIG_SPECIFIER
#

"$app/tsconfig" import {SVELTEKIT_TSCONFIG_SPECIFIER} from '@fuzdev/gro/constants.js';

The extends specifier SvelteKit projects use for the tsconfig that svelte-kit sync generates at SVELTEKIT_TSCONFIG_PATH.

SVELTEKIT_VITE_CACHE_PATH
#

string import {SVELTEKIT_VITE_CACHE_PATH} from '@fuzdev/gro/constants.js';

SveltePackageOptions
#

SveltePackageOptions import type {SveltePackageOptions} from '@fuzdev/gro/sveltekit_helpers.js';

Options to the SvelteKit packaging CLI.

`watch?`

Watch files in src/lib for changes and rebuild the package

type boolean

`w?`

Alias for watch.

type boolean

`input?`

The input directory which contains all the files of the package. Defaults to src/lib

type string

`i?`

Alias for input.

type string

`output?`

The output directory where the processed files are written to. Your package.json's exports should point to files inside there, and the files array should include that folder. Defaults to dist

type string

`o?`

Alias for output.

type string

`types?`

Whether or not to create type definitions (d.ts files). We strongly recommend doing this as it fosters ecosystem library quality. Defaults to true

type boolean

`t?`

Alias for types.

type boolean

`tsconfig?`

The path to a tsconfig or jsconfig. When not provided, searches for the next upper tsconfig/jsconfig in the workspace path.

type string

Task
#

Task<TArgs, TArgsSchema, TReturn> import type {Task} from '@fuzdev/gro/task.js';

generics

Task<TArgs = Args, TArgsSchema extends z.ZodType<Args, Args> = z.ZodType<Args, Args>, TReturn = unknown>

`TArgs`

default Args

`TArgsSchema`

constraint z.ZodType<Args, Args>

default z.ZodType<Args, Args>

`TReturn`

default unknown

`run`

type (ctx: TaskContext<TArgs>): TReturn | Promise<TReturn>

`ctx`

type TaskContext<TArgs>

returns TReturn | Promise<TReturn>

`summary?`

type string

`Args?`

type TArgsSchema

TASK_FILE_SUFFIX_JS
#

".task.js" import {TASK_FILE_SUFFIX_JS} from '@fuzdev/gro/task.js';

TASK_FILE_SUFFIX_TS
#

".task.ts" import {TASK_FILE_SUFFIX_TS} from '@fuzdev/gro/task.js';

TASK_FILE_SUFFIXES
#

string[] import {TASK_FILE_SUFFIXES} from '@fuzdev/gro/task.js';

task_registry_find
#

(task_root_dirs: PathId[], search_filters: PathFilter[]): Promise<TaskRegistryEntry[]> import {task_registry_find} from '@fuzdev/gro/task_registry.js';

Finds the tasks in task_root_dirs with the names runtime resolution gives them, skipping Gro's builtins, which GroBuiltinTasks types. A file or name found under an earlier root dir shadows later ones, like resolution.

`task_root_dirs`

type PathId[]

`search_filters`

type PathFilter[]

returns

Promise<TaskRegistryEntry[]>

task_registry_render_builtins
#

(entries: TaskRegistryEntry[], output_dir: PathId, origin_path: string): string import {task_registry_render_builtins} from '@fuzdev/gro/task_registry.js';

Renders the GroBuiltinTasks interface for Gro's own tasks.

`entries`

type TaskRegistryEntry[]

`output_dir`

type PathId

`origin_path`

type string

returns

string

task_registry_render_project
#

gro_plugin_gen.ts view source

(entries: TaskRegistryEntry[], output_dir: PathId, origin_path: string): string import {task_registry_render_project} from '@fuzdev/gro/task_registry.js';

Renders the module augmentation of ProjectTasks written by gen_task_registry.

`entries`

type TaskRegistryEntry[]

`output_dir`

type PathId

`origin_path`

type string

returns

string

TaskArgs
#

TaskArgs import type {TaskArgs} from '@fuzdev/gro/gro_plugin_gen.js';

inheritance

extends: Args

`watch?`

type boolean

TaskArgsInput
#

TaskArgsInput<TName>

type TaskRegistry[TName] extends { Args: infer TSchema extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; } ? input<TSchema> : Args

import type {TaskArgsInput} from '@fuzdev/gro/task_registry.js';

The input type of the task's Args schema, so defaulted args are optional, or loose Args for a task module without an Args export.

generics

TaskArgsInput<TName extends TaskName>

`TName`

constraint TaskName

TaskContext
#

TaskContext<TArgs> import type {TaskContext} from '@fuzdev/gro/task.js';

generics

TaskContext<TArgs = object>

`TArgs`

default object

`args`

type TArgs

`config`

type GroConfig

`svelte_config`

Resolved on first access, so tasks that don't touch it never pay to read the SvelteKit config.

type Promise<ParsedSvelteConfig>

`filer`

type Filer

`log`

type Logger

`timings`

type Timings

`invoke_task`

type <TName extends string>(task_name: InvokeTaskName<TName>, ...rest: InvokeTaskRest<TName>): Promise<void>

`task_name`

type InvokeTaskName<TName>

`rest`

type InvokeTaskRest<TName>

returns Promise<void>

TaskError
#

import {TaskError} from '@fuzdev/gro/task.js';

This is used by tasks to signal a known failure. It's useful for cleaning up logging because we usually don't need their stack trace.

inheritance

extends: Error

TaskModule
#

TaskModule import type {TaskModule} from '@fuzdev/gro/task.js';

`task`

type Task<Args, ZodType<Args, Args, $ZodTypeInternals<Args, Args>>, unknown>

TaskModuleMeta
#

TaskModuleMeta import type {TaskModuleMeta} from '@fuzdev/gro/task.js';

inheritance

extends: ModuleMeta<TaskModule>

`name`

type string

TaskName
#

TaskName

import type {TaskName} from '@fuzdev/gro/task_registry.js';

TaskRegistry
#

TaskRegistry

type Omit<GroBuiltinTasks, "clean" | "fixture/no_args" | "fixture/required_args"> & ProjectTasks & { "gro/build": typeof import("build.task.ts", { with: { "resolution-mode": "import" } }); "gro/changeset": typeof import("changeset.task.ts", { with: { "resolution-mode": "import" } }); "gro/check": typeof import("check.task.ts", { with: { "reso...

import type {TaskRegistry} from '@fuzdev/gro/task_registry.js';

Every task name invoke_task accepts as a literal, mapped to its module's type. Mirrors runtime resolution: a project task shadows the builtin with the same name, and gro/-prefixed names always reach the builtin.

`build`

type typeof import("build.task.ts", { with: { "resolution-mode": "import" } })

`changeset`

type typeof import("changeset.task.ts", { with: { "resolution-mode": "import" } })

`check`

type typeof import("check.task.ts", { with: { "resolution-mode": "import" } })

`commit`

type typeof import("commit.task.ts", { with: { "resolution-mode": "import" } })

`deploy`

type typeof import("deploy.task.ts", { with: { "resolution-mode": "import" } })

`dev`

type typeof import("dev.task.ts", { with: { "resolution-mode": "import" } })

`format`

type typeof import("format.task.ts", { with: { "resolution-mode": "import" } })

`gen`

type typeof import("gen.task.ts", { with: { "resolution-mode": "import" } })

`lint`

type typeof import("lint.task.ts", { with: { "resolution-mode": "import" } })

`publish`

type typeof import("publish.task.ts", { with: { "resolution-mode": "import" } })

`reinstall`

type typeof import("reinstall.task.ts", { with: { "resolution-mode": "import" } })

`release`

type typeof import("release.task.ts", { with: { "resolution-mode": "import" } })

`resolve`

type typeof import("resolve.task.ts", { with: { "resolution-mode": "import" } })

`run`

type typeof import("run.task.ts", { with: { "resolution-mode": "import" } })

`sync`

type typeof import("sync.task.ts", { with: { "resolution-mode": "import" } })

`test`

type typeof import("test.task.ts", { with: { "resolution-mode": "import" } })

`typecheck`

type typeof import("typecheck.task.ts", { with: { "resolution-mode": "import" } })

`upgrade`

type typeof import("upgrade.task.ts", { with: { "resolution-mode": "import" } })

`clean`

type typeof import("src/test/fixtures/task_registry/clean_override.task_fixture.ts", { with: { "resolution-mode": "import" } })

`fixture/no_args`

type typeof import("src/test/fixtures/task_registry/no_args.task_fixture.ts", { with: { "resolution-mode": "import" } })

`fixture/required_args`

type typeof import("src/test/fixtures/task_registry/required_args.task_fixture.ts", { with: { "resolution-mode": "import" } })

`gro/build`

type typeof import("build.task.ts", { with: { "resolution-mode": "import" } })

`gro/changeset`

type typeof import("changeset.task.ts", { with: { "resolution-mode": "import" } })

`gro/check`

type typeof import("check.task.ts", { with: { "resolution-mode": "import" } })

`gro/clean`

type typeof import("clean.task.ts", { with: { "resolution-mode": "import" } })

`gro/commit`

type typeof import("commit.task.ts", { with: { "resolution-mode": "import" } })

`gro/deploy`

type typeof import("deploy.task.ts", { with: { "resolution-mode": "import" } })

`gro/dev`

type typeof import("dev.task.ts", { with: { "resolution-mode": "import" } })

`gro/format`

type typeof import("format.task.ts", { with: { "resolution-mode": "import" } })

`gro/gen`

type typeof import("gen.task.ts", { with: { "resolution-mode": "import" } })

`gro/lint`

type typeof import("lint.task.ts", { with: { "resolution-mode": "import" } })

`gro/publish`

type typeof import("publish.task.ts", { with: { "resolution-mode": "import" } })

`gro/reinstall`

type typeof import("reinstall.task.ts", { with: { "resolution-mode": "import" } })

`gro/release`

type typeof import("release.task.ts", { with: { "resolution-mode": "import" } })

`gro/resolve`

type typeof import("resolve.task.ts", { with: { "resolution-mode": "import" } })

`gro/run`

type typeof import("run.task.ts", { with: { "resolution-mode": "import" } })

`gro/sync`

type typeof import("sync.task.ts", { with: { "resolution-mode": "import" } })

`gro/test`

type typeof import("test.task.ts", { with: { "resolution-mode": "import" } })

`gro/typecheck`

type typeof import("typecheck.task.ts", { with: { "resolution-mode": "import" } })

`gro/upgrade`

type typeof import("upgrade.task.ts", { with: { "resolution-mode": "import" } })

TaskRegistryEntry
#

TaskRegistryEntry import type {TaskRegistryEntry} from '@fuzdev/gro/task_registry.js';

`name`

type string

`id`

type PathId

to_cli_name
#

(cli: string | Cli): string import {to_cli_name} from '@fuzdev/gro/cli.js';

`cli`

type string | Cli

returns

string

to_default_compile_module_options
#

({ dev, generate, filename, rootDir, warningFilter }: CompileOptions): ModuleCompileOptions import {to_default_compile_module_options} from '@fuzdev/gro/svelte_config.js';

`__0`

type CompileOptions

returns

ModuleCompileOptions

to_default_env_files
#

(dev: boolean): string[] import {to_default_env_files} from '@fuzdev/gro/env.js';

The env files Vite loads for a mode, in precedence order, later files winning.

`dev`

type boolean

returns

string[]

to_default_outpaths
#

esbuild_helpers.ts view source

(dir: string, lib_dir: string): CreateOutpaths import {to_default_outpaths} from '@fuzdev/gro/gro_plugin_server.js';

The Outpaths used when the plugin is given none.

`dir`

type string

`lib_dir`

type string

returns

CreateOutpaths

to_define_import_meta_env
#

(dev: boolean, base_url: "" | `/${string}` | undefined, ssr?: boolean, mode?: string): Record<string, string> import {to_define_import_meta_env} from '@fuzdev/gro/esbuild_helpers.js';

Creates an esbuild define shim for Vite's import.meta\.env.

`dev`

type boolean

`base_url`

best-effort shim from SvelteKit's base to Vite's import.meta\.env.BASE_URL

type "" | `/${string}` | undefined

`ssr`

type boolean

default true

`mode`

type string

default dev ? 'development' : 'production'

returns

Record<string, string>

to_forwarded_args
#

(command: string, raw_rest_args?: string[] | undefined, cache?: Record<string, Args | undefined>): Args import {to_forwarded_args} from '@fuzdev/gro/args.js';

Parses process.argv for the specified command, so given gro taskname arg1 --arg2 -- eslint eslintarg1 --eslintarg2 -- tsc --tscarg1 --tscarg2 the command 'eslint' returns eslintarg1 --eslintarg2 and 'tsc' returns --tscarg1 and --tscarg2.

`command`

type string

`raw_rest_args?`

type string[]

optional

`cache`

type Record<string, Args | undefined>

default to_forwarded_args_by_command(raw_rest_args)

returns

Args

to_forwarded_args_by_command
#

(raw_rest_args?: string[]): Record<string, Args | undefined> import {to_forwarded_args_by_command} from '@fuzdev/gro/args.js';

`raw_rest_args`

type string[]

default to_raw_rest_args()

returns

Record<string, Args | undefined>

to_gen_result
#

(origin_id: PathId, raw_result: RawGenResult): GenResult import {to_gen_result} from '@fuzdev/gro/gen.js';

`origin_id`

type PathId

`raw_result`

type RawGenResult

returns

GenResult

to_implicit_forwarded_args
#

(command_to_strip?: string | undefined, raw_rest_args?: string[]): Args import {to_implicit_forwarded_args} from '@fuzdev/gro/args.js';

Gets all args after the first -- without assuming a command name. This is useful for tasks that want to forward args directly to a tool without requiring users to specify the tool name explicitly. Optionally strips a specific command name if present for backward compatibility.

`command_to_strip?`

type string

optional

`raw_rest_args`

type string[]

default to_raw_rest_args()

returns

Args

examples

// `gro test -- --watch` → {watch: true}
// `gro test -- foo.test.ts` → {_: ['foo.test.ts']}
// `gro test -- vitest --watch` with command_to_strip='vitest' → {watch: true}
to_implicit_forwarded_args('vitest')

to_input_path
#

(raw_input_path: RawInputPath, root_path?: string): InputPath import {to_input_path} from '@fuzdev/gro/input_path.js';

Raw input paths are paths that users provide to Gro to reference files for tasks and gen.

A raw input path can be to a file or directory in the following forms:

an absolute path, preserved
an explicit relative path, e.g. ./src/foo, resolved to root_path which defaults to the cwd
an implicit relative path, e.g. src/foo, preserved
an implicit relative path prefixed with gro/, transformed to absolute in the Gro directory

Thus, input paths are either absolute or implicitly relative.

`raw_input_path`

type RawInputPath

`root_path`

type string

default process.cwd()

returns

InputPath

to_input_paths
#

resolve_specifier.ts view source

(raw_input_paths: RawInputPath[], root_path?: string | undefined): InputPath[] import {to_input_paths} from '@fuzdev/gro/input_path.js';

`raw_input_paths`

type RawInputPath[]

`root_path?`

type string

optional

returns

InputPath[]

to_missing_module_id
#

(error: unknown): string | null import {to_missing_module_id} from '@fuzdev/gro/resolve_specifier.js';

The file a failed Node resolution was looking for, if it failed because the file is missing - Node maps a subpath import like #lib/foo.js through package.json imports before failing, so this is the path a .js-for-.ts retry should start from.

`error`

type unknown

returns

string | null

the missing file's path, or null for any other error

to_output_file_name
#

(filename: string): string import {to_output_file_name} from '@fuzdev/gro/gen.js';

`filename`

type string

returns

string

to_plugin_context
#

<TArgs>(ctx: TaskContext<TArgs>, dev: boolean, watch: boolean): PluginContext<TArgs> import {to_plugin_context} from '@fuzdev/gro/plugin.js';

Widens a TaskContext to a PluginContext by adding dev and watch. Copies property descriptors rather than spreading, because svelte_config is a lazy getter - spreading would call it, resolving the Svelte config even for a plugin set that never reads it, and pinning whichever promise it returned instead of the memoized one.

`ctx`

type TaskContext<TArgs>

`dev`

type boolean

`watch`

type boolean

returns

PluginContext<TArgs>

generics

to_plugin_context<TArgs>

`TArgs`

to_raw_rest_args
#

(argv?: string[]): string[] import {to_raw_rest_args} from '@fuzdev/gro/args.js';

Gets the array of raw string args starting with the first --, if any.

`argv`

type string[]

default process.argv

returns

string[]

to_root_path
#

(id: PathId, p?: Paths): string import {to_root_path} from '@fuzdev/gro/paths.js';

`id`

type PathId

`p`

type Paths

default infer_paths(id)

returns

string

to_server_source_id
#

(lib_path?: string): PathId import {to_server_source_id} from '@fuzdev/gro/gro_plugin_server.js';

The server entry point of a project whose lib directory is lib_path.

`lib_path`

type string

default LIB_PATH

returns

PathId

to_task_args
#

(argv?: string[]): { task_name: string; args: Args; } import {to_task_args} from '@fuzdev/gro/args.js';

Parses task_name and args from process.argv, ignoring anything after any --.

`argv`

type string[]

default process.argv

returns

{ task_name: string; args: Args; }

to_task_name
#

(id: PathId, task_root_dir: PathId, input_path: InputPath, root_path: PathId): string import {to_task_name} from '@fuzdev/gro/task.js';

`id`

type PathId

`task_root_dir`

type PathId

`input_path`

type InputPath

`root_path`

type PathId

returns

string

TS_MATCHER
#

RegExp import {TS_MATCHER} from '@fuzdev/gro/constants.js';

TSCONFIG_FILENAME
#

sveltekit_shim_app_state.ts view source

"tsconfig.json" import {TSCONFIG_FILENAME} from '@fuzdev/gro/constants.js';

update_changelog
#

changelog.ts view source

(owner: string, repo: string, path?: string, token?: string | undefined, log?: Logger | undefined, cache?: Map<string, { key: string; url: string; params: any; value: any; etag: string | null; last_modified: string | null; }>): Promise<...>

import {update_changelog} from '@fuzdev/gro/changelog.js';

Updates a changelog produced by @changesets/changelog-git with better links and formatting. It's similar to @changesets/changelog-github but doesn't require a token for light usage. This may be better implemented as a standalone dependency as an alternative to @changesets/changelog-git.

`owner`

type string

`repo`

type string

`path`

type string

default 'CHANGELOG.md'

`token?`

type string

optional

`log?`

type Logger

optional

`cache`

type Map<string, { key: string; url: string; params: any; value: any; etag: string | null; last_modified: string | null; }>

default new Map()

returns

Promise<boolean>

boolean indicating if the changelog changed

updated
#

{ readonly current: boolean; check(): Promise<boolean>; } import {updated} from '@fuzdev/gro/sveltekit_shim_app_state.js';

validate_build_cache
#

(metadata: { version: string; git_commit: string | null; build_cache_config_hash: string; timestamp: string; outputs: { path: string; hash: string; size: number; mtime: number; ctime: number; mode: number; }[]; }): Promise<...>

import {validate_build_cache} from '@fuzdev/gro/build_cache.js';

Validates that a cached build is still valid by checking stats and hashing outputs. Uses size as a fast negative check before expensive hashing. This is comprehensive validation to catch manual tampering or corruption.

`metadata`

type BuildCacheMetadata

returns

Promise<boolean>

validate_gen_module
#

(mod: Record<string, any>): mod is GenfileModule import {validate_gen_module} from '@fuzdev/gro/gen.js';

`mod`

type Record<string, any>

returns

boolean

validate_gro_config_module
#

(config_module: any, config_path: string): asserts config_module is GroConfigModule import {validate_gro_config_module} from '@fuzdev/gro/gro_config.js';

`config_module`

type any

`config_path`

type string

returns

void

validate_task_module
#

(mod: Record<string, any>): mod is TaskModule import {validate_task_module} from '@fuzdev/gro/task.js';

`mod`

type Record<string, any>

returns

boolean

version
#

"" import {version} from '@fuzdev/gro/sveltekit_shim_app_env.js';

VITE_CLI
#

"vite" import {VITE_CLI} from '@fuzdev/gro/constants.js';

VITE_CONFIG_FILENAMES
#

string[] import {VITE_CONFIG_FILENAMES} from '@fuzdev/gro/constants.js';

Every filename Vite picks up as its config, in Vite's own precedence order. Which one wins is Vite's call, so Gro treats them as a set rather than privileging one extension - it detects a Vite config with all of them, and formats all of them.

VITEST_CLI
#

"vitest" import {VITEST_CLI} from '@fuzdev/gro/constants.js';

watch_dir
#

({ dir, on_change, filter, absolute, chokidar, ignored }: WatchDirOptions): WatchNodeFs import {watch_dir} from '@fuzdev/gro/watch_dir.js';

Watch for changes on the filesystem using chokidar.

`__0`

type WatchDirOptions

returns

WatchNodeFs

WatchDirOptions
#

WatchDirOptions import type {WatchDirOptions} from '@fuzdev/gro/watch_dir.js';

`dir`

type string

`on_change`

type (change: WatcherChange): void

`change`

type WatcherChange

returns void

`filter?`

type (PathFilter) | null

`chokidar?`

type Partial<BasicOpts & { ignored: Matcher | Matcher[]; awaitWriteFinish: boolean | Partial<AWF>; }>

`absolute?`

When false, returns the path relative to dir.

type boolean

default true

`ignored?`

Pattern to ignore files, merged into chokidar.ignored if also provided.

undefined (default) ignores files matching .tmp. pattern
null sets no default ignore pattern
or some custom pattern

type Matcher | null

WatcherChange
#

WatcherChange import type {WatcherChange} from '@fuzdev/gro/watch_dir.js';

`type`

type WatcherChangeType

`path`

type string

`is_directory`

type boolean

WatcherChangeCallback
#

WatcherChangeCallback import type {WatcherChangeCallback} from '@fuzdev/gro/watch_dir.js';

`(call)`

type (change: WatcherChange): void

`change`

type WatcherChange

returns void

WatcherChangeType
#

WatcherChangeType

type "add" | "update" | "delete"

import type {WatcherChangeType} from '@fuzdev/gro/watch_dir.js';

WatchNodeFs
#

WatchNodeFs import type {WatchNodeFs} from '@fuzdev/gro/watch_dir.js';

`init`

type (): Promise<void>

returns Promise<void>

`close`

type (): Promise<void>

returns Promise<void>

write_gen_results
#