CLIAPI

sv

sv exposes a programmatic API for creating projects and running add-ons.

defineAddon

Creates an add-on definition. See create your own for a full guide.

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): (content: string) => string;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): (content: string) => string;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
The parser choice is baked into the transform type - you can't accidentally
parse a vite config as svelte because you never call a parser yourself.
Transforms are curried: call with the callback to get a (content: string) => string
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';
import { defineAddon(alias) function defineAddon<const Id extends string, Args extends OptionDefinition>(config: Addon<Args, Id>): Addon<Args, Id> (+1 overload)
import defineAddonThe entry point for your addon, It will hold every thing! (options, setup, run, nextSteps, ...)
For dynamic options added via addOption in setup, use the generic to get strong typing:
const addon = defineAddon<{ extra: boolean }>()({ ... });
addon.options.extra.default // boolean, defineAddonOptions(alias) function defineAddonOptions(): OptionBuilder<{}>
import defineAddonOptionsOptions for an addon.
Will be prompted to the user if there are not answered by args when calling the cli.
const options = defineAddonOptions()
  .add('demo', {
    question: `demo? ${color.optional('(a cool one!)')}`
    type: string | boolean | number | select | multiselect,
    default: true,
  })
  .build();
To define by args, you can do
npx sv add <addon>=<option1>:<value1>+<option2>:<value2> } from 'sv';

export default defineAddon(alias) defineAddon<"my-addon", {}>(config: Addon<{}, "my-addon", Record<string, unknown>>): Addon<{}, "my-addon", Record<string, unknown>> (+1 overload)
import defineAddonThe entry point for your addon, It will hold every thing! (options, setup, run, nextSteps, ...)
For dynamic options added via addOption in setup, use the generic to get strong typing:
const addon = defineAddon<{ extra: boolean }>()({ ... });
addon.options.extra.default // boolean({
	id(property) id: "my-addon": 'my-addon',
	options(property) options: {}: defineAddonOptions(alias) defineAddonOptions(): OptionBuilder<{}>
import defineAddonOptionsOptions for an addon.
Will be prompted to the user if there are not answered by args when calling the cli.
const options = defineAddonOptions()
  .add('demo', {
    question: `demo? ${color.optional('(a cool one!)')}`
    type: string | boolean | number | select | multiselect,
    default: true,
  })
  .build();
To define by args, you can do
npx sv add <addon>=<option1>:<value1>+<option2>:<value2>().build(method) build(): {}(),
	// called before run - declare dependencies, environment requirements, and dynamic options	setup(property) setup?: ((workspace: Workspace & {
    dependsOn: (name: keyof OfficialAddons) => void;
    unsupported: (reason: string) => void;
    runsAfter: (name: keyof OfficialAddons) => void;
    addOption: <K extends string>(key: K, question: BaseQuestion<any> & Question<any>) => void;
}) => MaybePromise<void>) | undefined: ({ dependsOn(parameter) dependsOn: (name: keyof OfficialAddons) => voidOn what official addons does this addon depend on?
, unsupported(parameter) unsupported: (reason: string) => voidWhy is this addon not supported?
, addOption(parameter) addOption: <K extends string>(key: K, question: BaseQuestion<any> & Question<any>) => void, isKit(parameter) isKit: boolean }) => {
		if (!isKit(parameter) isKit: boolean) unsupported(parameter) unsupported: (reason: string) => voidWhy is this addon not supported?
('Requires SvelteKit');
		dependsOn(parameter) dependsOn: (name: keyof OfficialAddons) => voidOn what official addons does this addon depend on?
('eslint');
		// dynamically add options based on workspace state or fetched data		addOption(parameter) addOption: <"theme">(key: "theme", question: BaseQuestion<any> & Question<any>) => void('theme', {
			question(property) question: string: 'Which theme?',
			type(property) type: "select": 'select',
			default(property) default: any: 'dark',
			options(property) options: {
    value: any;
    label?: string;
    hint?: string;
}[]: [{ value(property) value: any: 'dark' }, { value(property) value: any: 'light' }]
		});
	},
	// the actual work — add files, edit files, declare dependencies	run(property) run: (workspace: Workspace & {
    options: OptionValues<{}> & Record<string, unknown>;
    sv: SvApi;
    cancel: (reason: string) => void;
}) => MaybePromise<void>: ({ sv(parameter) sv: SvApi, options(parameter) options: OptionValues<{}> & Record<string, unknown>Add-on options (includes dynamically added options from setup)
, cancel(parameter) cancel: (reason: string) => voidCancel the addon at any time!
 }) => {
		// add a dependency		sv(parameter) sv: SvApi.devDependency(property) devDependency: (pkg: string, version: string) => void('my-lib', '^1.0.0');
		// create or edit files using transforms from @sveltejs/sv-utils		sv(parameter) sv: SvApi.file(property) file: (path: string, edit: (content: string) => string | false) => voidEdit a file in the workspace. (will create it if it doesn't exist)
Return false from the callback to abort - the original content is returned unchanged.
('src/lib/foo.ts', (content(parameter) content: string) => {
			return 'export const foo = true;';
		});

		sv(parameter) sv: SvApi.file(property) file: (path: string, edit: (content: string) => string | false) => voidEdit a file in the workspace. (will create it if it doesn't exist)
Return false from the callback to abort - the original content is returned unchanged.
(
			'src/routes/+page.svelte',
			transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): (content: string) => string;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): (content: string) => string;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
The parser choice is baked into the transform type - you can't accidentally
parse a vite config as svelte because you never call a parser yourself.
Transforms are curried: call with the callback to get a (content: string) => string
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.svelte(method) svelte(cb: (file: {
    ast: AST.Root;
    content: string;
    svelte: typeof index_d_exports$4;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): (content: string) => stringTransform a Svelte component file.
Return false from the callback to abort - the original content is returned unchanged.
(({ ast(parameter) ast: AST.Root, svelte(parameter) svelte: typeof index_d_exports$4 }) => {
				svelte(parameter) svelte: typeof index_d_exports$4.addFragment(alias) index_d_exports$4.addFragment(ast: AST.Root, content: string, options?: {
    mode?: "append" | "prepend";
    language?: "ts" | "js";
}): void
export index_d_exports$4.addFragment(ast(parameter) ast: AST.Root, '<p>Hello!</p>');
			})
		);
		// cancel at any point if something is wrong		// cancel('reason');	},
	// displayed after the add-on runs	nextSteps(property) nextSteps?: ((workspace: Workspace & {
    options: OptionValues<{}> & Record<string, unknown>;
}) => string[]) | undefined: ({ options(parameter) options: OptionValues<{}> & Record<string, unknown> }) => ['Run `npm run dev` to get started']
});

The sv object in run provides file, dependency, devDependency, and execute. For file transforms (AST-based editing of scripts, Svelte components, CSS, JSON, etc.) and package manager helpers, see @sveltejs/sv-utils.

Typed dynamic options

If your add-on adds options dynamically in setup (e.g. from a fetch), you can pass a type parameter to defineAddon to get strong typing for those options:

const addonconst addon: Addon<{} & SetupOptions<{
    theme: string;
}>, "my-addon", {
    theme: string;
}> = defineAddon(alias) defineAddon<{
    theme: string;
}>(): <Id, Args>(config: Omit<Addon<Args & SetupOptions<{
    theme: string;
}>, Id, {
    theme: string;
}>, "options"> & {
    options: Args;
}) => Addon<Args & SetupOptions<{
    theme: string;
}>, Id, {
    theme: string;
}> (+1 overload)
import defineAddonThe entry point for your addon, It will hold every thing! (options, setup, run, nextSteps, ...)
For dynamic options added via addOption in setup, use the generic to get strong typing:
const addon = defineAddon<{ extra: boolean }>()({ ... });
addon.options.extra.default // boolean<{ theme(property) theme: string: string }>()({
	id(property) id: "my-addon": 'my-addon',
	options(property) options: {}: defineAddonOptions(alias) defineAddonOptions(): OptionBuilder<{}>
import defineAddonOptionsOptions for an addon.
Will be prompted to the user if there are not answered by args when calling the cli.
const options = defineAddonOptions()
  .add('demo', {
    question: `demo? ${color.optional('(a cool one!)')}`
    type: string | boolean | number | select | multiselect,
    default: true,
  })
  .build();
To define by args, you can do
npx sv add <addon>=<option1>:<value1>+<option2>:<value2>().build(method) build(): {}(),
	setup(property) setup?: ((workspace: Workspace & {
    dependsOn: (name: keyof OfficialAddons) => void;
    unsupported: (reason: string) => void;
    runsAfter: (name: keyof OfficialAddons) => void;
    addOption: <K extends "theme">(key: K, question: SetupOptions<{
        theme: string;
    }>[K]) => void;
}) => MaybePromise<void>) | undefined: ({ addOption(parameter) addOption: <K extends "theme">(key: K, question: SetupOptions<{
    theme: string;
}>[K]) => void }) => {
		addOption(parameter) addOption: <"theme">(key: "theme", question: BaseQuestion<any> & StringQuestion) => void('theme', {
			question(property) question: string: 'Which theme?',
			type(property) type: "string": 'string',
			default(property) default: string: 'dark'
		});
	},
	run(property) run: (workspace: Workspace & {
    options: OptionValues<{} & SetupOptions<{
        theme: string;
    }>> & Record<string, unknown>;
    sv: SvApi;
    cancel: (reason: string) => void;
}) => MaybePromise<void>: ({ options(parameter) options: OptionValues<{} & SetupOptions<{
    theme: string;
}>> & Record<string, unknown>Add-on options (includes dynamically added options from setup)
 }) => {
		options(parameter) options: OptionValues<{} & SetupOptions<{
    theme: string;
}>> & Record<string, unknown>Add-on options (includes dynamically added options from setup)
.theme(property) theme: string; // string
	}
});

The type parameter maps value types (boolean, string, number) to question definitions. Without it, defineAddon stays strict and only allows statically defined options.

defineAddonOptions

Builder for add-on options. Chained with .add() and finalized with .build().

import { defineAddonOptions(alias) function defineAddonOptions(): OptionBuilder<{}>
import defineAddonOptionsOptions for an addon.
Will be prompted to the user if there are not answered by args when calling the cli.
const options = defineAddonOptions()
  .add('demo', {
    question: `demo? ${color.optional('(a cool one!)')}`
    type: string | boolean | number | select | multiselect,
    default: true,
  })
  .build();
To define by args, you can do
npx sv add <addon>=<option1>:<value1>+<option2>:<value2> } from 'sv';

const optionsconst options: {
    database: {
        readonly question: "Which database?";
        readonly type: "select";
        readonly default: "postgresql";
        readonly options: [{
            readonly value: "postgresql";
        }, {
            readonly value: "mysql";
        }, {
            readonly value: "sqlite";
        }];
    };
    docker: {
        readonly question: "Add a docker-compose file?";
        readonly type: "boolean";
        readonly default: false;
        readonly condition: (opts: OptionValues<Record<"database", {
            readonly question: "Which database?";
            readonly type: "select";
            readonly default: "postgresql";
            readonly options: [{
                readonly value: "postgresql";
            }, {
                readonly value: "mysql";
            }, {
                readonly value: "sqlite";
            }];
        }> & Record<...>>) => boolean;
    };
} = defineAddonOptions(alias) defineAddonOptions(): OptionBuilder<{}>
import defineAddonOptionsOptions for an addon.
Will be prompted to the user if there are not answered by args when calling the cli.
const options = defineAddonOptions()
  .add('demo', {
    question: `demo? ${color.optional('(a cool one!)')}`
    type: string | boolean | number | select | multiselect,
    default: true,
  })
  .build();
To define by args, you can do
npx sv add <addon>=<option1>:<value1>+<option2>:<value2>()
	.add(method) add<"database", {
    readonly question: "Which database?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}>(key: "database", question: {
    readonly question: "Which database?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}): OptionBuilder<Record<"database", {
    readonly question: "Which database?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}>>This type is a bit complex, but in usage, it's quite simple!
The idea is to add() options one by one, with the key and the question.
  .add('demo', {
    question: 'Do you want to add a demo?',
    type: 'boolean',  // string, number, select, multiselect
    default: true,
    // condition: (o) => o.previousOption === 'ok',
  })('database', {
		question(property) question: "Which database?": 'Which database?',
		type(property) type: "select": 'select',
		default(property) default: "postgresql": 'postgresql',
		options(property) options: [{
    readonly value: "postgresql";
}, {
    readonly value: "mysql";
}, {
    readonly value: "sqlite";
}]: [
			{ value(property) value: "postgresql": 'postgresql' },
			{ value(property) value: "mysql": 'mysql' },
			{ value(property) value: "sqlite": 'sqlite' }
		]
	})
	.add(method) add<"docker", {
    readonly question: "Add a docker-compose file?";
    readonly type: "boolean";
    readonly default: false;
    readonly condition: (opts: OptionValues<Record<"database", {
        readonly question: "Which database?";
        readonly type: "select";
        readonly default: "postgresql";
        readonly options: [{
            readonly value: "postgresql";
        }, {
            readonly value: "mysql";
        }, {
            readonly value: "sqlite";
        }];
    }> & Record<"docker", any>>) => boolean;
}>(key: "docker", question: {
    readonly question: "Add a docker-compose file?";
    readonly type: "boolean";
    readonly default: false;
    readonly condition: (opts: OptionValues<Record<"database", {
        readonly question: "Which database?";
        readonly type: "select";
        readonly default: "postgresql";
        readonly options: [{
            readonly value: "postgresql";
        }, {
            readonly value: "mysql";
        }, {
            readonly value: "sqlite";
        }];
    }> & Record<"docker", any>>) => boolean;
}): OptionBuilder<...>This type is a bit complex, but in usage, it's quite simple!
The idea is to add() options one by one, with the key and the question.
  .add('demo', {
    question: 'Do you want to add a demo?',
    type: 'boolean',  // string, number, select, multiselect
    default: true,
    // condition: (o) => o.previousOption === 'ok',
  })('docker', {
		question(property) question: "Add a docker-compose file?": 'Add a docker-compose file?',
		type(property) type: "boolean": 'boolean',
		default(property) default: false: false,
		// only ask when database is not sqlite		condition(property) condition: (opts: OptionValues<Record<"database", {
    readonly question: "Which database?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}> & Record<"docker", any>>) => boolean: (opts(parameter) opts: OptionValues<Record<"database", {
    readonly question: "Which database?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}> & Record<"docker", any>>) => opts(parameter) opts: OptionValues<Record<"database", {
    readonly question: "Which database?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}> & Record<"docker", any>>.database(property) database: "postgresql" | "mysql" | "sqlite" !== 'sqlite'
	})
	.build(method) build(): {
    database: {
        readonly question: "Which database?";
        readonly type: "select";
        readonly default: "postgresql";
        readonly options: [{
            readonly value: "postgresql";
        }, {
            readonly value: "mysql";
        }, {
            readonly value: "sqlite";
        }];
    };
    docker: {
        readonly question: "Add a docker-compose file?";
        readonly type: "boolean";
        readonly default: false;
        readonly condition: (opts: OptionValues<Record<"database", {
            readonly question: "Which database?";
            readonly type: "select";
            readonly default: "postgresql";
            readonly options: [{
                readonly value: "postgresql";
            }, {
                readonly value: "mysql";
            }, {
                readonly value: "sqlite";
            }];
        }> & Record<...>>) => boolean;
    };
}();

Options are asked in order. The condition callback receives the answers collected so far — return false to skip the question (its value will be undefined).

create

Programmatically create a new Svelte project.

import { create(alias) function create(options: Options): void (+1 overload)
import create } from 'sv';

create(alias) create(options: Options): void (+1 overload)
import createuse create({ cwd, ...options }) instead.
({
	cwd(property) cwd: string: './my-app',
	name(property) name: string: 'my-app',
	template(property) template: "minimal" | "demo" | "library" | "addon" | "svelte": 'minimal',
	types(property) types: "typescript" | "checkjs" | "none": 'typescript'
});

add

Programmatically run add-ons against an existing project.

import { add(alias) function add<Addons extends AddonMap>({ addons, cwd, options, packageManager }: InstallOptions<Addons>): Promise<ReturnType<({ loadedAddons, workspace, setupResults, options }: ApplyAddonOptions) => Promise<{
    filesToFormat: string[];
    status: Record<string, string[] | "success">;
}>>>
import add, officialAddons(alias) const officialAddons: OfficialAddons
import officialAddons } from 'sv';

await add(alias) add<{
    prettier: Addon<any, string, Record<string, unknown>>;
}>({ addons, cwd, options, packageManager }: InstallOptions<{
    prettier: Addon<any, string, Record<string, unknown>>;
}>): Promise<ReturnType<({ loadedAddons, workspace, setupResults, options }: ApplyAddonOptions) => Promise<{
    filesToFormat: string[];
    status: Record<string, string[] | "success">;
}>>>
import add({
	cwd(property) cwd: string: './my-app',
	addons(property) addons: {
    prettier: Addon<any, string, Record<string, unknown>>;
}: { prettier(property) prettier: Addon<any, string, Record<string, unknown>>: officialAddons(alias) const officialAddons: OfficialAddons
import officialAddons.prettier(property) prettier: Addon<any, string, Record<string, unknown>> },
	options(property) options: OptionMap<{
    prettier: Addon<any, string, Record<string, unknown>>;
}>: { prettier(property) prettier: {}: {} },
	packageManager(property) packageManager?: AgentName | undefined: 'npm'
});

Edit this page on GitHub llms.txt

previous next

[create your own] sv-utils