> [!NOTE]
> Les add-ons communautaires sont actuellement **expérimentaux**. Leur API peut changer. Ne les
> utilisez pas encore en production !

Ce guide vous explique comment créer, tester, et publier des add-ons communautaires pour `sv`.

## Démarrage rapide [!VO]Quick start

La façon la plus simple de créer un add-on est d'utiliser le template `addon` :

```sh
npx sv create --template addon [path]
```

Le projet nouvellement créé aura des fichiers `README.md` et `CONTRIBUTING.md` pour vous
accompagner.

## Structure du projet [!VO]Project structure

Un add-on ressemble généralement à ceci :

```js
import { transforms } from '@sveltejs/sv-utils';
import { defineAddon, defineAddonOptions } from 'sv';

export default defineAddon({
	id: 'addon-name',

	shortDescription: 'une meilleure description de ce que fait votre add-on ;)',

	options: defineAddonOptions()
		.add('who', {
			question: 'À qui cet add-on doit-il dire bonjour ?',
			type: 'string' // boolean | number | select | multiselect
		})
		.build(),

	setup: ({ dependsOn, isKit, unsupported }) => {
		if (!isKit) unsupported('Nécessite SvelteKit');
		dependsOn('vitest');
	},

	run: ({ isKit, cancel, sv, options, file, language, directory }) => {
		// Ajoute "Bonjour [who] !" sur la page racine
		sv.file(
			directory.kitRoutes + '/+page.svelte',
			transforms.svelte(({ ast, svelte }) => {
				svelte.addFragment(ast, `<p>Bonjour ${options.who} !</p>`);
			})
		);
	},

	nextSteps: ({ options }) => ['profitez de cet add-on!']
});
```

Le CLI de Svelte est divisé en deux paquets avec un frontière claire :

- [**`sv`**](sv) = **où et quand**. Ce paquet gère les paths, la détection de workspace, le suivi de
dépendances, et l'I/O de fichier. Le moteur orchestre l'exécution de l'add-on.
- [**`@sveltejs/sv-utils`**](sv-utils) = **quoi**. Ce paquet fournit des parsers, de l'outillage de
language, et des transformations typées. Tout ici est pur — pas de système de fichiers, pas de
conscience du workspace.

Cette séparation implique que les transformations sont testables sans aucun workspace, et
composables entre add-ons.

## Développement [!VO]Development

Vous pouvez exécuter votre add-on localement avec le protocole `file:` :

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

Ceci vous permet d'itérer rapidement sans publier sur npm.

Le protocole `file:` fonctionne également pour les add-ons privés ou personnalisés que vous n'avez
pas l'intention de publier — par exemple, pour standardiser la mise en place d'un projet au sein de
votre équipe ou de votre organisation.

> [!NOTE]
> Le scipt `demo-add` compile automatiquement votre add-on avant de l'exécuter.

## Tests [!VO]Testing

Le module `sv/testing` fournit des utilitaires pour tester votre add-on. `createSetupTest` est une
usine qui prend vos imports vitest et renvoie une fonction `setupTest`. Elle crée des vrais projets
SvelteKit à partir de templates, exécute votre add-on, et vous donne accès aux fichiers ainsi
générés.

```js
import { expect } from '@playwright/test';
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)(
	{ 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);

	const page = fs.readFileSync(path.resolve(cwd, 'src/routes/+page.svelte'), 'utf8');
	expect(page).toContain('Bonjour tout le monde !');
});
```

Votre fichier `vitest.config.js` doit contenir la configuration globale de `sv/testing` :

```js
import { defineConfig } from 'vitest/config';

export default defineConfig({
	test: {
		include: ['tests/**/*.test.{js,ts}'],
		globalSetup: ['tests/setup/global.js']
	}
});
```

Le script `tests/setup/global.js` étant le suivant :

```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 });
```

## Publier [!VO]Publishing

### Bundling

Les add-on communautaires sont compilés avec [tsdown](https://tsdown.dev/) en un seul fichier. Tout
est compilé, à l'exception de sv (qui est une dépendance-paire, fournie lors de l'exécution.)

### `package.json`

Votre add-on doit avoir `sv` comme dépendance-paire et **aucune** dépendance dans votre
`package.json` :

```jsonc
{
	"name": "@my-org/sv",
	"version": "1.0.0",
	"type": "module",
	// point d'entrée compilé (tsdown génère des .mjs pour les ESM)
	"exports": {
		".": { "default": "./dist/index.mjs" }
	},
	"publishConfig": {
		"access": "public"
	},
	// ne peut pas avoir de dépendances
	"dependencies": {},
	"peerDependencies": {
		// la version minimum requise pour exécuter cet add-on
		"sv": "^0.13.0"
	},
	// Ajoutez le mot-clé "sv-add" afin que les gens puissent trouver votre add-on
	"keywords": ["sv-add", "svelte", "sveltekit"]
}
```

### Conventions de nommage [!VO]Naming convention

#### Noms de paquets [!VO]packages names

Si vous appelez vos paquet `@my-org/sv`, les gens pourront l'installer juste en tapant le nom de
votre organisation :

```sh
npx sv add @my-org
```

Il est également possible de publier avec un nom comme `@my-org/core`, les gens devront alors taper
le nom complet du paquet :

```sh
npx sv add @my-org/core
```

Il est également possible de demander une version précise :

```sh
npx sv add @my-org/sv@1.2.3
```

Lorsqu'aucune version n'est demandée, `latest` est utilisé.

> [!NOTE]
> Les paquets non scopés ne sont pas encore supportés

#### Options d'export [!VO]export options

`sv` essaye d'abord d'importer `your-package/sv`, puis utilise l'export par défaut s'il n'y arrive
pas. Ceci signifie que vous avez deux options :

1. **L'export par défaut** (pour les paquets d'add-on dédiés) :

   ```json
   {
   	"exports": {
   		".": "./src/index.js"
   	}
   }
   ```

2. **L'export `./sv`** (pour les paquets qui exportent également d'autres fonctionnalités):
   ```json
   {
   	"exports": {
   		".": "./src/main.js",
   		"./sv": "./src/addon.js"
   	}
   }
   ```

### Publier sur npm [!VO]Publish to npm

```sh
npm login
npm publish
```

> `prepublishOnly` exécute automatiquement le build avant de publier.

## Prochaines étapes [!VO]Next steps

Vous pouvez de manière optionnelle afficher des indications à afficher lors de l'exécution de votre
add-on :

```js
import { color } from '@sveltejs/sv-utils';

export default defineAddon({
	// ...

	nextSteps: ({ options }) => [
		`Lancez ${color.command('npm run dev')} pour commencer le développement`,
		`Retrouvez la documentation sur https://...`
	]
});
```

## Compatibilité de version [!VO]Version compatibility

Votre add-on doit préciser la version minimale de `sv `requises dans vos `peerDependencies`. Si la
version de `sv `d'un utilisateur ou d'un utilisatrice a une majeure différente de celle pour
laquelle votre add-on a été conçu, ils et elles verront un avertissement de compatibilité.


## Exemples [!VO]Examples

Consultez le [code source des add-ons
officiels](https://github.com/sveltejs/cli/tree/main/packages/sv/src/addons) pour trouver des
exemples concrets.