Svelte · CLI and AI tooling · all subjects

cli/overview

141 notes in this subject, read out of this brain and free to use. This is page 3 of 3.

nextSteps function for add-on guidance

The nextSteps function returns an array of strings displayed in the console after the add-on runs. Strings can include color.command() for highlighting commands: 'Run ' + color.command('npm run dev') + ' to start developing'.

Add-on package naming convention

Add-on packages must be published under an npm org scope. Format: @my-org/sv or @my-org/core. Packages published under the 'sv' scope can omit the scope name: 'npx sv add @my-org' resolves the same as 'npx sv add @my-org/sv'. Specific versions can be specified with: 'npx sv add @my-org/sv@1.2.3'.

Add-on export entry points

The CLI looks for './sv' export first. If not found, it defaults to '.' export. For dedicated add-on packages, use default export with "exports": { ".": "./dist/addon.mjs" }. For packages exporting other functionality, use './sv' export with "exports": { ".": "./dist/main.mjs", "./sv": "./dist/addon.mjs" }.

defineAddonOptions.add method

The defineAddonOptions().add() method creates addon options. It takes two parameters: a key (string) and an options object containing 'question' (string prompt), 'type' (one of: boolean, number, string, select, multiselect), and optionally 'default' (boolean value). The chain must end with .build().

sv and @sveltejs/sv-utils package separation

'sv' package owns paths, workspace detection, dependency tracking, and file I/O; it orchestrates add-on execution. '@sveltejs/sv-utils' provides parsers, language tooling, and typed transforms and is pure with no file system or workspace awareness. This separation makes transforms testable without a workspace and composable across add-ons.

Run add-on locally with file: protocol

To run an add-on locally without publishing, use 'npx sv add file:../path/to/my-addon' from the test project directory. This allows quick iteration and works for custom or private add-ons that standardize project setup across a team or organization.

defineAddon function structure

defineAddon creates an add-on definition with required properties: id (string identifier), options (built with defineAddonOptions), setup (called before run to declare dependencies and requirements), run (performs the actual work), and nextSteps (displayed after the add-on runs).

sv programmatic API overview

The sv module exposes a programmatic API for creating projects and running add-ons through functions like defineAddon, create, and add.

create function parameters

The create function programmatically creates a new Svelte project with parameters: cwd (project directory path), name (project name), template (template type), and types (typescript or other type configuration).

defineAddon typed dynamic options

defineAddon accepts a type parameter to provide strong typing for dynamically added options. The type parameter is passed as a generic before the function call: defineAddon<{ theme: string }>(). This allows the options object in the run callback to have typed properties.

defineAddon setup callback parameters and methods

The setup callback receives an object with methods: dependsOn (declare dependency), unsupported (mark as unsupported), addOption (dynamically add options), and isKit (check if SvelteKit project).

defineAddonOptions builder pattern

defineAddonOptions creates a builder that chains .add() calls to define options and finalizes with .build(). Each option definition includes: question (prompt text), type (select, boolean, string, number), default value, and optional condition callback that receives previously answered options to determine if the question should be asked.

option condition callback for conditional prompts

Options defined with defineAddonOptions can include a condition property with a callback function that receives the options object of all previously answered questions. Returning false skips the question and its value becomes undefined.

addOption dynamic option definition

The addOption callback in setup defines individual options with: question (prompt text), type (select, boolean, or string), default value, and for select type, an options array containing objects with value properties.

add function parameters

The add function programmatically runs add-ons against an existing project with parameters: cwd (project directory path), addons (object mapping addon names to addon definitions, can use officialAddons), options (object mapping addon names to their option values), and packageManager (npm, yarn, pnpm, etc.).

sv.devDependency method

The sv.devDependency method adds a development dependency to the project. It takes a package name and version specifier (e.g., '^1.0.0').

sv.file method for creating or editing files

The sv.file method takes a file path and a callback function that receives the file content. The callback returns the new file content. For complex transformations, it can accept transforms from @sveltejs/sv-utils for AST-based editing of scripts, Svelte components, CSS, JSON, and other formats.

defineAddon run callback parameters and sv methods

The run callback receives an object containing: sv object with methods file, dependency, devDependency, and execute; options object containing the collected options; and cancel function to stop execution with a reason.

Svelte CLI documentation is auto-generated

The Svelte CLI documentation file (cli/index.md) is automatically generated by scripts located at apps/svelte.dev/scripts/sync-docs/index.ts. This file should not be manually edited.

API documentation is auto-generated

The API documentation file at apps/svelte.dev/content/docs/cli/50-api/index.md is auto-generated via apps/svelte.dev/scripts/sync-docs/index.ts. The file should not be manually edited.

Add-ons documentation is auto-generated

The add-ons documentation file is generated automatically by apps/svelte.dev/scripts/sync-docs/index.ts and should not be edited manually.

Give your agent this brain