> [!NOTE] Les add-ons communautaires sont actuellement **expérimentaux**. L'API peut évoluer. Ne les
> utilisez pas en production pour le moment !

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

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

La manière la plus simple de créer un add-on est d'utiliser le template d'add-on :

```sh
npx sv create --template addon my-addon
cd my-addon
```

## Structure de l'add-on [!VO]Add-on structure

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

_survolez les mots-clés dans le code pour obtenir plus de contexte_

```js
import { defineAddon, defineAddonOptions, parse, svelte } from 'sv/core';

// Définir des options qui seront présentées à l'utilisateur (ou passées en arguments)
const options = defineAddonOptions()
	.add('who', {
		question: "À qui l'add-on doit-il dire bonjour ?",
		type: 'string' // boolean | number | select | multiselect
	})
	.build();

// la définition de votre add-on, le point d'entrée
export default defineAddon({
	id: 'le-nom-de-l-add-on',

	options,

	// étape de préparation, vérification des prérequis et des dépendances
	setup: ({ dependsOn }) => {
		dependsOn('tailwindcss');
	},

	// exécution de l'add-on
	run: ({ kit, cancel, sv, options }) => {
		if (!kit) return cancel('SvelteKit est requis');

		// Ajoute "Bonjour [who]" à la page racine
		sv.file(kit.routesDirectory + '/+page.svelte', (content) => {
			const { ast, generateCode } = parse.svelte(content);

			svelte.addFragment(ast, `<p>Bonjour ${options.who} !</p>`);

			return generateCode();
		});
	}
});
```

## Développement avec le protocole `file:` [!VO]Development with `file:` protocol

Lorsque vous développez votre add-on, vous pouvez le tester localement en utilisant le protocole
`file:` :

```sh
# Dans votre projet test
npx sv add file:../path/to/my-addon
```

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

## Tester avec `sv/testing` [!VO]Testing with `sv/testing`

Le module `sv/testing` fournit des utilitaires pour tester votre add-on :

```js
import { test, expect } from 'vitest';
import { setupTest } from 'sv/testing';
import addon from './index.js';

test("ajoute un message d'accueil", async () => {
	const { content } = await setupTest({
		addon,
		options: { who: 'tout le monde' },
		files: {
			'src/routes/+page.svelte': '<h1>Bonjour</h1>'
		}
	});

	expect(content('src/routes/+page.svelte')).toContain('Bonjour tout le monde !');
});
```

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

### Structure de paquet [!VO]Package structure

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

```json
{
	"name": "@your-org/sv",
	"version": "1.0.0",
	"type": "module",
	"exports": {
		".": "./dist/index.js"
	},
	"dependencies": {
		"sv": "^0.11.0"
	},
	"keywords": ["sv-add"]
}
```

> [!NOTE]
> Ajoutez le mot-clé `sv-add` afin que les utilisateurs et utilisatrices puissent trouver votre
> add-on sur npm.

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

Votre paquet peut exporter l'add-on de deux manières :

1. **Export par défaut** (recommandé pour les paquets dédiés à un add-on) :

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

2. **Export `/sv`** (pour les paquets qui ont d'autres fonctionnalités) :
   ```json
   {
   	"exports": {
   		".": "./dist/main.js",
   		"./sv": "./dist/addon.js"
   	}
   }
   ```

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

- **Paquets scopés**: Utilisez `@your-org/sv` en tant que nom du paquet. Les utilisateurs et
utilisatrices peuvent alors l'installer avec uniquement `npx sv add @your-org`.
- **Paquets classiques**: N'importe quel nom fonctionne. Le paquet s'installera avec `npx sv add
your-package-name`.

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

Votre add-on doit préciser la version minimale de `sv` requises dans le `package.json`. 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é.