Skip to main content
CLIAdd-ons

[créez le votre]

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 le CLI de Svelte.

Démarrage rapide

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

npx sv create --template addon [path]

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

Structure du projet

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

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, addOption }) => {
		if (!isKit) unsupported('Nécessite SvelteKit');
		dependsOn('vitest');

		// ajoute dynamiquement des options (par ex. basé sur l'état du workspace ou des données récupérées)
		// addOption('key', { question: '...', type: 'boolean', default: true });
	},

	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 est divisé en deux paquets avec un frontière claire :

  • 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 = 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

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

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.

Le scipt demo-add compile automatiquement votre add-on avant de l’exécuter.

Tests

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.

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 :

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 :

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

Bundling

Les add-on communautaires sont compilés avec tsdown 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 :

{
	"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 avec https://www.npmx.dev/search?q=keyword:sv-add
	"keywords": ["sv-add", "svelte", "sveltekit"]
}

Noms de paquets

Packages must be published under an npm org:

# ✓ BIEN
npx sv add @my-org/sv
npx sv add @my-org/core

# ✗ PAS BIEN
npx sv add my-lib

Si votre paquet est publié avec le scope sv, celui-ci peut être omis. Les exemples suivants sont tous résolus vers le même paquet :

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

Pour obtenir une version spécifique, ajoutez @<version> :

npx sv add @my-org/sv@1.2.3

Points d’entrée

Le CLI cherche d’abord ./sv. S’il ne le trouve pas, il considère par défaut le point d’entrée .. Ceci signifie que vous avez deux options :

  1. Export par défaut (pour un paquet d’add-on dédié):
{
	"name": "@my-org/sveltekit-addon",
	"exports": {
		".": "./dist/addon.mjs"
	}
}
  1. Export ./sv (pour les paquets qui exportent également d’autres fonctionnalités) :
{
	"name": "@my-org/sveltekit-addon",
	"exports": {
		".": "./dist/main.mjs",
		"./sv": "./dist/addon.mjs"
	}
}

Publier sur npm

npm login
npm publish

prepublishOnly exécute automatiquement le build avant de publier.

Prochaines étapes

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

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

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

Consultez le code source des add-ons officiels pour trouver des exemples concrets.

Modifier cette page sur Github llms.txt

précédent suivant
devtools-json