CLIAPI

sv

sv expose une API programmatique permettant de créer des projets et d’exécuter des add-ons.

defineAddon

Crée une définition d’add-on. Consultez la section créez le votre pour trouver un guide complet.

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(): {}(),

	// appelé avant l'exécution — déclarer des dépendances, des prérequis d'environnement et des options dynamiques
	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?
, isKit(parameter) isKit: boolean }) => {
		if (!isKit(parameter) isKit: boolean) unsupported(parameter) unsupported: (reason: string) => voidWhy is this addon not supported?
('Nécessite SvelteKit');
		dependsOn(parameter) dependsOn: (name: keyof OfficialAddons) => voidOn what official addons does this addon depend on?
('eslint');

		// ajoute dynamiquement des options (par ex. basé sur l'état du workspace ou des données récupérées)
		addOptionany('theme', {
			question(property) question: string: 'Which theme?',
			type(property) type: string: 'select',
			default(property) default: string: 'dark',
			options(property) options: {
    value: string;
}[]: [{ value(property) value: string: 'dark' }, { value(property) value: string: 'light' }]
		});
	},

	// le travail effectif — ajouter, modifier des fichiers, déclarer des dépendances
	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!
 }) => {
		// ajouter une dépendance
		sv(parameter) sv: SvApi.devDependency(property) devDependency: (pkg: string, version: string) => void('my-lib', '^1.0.0');

		// créer ou ajouter des fichiers en utilisant des transformations de @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>');
			})
		);

		// annuler à tout moment si quelque chose se passe mal
		// cancel('reason');
	},

	// affiché après l'exécution de l'add-on
	nextSteps(property) nextSteps?: ((workspace: Workspace & {
    options: OptionValues<{}> & Record<string, unknown>;
}) => string[]) | undefined: ({ options(parameter) options: OptionValues<{}> & Record<string, unknown> }) => ['Lancer `npm run dev` pour commencer']
});

L’objet sv dans run fournit file, dependency, devDependency, et execute. Pour les transformations (l’édition de scripts, de composants Svelte, de CSS, de JSON,... basée sur des AST), et les utilitaires de gestion de paquets, consultez @sveltejs/sv-utils.

Options typées dynamiques

Si votre add-on ajoute des options dynamiquement dans setup, (par ex, depuis un appel fetch), vous pouvez fournir un paramètre de type à defineAddon pour obtenir un typage fort pour ces 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: 'Quel thème ?',
			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
	}
});

Le paramètre de type fait correspondre le type (boolean, string, number) aux définitions des questions. Sans ce paramètre, defineAddon reste strict et autorise uniquement des options définies de manière statique.

defineAddonOptions

Permet de construire des options pour les add-ons. Chaîné avec .add() et finalisé par .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: "Quelle base de données ?";
        readonly type: "select";
        readonly default: "postgresql";
        readonly options: [{
            readonly value: "postgresql";
        }, {
            readonly value: "mysql";
        }, {
            readonly value: "sqlite";
        }];
    };
    docker: {
        readonly question: "Ajouter un fichier docker-compose ?";
        readonly type: "boolean";
        readonly default: false;
        readonly condition: (opts: OptionValues<Record<"database", {
            readonly question: "Quelle base de données ?";
            readonly type: "select";
            readonly default: "postgresql";
            readonly options: [{
                readonly value: "postgresql";
            }, {
                readonly value: "mysql";
            }, {
                ...;
            }];
        }> & 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: "Quelle base de données ?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}>(key: "database", question: {
    readonly question: "Quelle base de données ?";
    readonly type: "select";
    readonly default: "postgresql";
    readonly options: [{
        readonly value: "postgresql";
    }, {
        readonly value: "mysql";
    }, {
        readonly value: "sqlite";
    }];
}): OptionBuilder<Record<"database", {
    readonly question: "Quelle base de données ?";
    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: "Quelle base de données ?": 'Quelle base de données ?',
		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: "Ajouter un fichier docker-compose ?";
    readonly type: "boolean";
    readonly default: false;
    readonly condition: (opts: OptionValues<Record<"database", {
        readonly question: "Quelle base de données ?";
        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: "Ajouter un fichier docker-compose ?";
    readonly type: "boolean";
    readonly default: false;
    readonly condition: (opts: OptionValues<Record<"database", {
        readonly question: "Quelle base de données ?";
        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: "Ajouter un fichier docker-compose ?": 'Ajouter un fichier docker-compose ?',
		type(property) type: "boolean": 'boolean',
		default(property) default: false: false,
		// ne poser la question que lorsque la base de données n'est pas sqlite
		condition(property) condition: (opts: OptionValues<Record<"database", {
    readonly question: "Quelle base de données ?";
    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: "Quelle base de données ?";
    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: "Quelle base de données ?";
    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: "Quelle base de données ?";
        readonly type: "select";
        readonly default: "postgresql";
        readonly options: [{
            readonly value: "postgresql";
        }, {
            readonly value: "mysql";
        }, {
            readonly value: "sqlite";
        }];
    };
    docker: {
        readonly question: "Ajouter un fichier docker-compose ?";
        readonly type: "boolean";
        readonly default: false;
        readonly condition: (opts: OptionValues<Record<"database", {
            readonly question: "Quelle base de données ?";
            readonly type: "select";
            readonly default: "postgresql";
            readonly options: [{
                readonly value: "postgresql";
            }, {
                readonly value: "mysql";
            }, {
                ...;
            }];
        }> & Record<...>>) => boolean;
    };
}();

Les options sont posées dans l’ordre. Le callback condition reçoit les réponses collectées jusque là — renvoyez false pour éviter la question (sa valeur sera undefined).

create

Crée programmatiquement un nouveau projet Svelte.

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

Exécute programmatiquement des add-ons sur un projet existant.

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?: any: 'npm'
});

Modifier cette page sur Github llms.txt

précédent suivant

[créez le votre] sv-utils