We follow the standard fork-based workflow:

1. Fork this repository to your GitHub account.
2. Clone your fork locally.
3. Create a new branch for your change: git checkout -b your-feature-name
4. Commit and push your changes to your branch.
5. Open a pull request from your branch to the main branch of this repository.

Please keep your pull requests focused to feature or issue. Focused smaller changes are easier to review and faster to merge.

This project is a monorepo managed with pnpm workspaces. Install it here.

For testing, docker is also required. For linux users, you will have to ensure 'sudo' is not required. See docker post install

Checkout the code and install the dependencies with:

git clone https://github.com/sveltejs/cli.git
cd cli
pnpm i

To build the project and all packages. Run the 'build' script:

# from root of project
pnpm build

This outputs into /packages/PACKAGE/dist/.

Run the 'cli' package:

pnpm sv
pnpm sv create
pnpm sv add
pnpm sv migrate
pnpm sv check
pnpm sv help

Run build with watch mode:

pnpm dev

For each add-on we have integration tests setup. These install the deps, build the app, run the dev server and then run a few small snippets against the add-on to see if the changes introduced by the add-on are working as expected.

Because the add-on integration tests take a long time, CI only runs them when a pull request has the needs-addon-integration-tests label. Add this label to pull requests that change add-on behavior or could otherwise affect add-on integrations. Changesets release pull requests receive the label automatically.

Tests are split into projects: cli, core, sv-utils, addons, create, migrate. Always run tests by project for faster feedback:

pnpm test --project migrate            # Migrate tests
pnpm test --project core               # Core tests
pnpm test --project create             # Project creation tests
pnpm test --project addons             # Add-on tests
pnpm test --project sv-utils           # sv-utils tests

pnpm test --project addons eslint      # Just eslint add-on tests
pnpm build && pnpm test --project cli  # CLI tests

For interactive debugging, append :ui:

-pnpm test --project cli
+pnpm test:ui --project cli

Run all tests (slow, typically for CI):

pnpm test

Example of how to debug an addon failing test. Once you run the test command, you will have a directory in .test-output with the test id. A good starting point is to cd into the failing tests dir and run the app directly. E.g.:

pnpm test --project addons better-auth   # Run the failing test first

# Each test generates a standalone app in .test-output
cd packages/sv/.test-output/addons/better-auth/default-kit-ts

# Option 1: Run dev server for interactive debugging
pnpm dev
# Open http://localhost:5173 and use browser DevTools to inspect

# Option 2: Build and preview (matches production behavior)
pnpm build
pnpm preview

Using dev mode with browser DevTools is often the fastest way to debug UI issues - you can inspect network requests, console errors, and the DOM directly. Once you identify the issue, fix it in the addon source (packages/sv/src/addons/[addon].ts) and re-run the test.

Some snapshots are testing the output of sv directly from the generated binary. They are located in packages/sv/src/cli/tests/snapshots. Make sure to generate a new binary before updating these snapshots.

In one command:

pnpm build && pnpm test --project cli --update all

Ensure the following passes:

• pnpm lint
• pnpm check

Use pnpm format to format the code.

Run pnpm update-deps to recursively update the dependencies of all: addons, create templates, package.jsons and github actions to latest.

Public APIs cannot be changed in a minor release since it is a breaking change. Instead, the old behaviour is marked as deprecated until the next major version, at which point they can be removed.

1. Add @deprecated JSDoc on the type/function - IDEs will show strikethrough:

   /** @deprecated use `newThing()` instead. */

2. Emit a runtime warning (for functions/methods) using svDeprecated() from core/deprecated.ts. Warns once per message:

   svDeprecated('use `newThing()` instead of `oldThing()`');

3. Keep the old behavior working - the deprecated API should still function correctly, just with a warning.

Search for svDeprecated and @deprecated to find and remove all deprecated APIs.

Here is the command to generate a change set:

# from root of project
pnpm changeset

# select package
# choose the level of change (patch, minor, major)
# write a summary like:
#   feat(mdsvex): enable .svx .md extensions by default
#   fix(vitest): add browser testing to vitest config
#   chore(cli): update addons dependencies

• Format changeset summaries as <type>(<scope>): <summary>. A scope is required.
• Use a conventional type such as feat, fix, chore, docs, refactor, revert, security, or breaking.
• Write the summary as a concise, lowercase, imperative phrase and wrap code identifiers in backticks.
• Use single quotes around package names in the changeset frontmatter.
• Do not edit packages/*/CHANGELOG.md manually.

Choose a scope that identifies the part of the project affected by the change. Only relevant for changesets targetting sv. Potential scopes include:

• cli for command-line parsing, prompts, and command execution
• create for project creation and templates
• migrate for migrations and migration tasks
• addons for behavior shared across add-ons, or the add-on name such as drizzle, eslint, or better-auth for a specific add-on
• deps for dependency-only changes