CLIAdd-ons

[create your own]

This guide covers how to create, test, and publish community add-ons for the Svelte CLI.

Quick start

The easiest way to create an add-on is by using the addon template:

npx sv create --template addon [path]

The newly created project will have a README.md and CONTRIBUTING.md to guide you along.

Project structure

Typically, an add-on looks like this:

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 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 | false
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 add-on.
const addon = defineAddon({ id: 'my-addon', options, run });
If your add-on adds dynamic options via addOption during setup, pass their
types as a type argument:
const addon = defineAddon<{ extra: boolean }>()({ ... });
// Take note of the extra call here:         👆   👆
// This works around Typescript's lack of partial type arguments
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<"addon-name", {
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}>(config: Addon<{
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}, "addon-name", Record<string, unknown>>): Addon<{
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}, "addon-name", Record<string, unknown>> (+1 overload)
import defineAddonThe entry point for your add-on.
const addon = defineAddon({ id: 'my-addon', options, run });
If your add-on adds dynamic options via addOption during setup, pass their
types as a type argument:
const addon = defineAddon<{ extra: boolean }>()({ ... });
// Take note of the extra call here:         👆   👆
// This works around Typescript's lack of partial type arguments
addon.options.extra.default; // boolean({
	id(property) id: "addon-name": 'addon-name',

	shortDescription(property) shortDescription?: string | undefined: 'a better description of what your addon does ;)',

	options(property) options: {
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}: 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<"who", Question<Record<"who", {
    readonly question: "To whom should the addon say hello?";
    readonly type: "string";
}>>>(key: "who", question: Question<Record<"who", {
    readonly question: "To whom should the addon say hello?";
    readonly type: "string";
}>>): OptionBuilder<Record<"who", Question<Record<"who", {
    readonly question: "To whom should the addon say hello?";
    readonly type: "string";
}>>>>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',
  })('who', {
			question(property) question: string: 'To whom should the addon say hello?',
			type(property) type: "string": 'string' // boolean | number | select | multiselect
		})
		.build(method) build(): {
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}(),

	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?
, isKit(parameter) isKit: boolean, 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 }) => {
		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?
('vitest');

		// dynamically add options (e.g. based on workspace state or fetched data)
		// addOption('key', { question: '...', type: 'boolean', default: true });
	},

	run(property) run: (workspace: Workspace & {
    options: OptionValues<{
        who: Question<Record<"who", {
            readonly question: "To whom should the addon say hello?";
            readonly type: "string";
        }>>;
    }> & Record<string, unknown>;
    sv: SvApi;
    cancel: (reason: string) => void;
}) => MaybePromise<void>: ({ isKit(parameter) isKit: boolean, cancel(parameter) cancel: (reason: string) => voidCancel the addon at any time!
, sv(parameter) sv: SvApi, options(parameter) options: OptionValues<{
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}> & Record<string, unknown>Add-on options (includes dynamically added options from setup)
, file(parameter) file: {
    viteConfig: "vite.config.js" | "vite.config.ts";
    typeConfig: "jsconfig.json" | "tsconfig.json" | undefined;
    stylesheet: `${string}/layout.css` | "src/app.css";
    package: "package.json";
    gitignore: ".gitignore";
    getRelative: ({ from, to }: {
        from?: string;
        to: string;
    }) => string;
    findUp: (filename: string) => string;
}, language(parameter) language: "ts" | "js", directory(parameter) directory: {
    src: string;
    lib: string;
    kitRoutes: string;
} }) => {
		// Add "Hello [who]!" to the root page
		sv(parameter) sv: SvApi.file(property) file: (path: string, edit: FileEdit) => 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.
(
			directory(parameter) directory: {
    src: string;
    lib: string;
    kitRoutes: string;
}.kitRoutes(property) kitRoutes: string + '/+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): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 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 | false
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): TransformFnTransform a Svelte component file.
Return false from the callback to abort.
(({ 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 ${options(parameter) options: OptionValues<{
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}> & Record<string, unknown>Add-on options (includes dynamically added options from setup)
.who(property) who: unknown}!</p>`);
			})
		);
	},

	nextSteps(property) nextSteps?: ((workspace: Workspace & {
    options: OptionValues<{
        who: Question<Record<"who", {
            readonly question: "To whom should the addon say hello?";
            readonly type: "string";
        }>>;
    }> & Record<string, unknown>;
}) => string[]) | undefined: ({ options(parameter) options: OptionValues<{
    who: Question<Record<"who", {
        readonly question: "To whom should the addon say hello?";
        readonly type: "string";
    }>>;
}> & Record<string, unknown> }) => ['enjoy the add-on!']
});

The CLI is split into two packages with a clear boundary:

sv = where and when to do it. It owns paths, workspace detection, dependency tracking, and file I/O. The engine orchestrates add-on execution.
@sveltejs/sv-utils = what to do to content. It provides parsers, language tooling, and typed transforms. Everything here is pure - no file system, no workspace awareness.

This separation means transforms are testable without a workspace and composable across add-ons.

Development

You can run your add-on locally using the file: protocol:

cd /path/to/test-project
npx sv add file:../path/to/my-addon

This allows you to iterate quickly without publishing to npm.

The file: protocol also works for custom or private add-ons that you don’t intend to publish - for example, to standardize project setup across your team or organization.

The demo-add script automatically builds your add-on before running it.

Testing

The sv/testing module provides utilities for testing your add-on. createSetupTest is a factory that takes your vitest imports and returns a setupTest function. It creates real SvelteKit projects from templates, runs your add-on, and gives you access to the resulting files.

import { expectimport expect } from '@playwright/test';
import fs(alias) module "node:fs"
import fs from 'node:fs';
import path(alias) namespace path
(alias) const path: path.PlatformPath
import path from 'node:path';
import { createSetupTest(alias) function createSetupTest(vitest: VitestContext, playwright?: PlaywrightContext): <Addons extends AddonMap>(addons: Addons, options?: SetupTestOptions<Addons>) => {
    test: vitest.TestAPI<Fixtures>;
    testCases: Array<AddonTestCase<AddonMap>>;
    prepareServer: typeof prepareServer;
}
import createSetupTest } from 'sv/testing';
import * as vitestimport vitest from 'vitest';
import addonimport addon from './index.js';

const { testconst test: vitest.TestAPI<Fixtures>, testCasesconst testCases: AddonTestCase<AddonMap>[] } = createSetupTest(alias) createSetupTest(vitest: VitestContext, playwright?: PlaywrightContext): <Addons extends AddonMap>(addons: Addons, options?: SetupTestOptions<Addons>) => {
    test: vitest.TestAPI<Fixtures>;
    testCases: Array<AddonTestCase<AddonMap>>;
    prepareServer: typeof prepareServer;
}
import createSetupTest(vitestimport vitest)(
	{ addon(property) addon: any },
	{
		kinds(property) kinds: {
    type: string;
    options: OptionMap<{
        addon: any;
    }>;
}[]: [
			{
				type(property) type: string: 'default',
				options(property) options: OptionMap<{
    addon: any;
}>: {
					'your-addon-name': { who(property) who: string: 'World' }
				}
			}
		],
		filter(property) filter?: ((addonTestCase: AddonTestCase<{
    addon: any;
}>) => boolean) | undefined: (testCase(parameter) testCase: AddonTestCase<{
    addon: any;
}>) => testCase(parameter) testCase: AddonTestCase<{
    addon: any;
}>.variant(property) variant: ProjectVariant.includes(method) String.includes(searchString: string, position?: number): booleanReturns true if searchString appears as a substring of the result of converting this
object to a String, at one or more positions that are
greater than or equal to position; otherwise, returns false.
searchString search string
position If position is undefined, 0 is assumed, so as to search all of the String.
('kit'),
		browser(property) browser?: boolean | undefined: false
	}
);

testconst test: vitest.TestAPI<Fixtures>.concurrent(property) concurrent: TypedChainableFunction<ChainableTestContextMap, TestCollectorCallable<Fixtures>, {
    each: TestEachFunction;
    for: TestForFunction<Fixtures>;
}>Whether suites and tests run concurrently.
Tests inherit concurrent from describe() and nested describe() will inherit from parent's concurrent.
.for(property) for: TestForFunction
<AddonTestCase<AddonMap>>(cases: readonly AddonTestCase<AddonMap>[]) => TestForFunctionReturn<AddonTestCase<AddonMap>, vitest.TestContext & Fixtures> (+1 overload)(testCasesconst testCases: AddonTestCase<AddonMap>[])('my-addon $kind.type $variant', async (testCase(parameter) testCase: AddonTestCase<AddonMap>, ctx(parameter) ctx: vitest.TestContext & Fixtures) => {
	const cwdconst cwd: string = ctx(parameter) ctx: vitest.TestContext & Fixtures.cwd(method) cwd(addonTestCase: AddonTestCase<any>): string(testCase(parameter) testCase: AddonTestCase<AddonMap>);

	const pageconst page: string = fs(alias) module "node:fs"
import fs.readFileSyncfunction readFileSync(path: fs.PathOrFileDescriptor, options: fs.ReadFileSyncOptionsWithStringEncoding | BufferEncoding): string (+3 overloads)Returns the contents of the path.
For detailed information, see the documentation of the asynchronous version of
this API: fs.readFile().
If the encoding option is specified then this function returns a
string. Otherwise it returns a buffer.
If buffer is provided and no encoding is specified, the returned {Buffer} is
a view over the supplied buffer containing only the bytes read. If the
supplied buffer is too small to contain the entire file, an error will be
thrown.
Similar to fs.readFile(), when the path is a directory, the behavior of
fs.readFileSync() is platform-specific.
import { readFileSync } from 'node:fs';

// macOS, Linux, and Windows
readFileSync('<directory>');
// => [Error: EISDIR: illegal operation on a directory, read <directory>]

//  FreeBSD
readFileSync('<directory>'); // => <data>v0.1.8
path filename or file descriptor
(path(alias) namespace path
(alias) const path: path.PlatformPath
import path.resolve(method) path.PlatformPath.resolve(...paths: string[]): stringThe right-most parameter is considered {to}. Other parameters are considered an array of {from}.
Starting from leftmost {from} parameter, resolves {to} to an absolute path.
If {to} isn't already absolute, {from} arguments are prepended in right to left order,
until an absolute path is found. If after using all {from} paths still no absolute path is found,
the current working directory is used as well. The resulting path is normalized,
and trailing slashes are removed unless the path gets resolved to the root directory.
paths A sequence of paths or path segments.
{TypeError} if any of the arguments is not a string.
(cwdconst cwd: string, 'src/routes/+page.svelte'), 'utf8');
	expectimport expect(pageconst page: string).toContainany('Hello World!');
});

Your vitest.config.js must include the global setup from sv/testing:

import { defineConfig(alias) function defineConfig(config: UserConfig): UserConfig (+4 overloads)
import defineConfig } from 'vitest/config';

export default defineConfig(alias) defineConfig(config: UserConfig): UserConfig (+4 overloads)
import defineConfig({
	test(property) UserConfig.test?: InlineConfig | undefinedOptions for Vitest
: {
		include(property) InlineConfig.include?: string[] | undefinedA list of glob patterns that match your test files.
['**/*.{test,spec}.?(c|m)[jt]s?(x)']
{@link https://vitest.dev/config/include}
: ['tests/**/*.test.{js,ts}'],
		globalSetup(property) InlineConfig.globalSetup?: string | string[] | undefinedPath to global setup files
: ['tests/setup/global.js']
	}
});

And the global test setup script tests/setup/global.js:

import path(alias) namespace path
(alias) const path: path.PlatformPath
import path from 'node:path';
import { setupGlobal(alias) function setupGlobal({ TEST_DIR, pre, post }: {
    TEST_DIR: string;
    pre?: () => Promise<void>;
    post?: () => Promise<void>;
}): ({ provide }: TestProject) => Promise<() => Promise<void>>
import setupGlobal } from 'sv/testing';
// test projects are scaffolded into `<project-root>/.test-output`
const TEST_DIRconst TEST_DIR: string = path(alias) namespace path
(alias) const path: path.PlatformPath
import path.resolve(method) path.PlatformPath.resolve(...paths: string[]): stringThe right-most parameter is considered {to}. Other parameters are considered an array of {from}.
Starting from leftmost {from} parameter, resolves {to} to an absolute path.
If {to} isn't already absolute, {from} arguments are prepended in right to left order,
until an absolute path is found. If after using all {from} paths still no absolute path is found,
the current working directory is used as well. The resulting path is normalized,
and trailing slashes are removed unless the path gets resolved to the root directory.
paths A sequence of paths or path segments.
{TypeError} if any of the arguments is not a string.
(import.metaThe type of import.meta.
If you need to declare that a given property exists on import.meta,
this type may be augmented via interface merging.
.dirname(property) ImportMeta.dirname: stringThe directory name of the current module.
This is the same as the path.dirname() of the import.meta.filename.

Caveat: only present on file: modules.

v21.2.0, v20.11.0
, '..', '..', '.test-output');

export default setupGlobal(alias) setupGlobal({ TEST_DIR, pre, post }: {
    TEST_DIR: string;
    pre?: () => Promise<void>;
    post?: () => Promise<void>;
}): ({ provide }: TestProject) => Promise<() => Promise<void>>
import setupGlobal({ TEST_DIR(property) TEST_DIR: string });

Publishing

Bundling

Community add-ons are bundled with tsdown into a single file. Everything is bundled except sv. (It is a peer dependency provided at runtime.)

sv ships its own copy of @sveltejs/sv-utils, so an add-on that leaves it unbundled will still load. Nothing verifies the version: your add-on runs against whatever sv provides, and following its breaking changes is up to you. Bundle it to stay on a version you control.

package.json

Your add-on must have sv as a peer dependency. Any dependencies declared will not be available at runtime, everything must be bundled:

{
	"name": "@my-org/sv",
	"version": "1.0.0",
	"type": "module",
	// bundled entry point (tsdown outputs .mjs for ESM)
	"exports": {
		".": { "default": "./dist/index.mjs" }
	},
	"publishConfig": {
		"access": "public"
	},
	// packages declared here will not be available during runtime, it must be bundled
	"dependencies": {},
	"peerDependencies": {
		// minimum version required to run by this add-on
		"sv": "^0.13.0"
	},
	// Add the "sv-add" keyword so users can discover your add-on with https://www.npmx.dev/search?q=keyword:sv-add
	"keywords": ["sv-add", "svelte", "sveltekit"]
}

Package names

Naming follows the same restrictions as on npm:

npx sv add my-addon
npx sv add @my-org/sv
npx sv add @my-org/foo

An add-on published as @<org>/sv can also be installed as @<org>. The following all resolve to the same package:

npx sv add @my-org
npx sv add @my-org/sv
npx sv add @my-org/sv@latest

For a specific version, append @<semver>:

npx sv add @my-org/sv@1.2.3
npx sv add my-addon@1.2.3

Entry points

The CLI looks for ./sv first. If that is not found, it defaults to the . entry point. This means you have two options:

Default export (for a dedicated add-on package):

{
	"name": "@my-org/sveltekit-addon",
	"exports": {
		".": "./dist/addon.mjs"
	}
}

./sv export (for packages that also export other functionality):

{
	"name": "@my-org/sveltekit-addon",
	"exports": {
		".": "./dist/main.mjs",
		"./sv": "./dist/addon.mjs"
	}
}

Publish to npm

npm login
npm publish

prepublishOnly automatically runs the build before publishing.

Next steps

You can optionally display guidance in the console after your add-on runs:

import { color(alias) const color: {
    addon: (str: ColorInput) => string;
    command: (str: ColorInput) => string;
    env: (str: ColorInput) => string;
    path: (str: ColorInput) => string;
    route: (str: ColorInput) => string;
    website: (str: ColorInput) => string;
    optional: (str: ColorInput) => string;
    dim: (str: ColorInput) => string;
    success: (str: ColorInput) => string;
    warning: (str: ColorInput) => string;
    error: (str: ColorInput) => string;
    hidden: (str: ColorInput) => string;
}
import color } from '@sveltejs/sv-utils';

export default defineAddonany({
	// ...

	nextSteps(property) nextSteps: ({ options }: {
    options: any;
}) => string[]: ({ options(parameter) options: any }) => [
		`Run ${color(alias) const color: {
    addon: (str: ColorInput) => string;
    command: (str: ColorInput) => string;
    env: (str: ColorInput) => string;
    path: (str: ColorInput) => string;
    route: (str: ColorInput) => string;
    website: (str: ColorInput) => string;
    optional: (str: ColorInput) => string;
    dim: (str: ColorInput) => string;
    success: (str: ColorInput) => string;
    warning: (str: ColorInput) => string;
    error: (str: ColorInput) => string;
    hidden: (str: ColorInput) => string;
}
import color.command(property) command: (str: ColorInput) => string('npm run dev')} to start developing`,
		`Check out the docs at https://...`
	]
});

Version compatibility

Your add-on should specify a minimum sv version in peerDependencies. Your users will get a compatibility warning if their sv version has a different major version than what was specified.

Examples

See the official add-on source code for some real world examples.

Edit this page on GitHub llms.txt

previous next

vitest sv