From bb646a660245829ac273321049ac326f3729c146 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 19:09:59 +0200
Subject: [PATCH 01/29] feat: community add-ons

---
 documentation/docs/20-commands/20-sv-add.md   |  25 ++
 documentation/docs/30-add-ons/99-community.md | 216 +++++++++++++++++
 documentation/docs/50-api/20-sv-utils.md      | 227 ++++++++++++++++++
 3 files changed, 468 insertions(+)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 7c0b56ada..d8fc782e8 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -63,3 +63,28 @@ Prevents installing dependencies
 - [`tailwindcss`](tailwind)
 - [`vitest`](vitest)
 
+## Community add-ons
+
+> [!NOTE]
+> Community add-ons are currently **experimental**. The API may change. Don't use them in production yet!
+
+> [!NOTE]
+> Svelte maintainers have not reviewed community add-ons for malicious code!
+
+Community add-ons are npm packages published by the community. Look out for add-ons from your favorite libraries and tools. _(soon)_ many are building `sv` add-ons to make integration a one-liner. You can find them [on npm](https://www.npmx.dev/search?q=keyword:sv-add) by searching for keyword: `sv-add`.
+
+```sh
+# Install a community add-on by org
+npx sv add @supacool
+
+# Use a local add-on (for development or custom/private add-ons)
+npx sv add file:../path/to/my-addon
+
+# Mix and match official and community add-ons
+npx sv add eslint @supacool
+
+# Also works when creating a new project directly
+npx sv create --add eslint @supacool
+```
+
+Want to create your own? Check the [Add-on Docs](community).
diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 4e7823093..438d25fca 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -2,5 +2,221 @@
 title: [create your own]
 ---
 
+> [!NOTE]
+> Community add-ons are currently **experimental**. The API may change. Don't use them in production yet!
 
+This guide covers how to create, test, and publish community add-ons for `sv`.
 
+## Quick start
+
+The easiest way to create an add-on is using the `addon` template:
+
+```sh
+npx sv create --template addon [path]
+```
+
+The project has a `README.md` and `CONTRIBUTING.md` to guide you along.
+
+## Project structure
+
+Typically, an add-on looks like this:
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+import { defineAddon, defineAddonOptions } from 'sv';
+
+// your add-on definition, the entry point
+export default defineAddon({
+	id: 'your-addon-name',
+
+	// optional: one-liner shown in prompts
+	shortDescription: 'does X',
+
+	// optional: link to docs/repo
+	homepage: 'https://...',
+
+	// Define options for user prompts (or passed as arguments)
+	options: defineAddonOptions()
+		.add('who', {
+			question: 'To whom should the addon say hello?',
+			type: 'string' // boolean | number | select | multiselect
+		})
+		.build(),
+
+	// preparing step, check requirements and dependencies
+	setup: ({ dependsOn }) => {
+		dependsOn('tailwindcss');
+	},
+
+	// actual execution of the addon
+	run: ({ isKit, cancel, sv, options, directory }) => {
+		if (!isKit) return cancel('SvelteKit is required');
+
+		// Add "Hello [who]!" to the root page
+		sv.file(
+			directory.kitRoutes + '/+page.svelte',
+			transforms.svelte(({ ast, svelte }) => {
+				svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
+			})
+		);
+	}
+});
+```
+
+> `sv` is responsible for the file system - `sv.file()` accepts a `path` to the file and a callback function to modify it.
+> `@sveltejs/sv-utils` is responsible for the content - `transforms.svelte()` provides you with the proper AST and utils to modify the file. See [sv-utils](/docs/cli/sv-utils) for the full API.
+
+## Development
+
+You can run your add-on locally using the `file:` protocol:
+
+```sh
+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.
+
+> [!NOTE]
+> It is not necessary to build your add-on during development.
+
+## Testing
+
+The `sv/testing` module provides utilities for testing your add-on:
+
+```js
+import { setupTest } from 'sv/testing';
+import { test, expect } from 'vitest';
+import addon from './index.js';
+
+test('adds hello message', async () => {
+	const { content } = await setupTest({
+		addon,
+		options: { who: 'World' },
+		files: {
+			'src/routes/+page.svelte': '<h1>Welcome</h1>'
+		}
+	});
+
+	expect(content('src/routes/+page.svelte')).toContain('Hello World!');
+});
+```
+
+## Publishing
+
+### Bundling
+
+Community add-ons are bundled with [tsdown](https://tsdown.dev/) into a single file. Everything is bundled except `sv`. (It is a peer dependency provided at runtime.)
+
+### `package.json`
+
+Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `package.json`:
+
+```jsonc
+{
+	"name": "@your-org/sv",
+	"version": "1.0.0",
+	"type": "module",
+	// entrypoint during development
+	"exports": {
+		".": "./src/index.js"
+	},
+	"publishConfig": {
+		"access": "public",
+		// entrypoint on build
+		"exports": {
+			".": { "default": "./dist/index.js" }
+		}
+	},
+	// cannot have dependencies
+	"dependencies": {},
+	"peerDependencies": {
+		// minimum version required to run by this addon
+		"sv": "^0.13.0"
+	},
+	// Add this keyword so users can discover your add-on
+	"keywords": ["sv-add"]
+}
+```
+
+### Naming convention
+
+Name your package `@your-org/sv`. Users install it by typing just the org:
+
+```sh
+# npm package: @your-org/sv
+npx sv add @your-org
+```
+
+> [!NOTE]
+> Unscoped packages are not supported yet
+
+### Export options
+
+`sv` first tries to import `your-package/sv`, then falls back to the default export. This means you have two options:
+
+1. **Default export** (recommended for dedicated add-on packages):
+
+   ```json
+   {
+   	"exports": {
+   		".": "./src/index.js"
+   	}
+   }
+   ```
+
+2. **`./sv` export** (for packages that also export other functionality):
+   ```json
+   {
+   	"exports": {
+   		".": "./src/main.js",
+   		"./sv": "./src/addon.js"
+   	}
+   }
+   ```
+
+### Publish to npm
+
+```sh
+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:
+
+```js
+// @noErrors
+import { color } from '@sveltejs/sv-utils';
+
+export default defineAddon({
+	// ...
+	nextSteps: ({ options }) => [
+		`Run ${color.command('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 user 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](https://github.com/sveltejs/cli/tree/main/packages/sv/src/addons) for some real world examples.
+
+## Architecture
+
+The Svelte 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.
diff --git a/documentation/docs/50-api/20-sv-utils.md b/documentation/docs/50-api/20-sv-utils.md
index 5e364bd61..4a714618d 100644
--- a/documentation/docs/50-api/20-sv-utils.md
+++ b/documentation/docs/50-api/20-sv-utils.md
@@ -2,3 +2,230 @@
 title: sv-utils
 ---
 
+> [!NOTE]
+> `@sveltejs/sv-utils` is currently **experimental**. The API may change. Full documentation is not yet available.
+
+`@sveltejs/sv-utils` is an add-on utilty for parsing, transforming, and generating code..
+
+```sh
+npm install -D @sveltejs/sv-utils
+```
+
+## transforms
+
+`transforms` is a collection of parser-aware functions that lets you modify the files via abstract syntax tree (AST). It accepts a callback function. The return value is designed to be be passed directly into `sv.file()`. 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.
+
+Each transform injects relevant utilities into the callback, so you only need one import:
+
+```js
+import { transforms } from '@sveltejs/sv-utils';
+
+transforms.script(/* ... */);
+transforms.svelte(/* ... */);
+// ...
+```
+
+### `transforms.script`
+
+Transform a JavaScript/TypeScript file. The callback receives `{ ast, comments, content, js }`.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	files.viteConfig,
+	transforms.script(({ ast, js }) => {
+		js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
+		js.vite.addPlugin(ast, { code: 'foo()' });
+	})
+);
+```
+
+### `transforms.svelte`
+
+Transform a Svelte component. The callback receives `{ ast, content, svelte, js }`.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	layoutPath,
+	transforms.svelte(({ ast, svelte }) => {
+		svelte.addFragment(ast, '<Foo />');
+	})
+);
+```
+
+### `transforms.svelteScript`
+
+Transform a Svelte component with a `<script>` block guaranteed. Pass `{ language }` as the first argument. The callback receives `{ ast, content, svelte, js }` where `ast.instance` is always non-null.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	layoutPath,
+	transforms.svelteScript({ language: 'ts' }, ({ ast, svelte, js }) => {
+		js.imports.addDefault(ast.instance.content, { as: 'Foo', from: './Foo.svelte' });
+		svelte.addFragment(ast, '<Foo />');
+	})
+);
+```
+
+### `transforms.css`
+
+Transform a CSS file. The callback receives `{ ast, content, css }`.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	files.stylesheet,
+	transforms.css(({ ast, css }) => {
+		css.addAtRule(ast, { name: 'import', params: "'tailwindcss'" });
+	})
+);
+```
+
+### `transforms.json`
+
+Transform a JSON file. Mutate the `data` object directly. The callback receives `{ data, content, json }`.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	files.tsconfig,
+	transforms.json(({ data }) => {
+		data.compilerOptions ??= {};
+		data.compilerOptions.strict = true;
+	})
+);
+```
+
+### `transforms.yaml` / `transforms.toml`
+
+Same pattern as `transforms.json`, for YAML and TOML files respectively. The callback receives `{ data, content }`.
+
+### `transforms.text`
+
+Transform a plain text file (.env, .gitignore, etc.). No parser - string in, string out. The callback receives `{ content, text }`.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	'.env',
+	transforms.text(({ content }) => {
+		return content + '\nDATABASE_URL="file:local.db"';
+	})
+);
+```
+
+### Aborting a transform
+
+Return `false` from any transform callback to abort - the original content is returned unchanged.
+
+```js
+// @noErrors
+import { transforms } from '@sveltejs/sv-utils';
+
+sv.file(
+	files.eslintConfig,
+	transforms.script(({ ast, js }) => {
+		const { value: existing } = js.exports.createDefault(ast, { fallback: myConfig });
+		if (existing !== myConfig) {
+			// config already exists, don't touch it
+			return false;
+		}
+		// ... continue modifying ast
+	})
+);
+```
+
+### Standalone usage & testing
+
+Transforms are curried functions - call them with the callback, then apply to content:
+
+```js
+import { transforms } from '@sveltejs/sv-utils';
+
+const transform = transforms.script(({ ast, js }) => {
+	js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
+});
+const result = transform('export default {}');
+```
+
+### Composability
+
+For cases where you need to mix and match transforms and raw edits, use `sv.file` with a content callback and invoke the curried transform manually:
+
+```js
+// @noErrors
+sv.file(path, (content) => {
+	// curried
+	const transform = transforms.script(({ ast, js }) => {
+		js.imports.addDefault(ast, { as: 'foo', from: 'bar' });
+	});
+
+	// parser manipulation
+	content = transform(content);
+
+	// raw string manipulation
+	content = content.replace('foo', 'baz');
+
+	return content;
+});
+```
+
+Add-ons can also export reusable transform functions:
+
+```js
+// @errors: 7006
+import { transforms } from '@sveltejs/sv-utils';
+
+// reusable - export from your package
+export const addFooImport = transforms.svelte(({ ast, svelte, js }) => {
+	svelte.ensureScript(ast, { language });
+	js.imports.addDefault(ast.instance.content, { as: 'Foo', from: './Foo.svelte' });
+});
+```
+
+```js
+sv.file('+page.svelte', addFooImport);
+sv.file('index.svelte', addFooImport);
+```
+
+## Parsers (low-level)
+
+`transforms` will fit most users needs (e.g., conditional parsing, error handling around the parser). If not, `parse` is a low-level API available to you:
+
+```js
+// @noErrors
+import { parse } from '@sveltejs/sv-utils';
+
+const { ast, generateCode } = parse.script(content);
+const { ast, generateCode } = parse.svelte(content);
+const { ast, generateCode } = parse.css(content);
+const { data, generateCode } = parse.json(content);
+const { data, generateCode } = parse.yaml(content);
+const { data, generateCode } = parse.toml(content);
+const { ast, generateCode } = parse.html(content);
+```
+
+## Language tooling
+
+Namespaced helpers for AST manipulation:
+
+- **`js.*`** - imports, exports, objects, arrays, variables, functions, vite config helpers, SvelteKit helpers
+- **`css.*`** - rules, declarations, at-rules, imports
+- **`svelte.*`** - ensureScript, addSlot, addFragment
+- **`json.*`** - arrayUpsert, packageScriptsUpsert
+- **`html.*`** - attribute manipulation
+- **`text.*`** - upsert lines in flat files (.env, .gitignore)

From 70cacaf421785f33bcca6b0a9caeecb09fbd402a Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 19:12:19 +0200
Subject: [PATCH 02/29] add changeset

---
 .changeset/some-rings-appear.md          | 6 ++++++
 documentation/docs/50-api/20-sv-utils.md | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/some-rings-appear.md

diff --git a/.changeset/some-rings-appear.md b/.changeset/some-rings-appear.md
new file mode 100644
index 000000000..249478187
--- /dev/null
+++ b/.changeset/some-rings-appear.md
@@ -0,0 +1,6 @@
+---
+'sv': minor
+'@sveltejs/sv-utils': minor
+---
+
+feat: community add-ons are now **experimental**
diff --git a/documentation/docs/50-api/20-sv-utils.md b/documentation/docs/50-api/20-sv-utils.md
index 4a714618d..f3c8776cc 100644
--- a/documentation/docs/50-api/20-sv-utils.md
+++ b/documentation/docs/50-api/20-sv-utils.md
@@ -3,7 +3,7 @@ title: sv-utils
 ---
 
 > [!NOTE]
-> `@sveltejs/sv-utils` is currently **experimental**. The API may change. Full documentation is not yet available.
+> `@sveltejs/sv-utils` is currently **experimental**. The API may change.
 
 `@sveltejs/sv-utils` is an add-on utilty for parsing, transforming, and generating code..
 

From 60faa612b407c6a7a31e08c62173e3e552b8025a Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 19:22:02 +0200
Subject: [PATCH 03/29] note for windows users

---
 documentation/docs/20-commands/20-sv-add.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index d8fc782e8..96551daed 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -87,4 +87,7 @@ npx sv add eslint @supacool
 npx sv create --add eslint @supacool
 ```
 
+> [!NOTE]
+> On Windows, quote community add-ons that start with `@`, for example: `npx sv add "@supacool"`.
+
 Want to create your own? Check the [Add-on Docs](community).

From ec0bc1cd5f21b8ce0a36e741cad3890ffea9c9c6 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 19:36:26 +0200
Subject: [PATCH 04/29] adding tests doc

---
 documentation/docs/30-add-ons/99-community.md | 70 +++++++++++++++----
 documentation/docs/50-api/20-sv-utils.md      |  8 +--
 2 files changed, 61 insertions(+), 17 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 438d25fca..c6178417a 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -50,7 +50,7 @@ export default defineAddon({
 	},
 
 	// actual execution of the addon
-	run: ({ isKit, cancel, sv, options, directory }) => {
+	run: ({ isKit, cancel, sv, options, file, language, directory }) => {
 		if (!isKit) return cancel('SvelteKit is required');
 
 		// Add "Hello [who]!" to the root page
@@ -85,26 +85,70 @@ The `file:` protocol also works for custom or private add-ons that you don't int
 
 ## Testing
 
-The `sv/testing` module provides utilities for testing your add-on:
+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.
 
 ```js
-import { setupTest } from 'sv/testing';
-import { test, expect } from 'vitest';
+import { createSetupTest } from 'sv/testing';
+import { expect } from '@playwright/test';
+import * as vitest from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
 import addon from './index.js';
 
-test('adds hello message', async () => {
-	const { content } = await setupTest({
-		addon,
-		options: { who: 'World' },
-		files: {
-			'src/routes/+page.svelte': '<h1>Welcome</h1>'
-		}
-	});
+const { test, testCases } = createSetupTest(vitest)(
+	{ addon },
+	{
+		kinds: [
+			{
+				type: 'default',
+				options: {
+					'your-addon-name': { who: 'World' }
+				}
+			}
+		],
+		filter: (testCase) => testCase.variant.includes('kit'),
+		browser: false
+	}
+);
+
+test.concurrent.for(testCases)(
+	'my-addon $kind.type $variant',
+	async (testCase, ctx) => {
+		const cwd = ctx.cwd(testCase);
 
-	expect(content('src/routes/+page.svelte')).toContain('Hello World!');
+		const page = fs.readFileSync(
+			path.resolve(cwd, 'src/routes/+page.svelte'),
+			'utf8'
+		);
+		expect(page).toContain('Hello World!');
+	}
+);
+```
+
+Your `vitest.config.js` must include the global setup from `sv/testing`:
+
+```js
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+	test: {
+		include: ['tests/**/*.test.{js,ts}'],
+		globalSetup: ['tests/setup/global.js']
+	}
 });
 ```
 
+And create `tests/setup/global.js`:
+
+```js
+import { fileURLToPath } from 'node:url';
+import { setupGlobal } from 'sv/testing';
+
+const TEST_DIR = fileURLToPath(new URL('../../.test-output/', import.meta.url));
+
+export default setupGlobal({ TEST_DIR });
+```
+
 ## Publishing
 
 ### Bundling
diff --git a/documentation/docs/50-api/20-sv-utils.md b/documentation/docs/50-api/20-sv-utils.md
index f3c8776cc..600ca9a0c 100644
--- a/documentation/docs/50-api/20-sv-utils.md
+++ b/documentation/docs/50-api/20-sv-utils.md
@@ -34,7 +34,7 @@ Transform a JavaScript/TypeScript file. The callback receives `{ ast, comments,
 import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
-	files.viteConfig,
+	file.viteConfig,
 	transforms.script(({ ast, js }) => {
 		js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
 		js.vite.addPlugin(ast, { code: 'foo()' });
@@ -84,7 +84,7 @@ Transform a CSS file. The callback receives `{ ast, content, css }`.
 import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
-	files.stylesheet,
+	file.stylesheet,
 	transforms.css(({ ast, css }) => {
 		css.addAtRule(ast, { name: 'import', params: "'tailwindcss'" });
 	})
@@ -100,7 +100,7 @@ Transform a JSON file. Mutate the `data` object directly. The callback receives
 import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
-	files.tsconfig,
+	file.typeConfig,
 	transforms.json(({ data }) => {
 		data.compilerOptions ??= {};
 		data.compilerOptions.strict = true;
@@ -137,7 +137,7 @@ Return `false` from any transform callback to abort - the original content is re
 import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
-	files.eslintConfig,
+	file.eslintConfig,
 	transforms.script(({ ast, js }) => {
 		const { value: existing } = js.exports.createDefault(ast, { fallback: myConfig });
 		if (existing !== myConfig) {

From ada56fe64cc3ef5702cfbf9617abf509367836ba Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 20:04:31 +0200
Subject: [PATCH 05/29] fix to accommodate npm (not pnpm)

---
 documentation/docs/30-add-ons/99-community.md       | 12 ++++--------
 .../src/cli/tests/snapshots/@my-org/sv/package.json | 13 ++++---------
 .../create/templates/addon/package.template.json    | 13 ++++---------
 3 files changed, 12 insertions(+), 26 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index c6178417a..9c6a78e49 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -81,7 +81,7 @@ 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.
 
 > [!NOTE]
-> It is not necessary to build your add-on during development.
+> The `demo-add` script automatically builds your add-on before running it.
 
 ## Testing
 
@@ -164,16 +164,12 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 	"name": "@your-org/sv",
 	"version": "1.0.0",
 	"type": "module",
-	// entrypoint during development
+	// bundled entrypoint (tsdown outputs .mjs for ESM)
 	"exports": {
-		".": "./src/index.js"
+		".": { "default": "./dist/index.mjs" }
 	},
 	"publishConfig": {
-		"access": "public",
-		// entrypoint on build
-		"exports": {
-			".": { "default": "./dist/index.js" }
-		}
+		"access": "public"
 	},
 	// cannot have dependencies
 	"dependencies": {},
diff --git a/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json b/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json
index 03ae9cd99..b2612863b 100644
--- a/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json
+++ b/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json
@@ -6,8 +6,8 @@
 	"license": "MIT",
 	"scripts": {
 		"demo-create": "sv create demo --types ts --template minimal --no-add-ons --no-install",
-		"demo-add": "sv add file:../ --cwd demo --no-git-check --no-install",
-		"demo-add:ci": "sv add file:../=who:you --cwd demo --no-git-check --no-download-check --no-install",
+		"demo-add": "pnpm build && sv add file:../ --cwd demo --no-git-check --no-install",
+		"demo-add:ci": "pnpm build && sv add file:../=who:you --cwd demo --no-git-check --no-download-check --no-install",
 		"build": "tsdown",
 		"prepublishOnly": "npm run build",
 		"test": "vitest run"
@@ -17,16 +17,11 @@
 	],
 	"exports": {
 		".": {
-			"default": "./src/index.js"
+			"default": "./dist/index.mjs"
 		}
 	},
 	"publishConfig": {
-		"access": "public",
-		"exports": {
-			".": {
-				"default": "./dist/index.js"
-			}
-		}
+		"access": "public"
 	},
 	"peerDependencies": {
 		"sv": "latest"
diff --git a/packages/sv/src/create/templates/addon/package.template.json b/packages/sv/src/create/templates/addon/package.template.json
index cfb672e72..98845560e 100644
--- a/packages/sv/src/create/templates/addon/package.template.json
+++ b/packages/sv/src/create/templates/addon/package.template.json
@@ -6,8 +6,8 @@
 	"license": "MIT",
 	"scripts": {
 		"demo-create": "sv create demo --types ts --template minimal --no-add-ons --no-install",
-		"demo-add": "sv add file:../ --cwd demo --no-git-check --no-install",
-		"demo-add:ci": "sv add file:../=who:you --cwd demo --no-git-check --no-download-check --no-install",
+		"demo-add": "pnpm build && sv add file:../ --cwd demo --no-git-check --no-install",
+		"demo-add:ci": "pnpm build && sv add file:../=who:you --cwd demo --no-git-check --no-download-check --no-install",
 		"build": "tsdown",
 		"prepublishOnly": "npm run build",
 		"test": "vitest run"
@@ -15,16 +15,11 @@
 	"files": ["dist"],
 	"exports": {
 		".": {
-			"default": "./src/index.js"
+			"default": "./dist/index.mjs"
 		}
 	},
 	"publishConfig": {
-		"access": "public",
-		"exports": {
-			".": {
-				"default": "./dist/index.js"
-			}
-		}
+		"access": "public"
 	},
 	"peerDependencies": {
 		"sv": "workspace:*"

From 74230aae5dcd287964848ba10d6581c4fe3500f5 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 20:53:18 +0200
Subject: [PATCH 06/29] Update documentation/docs/20-commands/20-sv-add.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/20-commands/20-sv-add.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 96551daed..3c2a0fa15 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -71,7 +71,7 @@ Prevents installing dependencies
 > [!NOTE]
 > Svelte maintainers have not reviewed community add-ons for malicious code!
 
-Community add-ons are npm packages published by the community. Look out for add-ons from your favorite libraries and tools. _(soon)_ many are building `sv` add-ons to make integration a one-liner. You can find them [on npm](https://www.npmx.dev/search?q=keyword:sv-add) by searching for keyword: `sv-add`.
+Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ many developers are building `sv` add-ons to make their integrations a one-liner. You can find them [on npm](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
 
 ```sh
 # Install a community add-on by org

From 296d172d8caa5d36a673ac720247382aab3e2c89 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 20:53:37 +0200
Subject: [PATCH 07/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/30-add-ons/99-community.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 9c6a78e49..e89ccc165 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -9,7 +9,7 @@ This guide covers how to create, test, and publish community add-ons for `sv`.
 
 ## Quick start
 
-The easiest way to create an add-on is using the `addon` template:
+The easiest way to create an add-on is by using the `addon` template:
 
 ```sh
 npx sv create --template addon [path]

From d48f88c37885f9e7ab28329cff3e9b18e2d6c5a8 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 20:53:48 +0200
Subject: [PATCH 08/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/30-add-ons/99-community.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index e89ccc165..9793308a8 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -15,7 +15,7 @@ The easiest way to create an add-on is by using the `addon` template:
 npx sv create --template addon [path]
 ```
 
-The project has a `README.md` and `CONTRIBUTING.md` to guide you along.
+The newly created project will have a `README.md` and `CONTRIBUTING.md` to guide you along.
 
 ## Project structure
 

From 5ed99a2123c8b9081fa8a4a46b64e44eba25cb90 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 20:53:58 +0200
Subject: [PATCH 09/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/30-add-ons/99-community.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 9793308a8..297282848 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -138,7 +138,7 @@ export default defineConfig({
 });
 ```
 
-And create `tests/setup/global.js`:
+And the global test setup script `tests/setup/global.js`:
 
 ```js
 import { fileURLToPath } from 'node:url';

From d1d5a59034b4ecb1600c30de6e8b52b5c26b38fa Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 21:03:19 +0200
Subject: [PATCH 10/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/30-add-ons/99-community.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 297282848..77fc84d59 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -177,8 +177,8 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 		// minimum version required to run by this addon
 		"sv": "^0.13.0"
 	},
-	// Add this keyword so users can discover your add-on
-	"keywords": ["sv-add"]
+	// Add the "sv-add" keyword so users can discover your add-on
+	"keywords": ["sv-add", "svelte", "sveltekit"]
 }
 ```
 

From d21b1b7add82d6fac6affe0bfb025e4231188094 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 21:03:34 +0200
Subject: [PATCH 11/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/30-add-ons/99-community.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 77fc84d59..05a5a3b2e 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -184,7 +184,7 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 
 ### Naming convention
 
-Name your package `@your-org/sv`. Users install it by typing just the org:
+If you name your package `@your-org/sv`, users can install it by typing just the org handle:
 
 ```sh
 # npm package: @your-org/sv

From 6bc994bd93ae1c2c90e24bd906ad2b1656dbe79b Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 21:18:11 +0200
Subject: [PATCH 12/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Tee Ming <chewteeming01@gmail.com>
---
 documentation/docs/30-add-ons/99-community.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 05a5a3b2e..c80479588 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -246,7 +246,7 @@ export default defineAddon({
 
 ## Version compatibility
 
-Your add-on should specify a minimum `sv` version in `peerDependencies`. Your user will get a compatibility warning if their `sv` version has a different major version than what was specified.
+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
 

From 89bfbe39f6ff110d6b2a988a08c3e05248c5cf39 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 31 Mar 2026 22:58:56 +0200
Subject: [PATCH 13/29] update keyworkds

---
 packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json  | 4 +++-
 packages/sv/src/create/templates/addon/package.template.json | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json b/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json
index b2612863b..adf2797a0 100644
--- a/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json
+++ b/packages/sv/src/cli/tests/snapshots/@my-org/sv/package.json
@@ -34,6 +34,8 @@
 		"vitest": "^4.1.0"
 	},
 	"keywords": [
-		"sv-add"
+		"sv-add",
+		"svelte",
+		"sveltekit"
 	]
 }
diff --git a/packages/sv/src/create/templates/addon/package.template.json b/packages/sv/src/create/templates/addon/package.template.json
index 98845560e..29b5da83a 100644
--- a/packages/sv/src/create/templates/addon/package.template.json
+++ b/packages/sv/src/create/templates/addon/package.template.json
@@ -32,5 +32,5 @@
 		"tsdown": "^0.21.4",
 		"vitest": "^4.1.0"
 	},
-	"keywords": ["sv-add"]
+	"keywords": ["sv-add", "svelte", "sveltekit"]
 }

From 15dfa92077707faf6940084983dbe7357dfdc5a4 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 07:30:50 +0200
Subject: [PATCH 14/29] npmx

---
 documentation/docs/20-commands/20-sv-add.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 3c2a0fa15..dd7d5114f 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -71,7 +71,7 @@ Prevents installing dependencies
 > [!NOTE]
 > Svelte maintainers have not reviewed community add-ons for malicious code!
 
-Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ many developers are building `sv` add-ons to make their integrations a one-liner. You can find them [on npm](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
+Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ many developers are building `sv` add-ons to make their integrations a one-liner. You can find them [on npmx](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
 
 ```sh
 # Install a community add-on by org

From b9034249cb71110d909aa268c873a46032427c5b Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 07:34:07 +0200
Subject: [PATCH 15/29] M

---
 documentation/docs/20-commands/20-sv-add.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index dd7d5114f..e053136e7 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -71,7 +71,7 @@ Prevents installing dependencies
 > [!NOTE]
 > Svelte maintainers have not reviewed community add-ons for malicious code!
 
-Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ many developers are building `sv` add-ons to make their integrations a one-liner. You can find them [on npmx](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
+Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ Many developers are building `sv` add-ons to make their integrations a one-liner. You can find them [on npmx](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
 
 ```sh
 # Install a community add-on by org

From 074589a5b2f173b5102d2967f7ba88fd3c3dfcd3 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 07:36:51 +0200
Subject: [PATCH 16/29] Update documentation/docs/20-commands/20-sv-add.md

Co-authored-by: Scott Wu <sw@scottwu.ca>
---
 documentation/docs/20-commands/20-sv-add.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index dd7d5114f..8943ecbf0 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -77,7 +77,7 @@ Community add-ons are npm packages published by the community. Look out for add-
 # Install a community add-on by org
 npx sv add @supacool
 
-# Use a local add-on (for development or custom/private add-ons)
+# Use a local add-on (for development or internal use)
 npx sv add file:../path/to/my-addon
 
 # Mix and match official and community add-ons

From 304dc882f8234e4bf19e769de727e32bccdd1020 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 07:41:01 +0200
Subject: [PATCH 17/29] Update documentation/docs/20-commands/20-sv-add.md

Co-authored-by: Scott Wu <sw@scottwu.ca>
---
 documentation/docs/20-commands/20-sv-add.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index 8943ecbf0..c2ac3bb19 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -88,6 +88,6 @@ npx sv create --add eslint @supacool
 ```
 
 > [!NOTE]
-> On Windows, quote community add-ons that start with `@`, for example: `npx sv add "@supacool"`.
+> On Windows PowerShell, `@` is a special character that should be escaped with single quotes. For example: `npx sv add '@supacool'`.
 
 Want to create your own? Check the [Add-on Docs](community).

From c749319bb384e6333f0d1a213106a2313bfed6e3 Mon Sep 17 00:00:00 2001
From: "jyc.dev" <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 07:41:17 +0200
Subject: [PATCH 18/29] Update documentation/docs/30-add-ons/99-community.md

Co-authored-by: Scott Wu <sw@scottwu.ca>
---
 documentation/docs/30-add-ons/99-community.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index c80479588..6cf50ca7a 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -174,7 +174,7 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 	// cannot have dependencies
 	"dependencies": {},
 	"peerDependencies": {
-		// minimum version required to run by this addon
+		// 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

From 9682efe56a960d669cf95723ef2861c82cb2164f Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 07:57:08 +0200
Subject: [PATCH 19/29] tweaks

---
 documentation/docs/30-add-ons/99-community.md | 20 +++++++------------
 packages/sv/src/cli/tests/cli.ts              |  2 +-
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index c80479588..a6bd23051 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -88,11 +88,11 @@ The `file:` protocol also works for custom or private add-ons that you don't int
 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.
 
 ```js
-import { createSetupTest } from 'sv/testing';
 import { expect } from '@playwright/test';
-import * as vitest from 'vitest';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createSetupTest } from 'sv/testing';
+import * as vitest from 'vitest';
 import addon from './index.js';
 
 const { test, testCases } = createSetupTest(vitest)(
@@ -111,18 +111,12 @@ const { test, testCases } = createSetupTest(vitest)(
 	}
 );
 
-test.concurrent.for(testCases)(
-	'my-addon $kind.type $variant',
-	async (testCase, ctx) => {
-		const cwd = ctx.cwd(testCase);
+test.concurrent.for(testCases)('my-addon $kind.type $variant', async (testCase, ctx) => {
+	const cwd = ctx.cwd(testCase);
 
-		const page = fs.readFileSync(
-			path.resolve(cwd, 'src/routes/+page.svelte'),
-			'utf8'
-		);
-		expect(page).toContain('Hello World!');
-	}
-);
+	const page = fs.readFileSync(path.resolve(cwd, 'src/routes/+page.svelte'), 'utf8');
+	expect(page).toContain('Hello World!');
+});
 ```
 
 Your `vitest.config.js` must include the global setup from `sv/testing`:
diff --git a/packages/sv/src/cli/tests/cli.ts b/packages/sv/src/cli/tests/cli.ts
index fe8e37883..f801dd534 100644
--- a/packages/sv/src/cli/tests/cli.ts
+++ b/packages/sv/src/cli/tests/cli.ts
@@ -45,7 +45,7 @@ describe('cli', () => {
 
 	it.for(testCases)(
 		'should create a new project with name $projectName',
-		{ timeout: 111_000 },
+		{ timeout: 123_000 },
 		async (testCase) => {
 			const { projectName, args, template = 'minimal' } = testCase;
 

From 014e7772b8fece03010e29506c6864ab8474f4f7 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 15:24:03 +0200
Subject: [PATCH 20/29] rmv no error

---
 documentation/docs/30-add-ons/99-community.md |  9 ++-------
 packages/sv/src/core/config.ts                | 14 ++++++++------
 2 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index d1216f760..7e37a4242 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -22,7 +22,6 @@ The newly created project will have a `README.md` and `CONTRIBUTING.md` to guide
 Typically, an add-on looks like this:
 
 ```js
-// @noErrors
 import { transforms } from '@sveltejs/sv-utils';
 import { defineAddon, defineAddonOptions } from 'sv';
 
@@ -30,11 +29,7 @@ import { defineAddon, defineAddonOptions } from 'sv';
 export default defineAddon({
 	id: 'your-addon-name',
 
-	// optional: one-liner shown in prompts
-	shortDescription: 'does X',
-
-	// optional: link to docs/repo
-	homepage: 'https://...',
+	shortDescription: 'does xyz',
 
 	// Define options for user prompts (or passed as arguments)
 	options: defineAddonOptions()
@@ -226,11 +221,11 @@ npm publish
 You can optionally display guidance in the console after your add-on runs:
 
 ```js
-// @noErrors
 import { color } from '@sveltejs/sv-utils';
 
 export default defineAddon({
 	// ...
+
 	nextSteps: ({ options }) => [
 		`Run ${color.command('npm run dev')} to start developing`,
 		`Check out the docs at https://...`
diff --git a/packages/sv/src/core/config.ts b/packages/sv/src/core/config.ts
index 5963eedbb..a367904d3 100644
--- a/packages/sv/src/core/config.ts
+++ b/packages/sv/src/core/config.ts
@@ -40,7 +40,9 @@ export type SvApi = {
 export type Addon<Args extends OptionDefinition, Id extends string = string> = {
 	id: Id;
 	alias?: string;
+	/** one-liner shown in prompts  */
 	shortDescription?: string;
+	/** link to docs/repo */
 	homepage?: string;
 	/** If true, this addon won't appear in the interactive prompt but can still be used via CLI */
 	hidden?: boolean;
@@ -135,12 +137,12 @@ export type AddonSource =
 	| { readonly kind: 'official'; readonly id: string }
 	| { readonly kind: 'file'; readonly path: string }
 	| {
-			readonly kind: 'npm';
-			readonly packageName: string;
-			readonly npmUrl: string;
-			readonly registryUrl: string;
-			readonly tag: string; // e.g. "latest", "1.0.0"
-	  };
+		readonly kind: 'npm';
+		readonly packageName: string;
+		readonly npmUrl: string;
+		readonly registryUrl: string;
+		readonly tag: string; // e.g. "latest", "1.0.0"
+	};
 
 export type AddonReference = {
 	readonly specifier: string;

From 82647d791869f78655470f7508f0f53ba54de8c8 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 15:25:46 +0200
Subject: [PATCH 21/29] =?UTF-8?q?fmt=20power=C2=B2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/sv/src/core/config.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/sv/src/core/config.ts b/packages/sv/src/core/config.ts
index a367904d3..78da0ad43 100644
--- a/packages/sv/src/core/config.ts
+++ b/packages/sv/src/core/config.ts
@@ -137,12 +137,12 @@ export type AddonSource =
 	| { readonly kind: 'official'; readonly id: string }
 	| { readonly kind: 'file'; readonly path: string }
 	| {
-		readonly kind: 'npm';
-		readonly packageName: string;
-		readonly npmUrl: string;
-		readonly registryUrl: string;
-		readonly tag: string; // e.g. "latest", "1.0.0"
-	};
+			readonly kind: 'npm';
+			readonly packageName: string;
+			readonly npmUrl: string;
+			readonly registryUrl: string;
+			readonly tag: string; // e.g. "latest", "1.0.0"
+	  };
 
 export type AddonReference = {
 	readonly specifier: string;

From 8f180df0090f45c963bb615b27a191dbbb476d87 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 16:00:17 +0200
Subject: [PATCH 22/29] docs

---
 documentation/docs/20-commands/20-sv-add.md   |  4 ++--
 documentation/docs/30-add-ons/99-community.md | 19 +++++++++++++------
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/documentation/docs/20-commands/20-sv-add.md b/documentation/docs/20-commands/20-sv-add.md
index a1ea32520..ccc60f755 100644
--- a/documentation/docs/20-commands/20-sv-add.md
+++ b/documentation/docs/20-commands/20-sv-add.md
@@ -71,10 +71,10 @@ Prevents installing dependencies
 > [!NOTE]
 > Svelte maintainers have not reviewed community add-ons for malicious code!
 
-Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ Many developers are building `sv` add-ons to make their integrations a one-liner. You can find them [on npmx](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
+Community add-ons are npm packages published by the community. Look out for add-ons from your favourite libraries and tools. _(soon)_ Many developers are building `sv` add-ons to make their integrations a one-liner. You can find them on [npmx](https://www.npmx.dev/search?q=keyword:sv-add) by searching for the keyword: `sv-add`.
 
 ```sh
-# Install a community add-on by org
+# Install a community add-on by org name (it will look at @org/sv)
 npx sv add @supacool
 
 # Use a local add-on (for development or internal use)
diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 7e37a4242..2cba1941e 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -150,7 +150,7 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 
 ```jsonc
 {
-	"name": "@your-org/sv",
+	"name": "@my-org/sv",
 	"version": "1.0.0",
 	"type": "module",
 	// bundled entrypoint (tsdown outputs .mjs for ESM)
@@ -173,21 +173,28 @@ Your add-on must have `sv` as a peer dependency and **no** `dependencies` in `pa
 
 ### Naming convention
 
-If you name your package `@your-org/sv`, users can install it by typing just the org handle:
+#### packages names
+
+If you name your package `@my-org/sv`, users can install it by typing just the org handle:
+
+```sh
+npx sv add @my-org
+```
+
+It's also possible to publish like `@my-org/core`, just users will need to type the full package name.
 
 ```sh
-# npm package: @your-org/sv
-npx sv add @your-org
+npx sv add @my-org/core
 ```
 
 > [!NOTE]
 > Unscoped packages are not supported yet
 
-### Export options
+#### export options
 
 `sv` first tries to import `your-package/sv`, then falls back to the default export. This means you have two options:
 
-1. **Default export** (recommended for dedicated add-on packages):
+1. **Default export** (for dedicated add-on packages):
 
    ```json
    {

From 5bcfcd3ef7516dac613f3aa1c1642223ece107b3 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 16:10:56 +0200
Subject: [PATCH 23/29] docs pass

---
 documentation/docs/30-add-ons/99-community.md | 25 ++++++-------------
 documentation/docs/50-api/10-sv.md            |  3 +++
 2 files changed, 11 insertions(+), 17 deletions(-)
 create mode 100644 documentation/docs/50-api/10-sv.md

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 2cba1941e..4f66ef88f 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -25,13 +25,11 @@ Typically, an add-on looks like this:
 import { transforms } from '@sveltejs/sv-utils';
 import { defineAddon, defineAddonOptions } from 'sv';
 
-// your add-on definition, the entry point
 export default defineAddon({
 	id: 'your-addon-name',
 
-	shortDescription: 'does xyz',
+	shortDescription: 'a better description of what your addon does ;)',
 
-	// Define options for user prompts (or passed as arguments)
 	options: defineAddonOptions()
 		.add('who', {
 			question: 'To whom should the addon say hello?',
@@ -39,12 +37,10 @@ export default defineAddon({
 		})
 		.build(),
 
-	// preparing step, check requirements and dependencies
 	setup: ({ dependsOn }) => {
-		dependsOn('tailwindcss');
+		dependsOn('vitest');
 	},
 
-	// actual execution of the addon
 	run: ({ isKit, cancel, sv, options, file, language, directory }) => {
 		if (!isKit) return cancel('SvelteKit is required');
 
@@ -59,8 +55,12 @@ export default defineAddon({
 });
 ```
 
-> `sv` is responsible for the file system - `sv.file()` accepts a `path` to the file and a callback function to modify it.
-> `@sveltejs/sv-utils` is responsible for the content - `transforms.svelte()` provides you with the proper AST and utils to modify the file. See [sv-utils](/docs/cli/sv-utils) for the full API.
+The Svelte CLI is split into two packages with a clear boundary:
+
+- [**`sv`**](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`**](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
 
@@ -247,12 +247,3 @@ Your add-on should specify a minimum `sv` version in `peerDependencies`. Your us
 ## Examples
 
 See the [official add-on source code](https://github.com/sveltejs/cli/tree/main/packages/sv/src/addons) for some real world examples.
-
-## Architecture
-
-The Svelte 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.
diff --git a/documentation/docs/50-api/10-sv.md b/documentation/docs/50-api/10-sv.md
new file mode 100644
index 000000000..d9f6e06e0
--- /dev/null
+++ b/documentation/docs/50-api/10-sv.md
@@ -0,0 +1,3 @@
+---
+title: sv
+---

From dcc8c37d948b280816b10a3fb8b4d5cc874a3dad Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Wed, 1 Apr 2026 16:57:25 +0200
Subject: [PATCH 24/29] update Project structure

---
 documentation/docs/30-add-ons/99-community.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index 4f66ef88f..aa187f748 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -26,7 +26,7 @@ import { transforms } from '@sveltejs/sv-utils';
 import { defineAddon, defineAddonOptions } from 'sv';
 
 export default defineAddon({
-	id: 'your-addon-name',
+	id: 'addon-name',
 
 	shortDescription: 'a better description of what your addon does ;)',
 
@@ -37,13 +37,12 @@ export default defineAddon({
 		})
 		.build(),
 
-	setup: ({ dependsOn }) => {
+	setup: ({ dependsOn, isKit, unsupported }) => {
+		if (!isKit) unsupported('Requires SvelteKit');
 		dependsOn('vitest');
 	},
 
 	run: ({ isKit, cancel, sv, options, file, language, directory }) => {
-		if (!isKit) return cancel('SvelteKit is required');
-
 		// Add "Hello [who]!" to the root page
 		sv.file(
 			directory.kitRoutes + '/+page.svelte',
@@ -51,7 +50,9 @@ export default defineAddon({
 				svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
 			})
 		);
-	}
+	},
+
+	nextSteps: ({ options }) => ['enjoy the add-on!']
 });
 ```
 

From 6c5e1fe60e3af90fdb0e77f3741c93b73eab6c02 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Thu, 2 Apr 2026 18:28:02 +0200
Subject: [PATCH 25/29] improve issues msg

---
 packages/sv/src/core/fetch-packages.ts | 33 +++++++++++++++++++-------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/packages/sv/src/core/fetch-packages.ts b/packages/sv/src/core/fetch-packages.ts
index 0952a72a8..403f7221c 100644
--- a/packages/sv/src/core/fetch-packages.ts
+++ b/packages/sv/src/core/fetch-packages.ts
@@ -113,7 +113,7 @@ export async function downloadPackage(options: DownloadOptions): Promise<AddonDe
 			}
 		}
 
-		return await importAddonCode(pkg.name);
+		return await importAddonCode(pkg.name, pkg.version);
 	}
 
 	const tarballUrl: string = pkg.dist.tarball;
@@ -136,18 +136,35 @@ export async function downloadPackage(options: DownloadOptions): Promise<AddonDe
 		})
 	);
 
-	return await importAddonCode(pkg.name);
+	return await importAddonCode(pkg.name, pkg.version);
 }
 
-async function importAddonCode(pkgName: string): Promise<AddonDefinition> {
+async function importAddonCode(pkgName: string, pkgVersion: string): Promise<AddonDefinition> {
+	const issues: string[] = [];
+
+	let details: AddonDefinition | undefined;
 	try {
-		const { default: details } = await import(`${pkgName}/sv`);
-		return details;
+		({ default: details } = await import(`${pkgName}/sv`));
 	} catch {
-		// /sv export doesn't exist, fall through to default
+		issues.push(`'/sv' export not found`);
+	}
+
+	if (!details) {
+		try {
+			({ default: details } = await import(pkgName));
+		} catch {
+			issues.push(`default export not found`);
+		}
 	}
-	const { default: details } = await import(pkgName);
-	return details;
+
+	if (!details && issues.length > 0) {
+		throw new Error(
+			`Failed to load add-on '${pkgName}@${pkgVersion}':\n- ${issues.join('\n- ')}\n\n` +
+				`Please report this to the add-on author.`
+		);
+	}
+
+	return details!;
 }
 
 type PackageJSON = {

From ce88d27c6dd8fcf19fe833f2c1566d93b45bcb64 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Thu, 2 Apr 2026 18:33:34 +0200
Subject: [PATCH 26/29] version info

---
 documentation/docs/30-add-ons/99-community.md | 8 ++++++++
 packages/sv/src/cli/add.ts                    | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/documentation/docs/30-add-ons/99-community.md b/documentation/docs/30-add-ons/99-community.md
index aa187f748..a7e8d1a1b 100644
--- a/documentation/docs/30-add-ons/99-community.md
+++ b/documentation/docs/30-add-ons/99-community.md
@@ -188,6 +188,14 @@ It's also possible to publish like `@my-org/core`, just users will need to type
 npx sv add @my-org/core
 ```
 
+Users can also ask for a specific version:
+
+```sh
+npx sv add @my-org/sv@1.2.3
+```
+
+When no version is specified, `latest` is used.
+
 > [!NOTE]
 > Unscoped packages are not supported yet
 
diff --git a/packages/sv/src/cli/add.ts b/packages/sv/src/cli/add.ts
index c786496d0..155c7c3a2 100644
--- a/packages/sv/src/cli/add.ts
+++ b/packages/sv/src/cli/add.ts
@@ -172,6 +172,8 @@ export const add = new Command('add')
 				'  sv add prettier eslint',
 				'  sv add vitest="usages:unit" tailwindcss="plugins:none"',
 				'  sv add drizzle="database:postgresql+client:postgres.js+docker:yes"',
+				'  sv add @supacool',
+				'  sv add @supacool/sv@0.1.2',
 				''
 			].join('\n');
 		}

From f053ed52aac4dec3c3e337811e386ecb4faa435c Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Thu, 2 Apr 2026 18:41:43 +0200
Subject: [PATCH 27/29] add in --help

---
 packages/sv/src/cli/add.ts | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/packages/sv/src/cli/add.ts b/packages/sv/src/cli/add.ts
index 155c7c3a2..6d1da6c0e 100644
--- a/packages/sv/src/cli/add.ts
+++ b/packages/sv/src/cli/add.ts
@@ -115,7 +115,7 @@ export function classifyAddons(inputs: AddonInput[], cwd: string): AddonReferenc
 	if (invalidAddons.length > 0) {
 		common.errorAndExit(
 			`Invalid add-ons specified: ${invalidAddons.map((id) => color.command(id)).join(', ')}\n` +
-				`${color.optional('Check the documentation for valid add-on specifiers:')} ${color.website('https://svelte.dev/docs/cli/sv-add')}`
+			`${color.optional('Check the documentation for valid add-on specifiers:')} ${color.website('https://svelte.dev/docs/cli/sv-add')}`
 		);
 	}
 
@@ -172,7 +172,7 @@ export const add = new Command('add')
 				'  sv add prettier eslint',
 				'  sv add vitest="usages:unit" tailwindcss="plugins:none"',
 				'  sv add drizzle="database:postgresql+client:postgres.js+docker:yes"',
-				'  sv add @supacool',
+				'  sv add prettier @supacool',
 				'  sv add @supacool/sv@0.1.2',
 				''
 			].join('\n');
@@ -506,7 +506,7 @@ export async function promptAddonQuestions({
 					const cyclePath = [...addonChain, addonId, depId].join(' → ');
 					common.errorAndExit(
 						`Circular dependency detected: ${cyclePath}\n` +
-							`Add-ons cannot have circular dependencies.`
+						`Add-ons cannot have circular dependencies.`
 					);
 				}
 
@@ -872,9 +872,16 @@ export function formatAddonHelpSection(opts: {
 		return formatItem(id, option.choices);
 	});
 	if (addonList.length > 0) {
-		output.push(styleTitle('Add-Ons:'), ...addonList, '');
+		output.push(styleTitle('Official Add-Ons:'), ...addonList, '');
 	}
 
+	// Community
+	output.push(
+		styleTitle('Community Add-Ons:'),
+		'  Find on: https://www.npmjs.com/search?q=keywords:sv-add',
+		''
+	);
+
 	// Syntax
 	output.push(
 		styleTitle('Add-On Syntax:'),

From 43d75fb89c724f59cc1d3f205198bc913706ca15 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Thu, 2 Apr 2026 18:52:54 +0200
Subject: [PATCH 28/29] =?UTF-8?q?fmt=C2=B2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/sv/src/cli/add.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/sv/src/cli/add.ts b/packages/sv/src/cli/add.ts
index 6d1da6c0e..f8b38e1f4 100644
--- a/packages/sv/src/cli/add.ts
+++ b/packages/sv/src/cli/add.ts
@@ -115,7 +115,7 @@ export function classifyAddons(inputs: AddonInput[], cwd: string): AddonReferenc
 	if (invalidAddons.length > 0) {
 		common.errorAndExit(
 			`Invalid add-ons specified: ${invalidAddons.map((id) => color.command(id)).join(', ')}\n` +
-			`${color.optional('Check the documentation for valid add-on specifiers:')} ${color.website('https://svelte.dev/docs/cli/sv-add')}`
+				`${color.optional('Check the documentation for valid add-on specifiers:')} ${color.website('https://svelte.dev/docs/cli/sv-add')}`
 		);
 	}
 
@@ -506,7 +506,7 @@ export async function promptAddonQuestions({
 					const cyclePath = [...addonChain, addonId, depId].join(' → ');
 					common.errorAndExit(
 						`Circular dependency detected: ${cyclePath}\n` +
-						`Add-ons cannot have circular dependencies.`
+							`Add-ons cannot have circular dependencies.`
 					);
 				}
 

From c0500c08a9ac376c72195bcd63a812185b4384bf Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Thu, 2 Apr 2026 19:03:48 +0200
Subject: [PATCH 29/29] v0 `sv` api docs

---
 documentation/docs/50-api/10-sv.md | 107 +++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/documentation/docs/50-api/10-sv.md b/documentation/docs/50-api/10-sv.md
index d9f6e06e0..70809023a 100644
--- a/documentation/docs/50-api/10-sv.md
+++ b/documentation/docs/50-api/10-sv.md
@@ -1,3 +1,110 @@
 ---
 title: sv
 ---
+
+`sv` exposes a programmatic API for creating projects and running add-ons.
+
+## `defineAddon`
+
+Creates an add-on definition. See [create your own](community) for a full guide.
+
+```js
+import { transforms } from '@sveltejs/sv-utils';
+import { defineAddon, defineAddonOptions } from 'sv';
+
+export default defineAddon({
+	id: 'my-addon',
+	options: defineAddonOptions().build(),
+
+	// called before run — declare dependencies and environment requirements
+	setup: ({ dependsOn, unsupported, isKit }) => {
+		if (!isKit) unsupported('Requires SvelteKit');
+		dependsOn('eslint');
+	},
+
+	// the actual work — add files, edit files, declare dependencies
+	run: ({ sv, options, cancel }) => {
+		// add a dependency
+		sv.devDependency('my-lib', '^1.0.0');
+
+		// create or edit files using transforms from @sveltejs/sv-utils
+		sv.file('src/lib/foo.ts', (content) => {
+			return 'export const foo = true;';
+		});
+
+		sv.file(
+			'src/routes/+page.svelte',
+			transforms.svelte(({ ast, svelte }) => {
+				svelte.addFragment(ast, '<p>Hello!</p>');
+			})
+		);
+
+		// cancel at any point if something is wrong
+		// cancel('reason');
+	},
+
+	// displayed after the add-on runs
+	nextSteps: ({ options }) => ['Run `npm run dev` to get started']
+});
+```
+
+The `sv` object in `run` provides `file`, `dependency`, `devDependency`, `execute`, and `pnpmBuildDependency`. For file transforms (AST-based editing of scripts, Svelte components, CSS, JSON, etc.), see [`@sveltejs/sv-utils`](sv-utils).
+
+## `defineAddonOptions`
+
+Builder for add-on options. Chained with `.add()` and finalized with `.build()`.
+
+```js
+import { defineAddonOptions } from 'sv';
+
+const options = defineAddonOptions()
+	.add('database', {
+		question: 'Which database?',
+		type: 'select',
+		default: 'postgresql',
+		options: [
+			{ value: 'postgresql' },
+			{ value: 'mysql' },
+			{ value: 'sqlite' }
+		]
+	})
+	.add('docker', {
+		question: 'Add a docker-compose file?',
+		type: 'boolean',
+		default: false,
+		// only ask when database is not sqlite
+		condition: (opts) => opts.database !== 'sqlite'
+	})
+	.build();
+```
+
+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.
+
+```js
+import { create } from 'sv';
+
+create('./my-app', {
+	name: 'my-app',
+	template: 'minimal',
+	types: 'typescript'
+});
+```
+
+## `add`
+
+Programmatically run add-ons against an existing project.
+
+```js
+import { add, officialAddons } from 'sv';
+
+await add({
+	cwd: './my-app',
+	addons: { prettier: officialAddons.prettier },
+	options: { prettier: {} },
+	packageManager: 'npm'
+});
+```