From aec0ce6df7bb496ad5c3919769a6b2455b8cd08f Mon Sep 17 00:00:00 2001 From: Manuel Serret Date: Tue, 8 Oct 2024 21:19:41 +0200 Subject: [PATCH 01/10] add cli docs --- .../cli/10-getting-started/10-commands.md | 26 +++++++ .../docs/cli/10-getting-started/50-create.md | 39 ++++++++++ .../docs/cli/10-getting-started/51-add.md | 77 +++++++++++++++++++ .../docs/cli/10-getting-started/52-migrate.md | 13 ++++ .../docs/cli/10-getting-started/53-check.md | 17 ++++ .../docs/cli/10-getting-started/index.md | 3 + .../docs/cli/20-community-adders/10-usage.md | 28 +++++++ .../docs/cli/20-community-adders/11-docs.md | 15 ++++ .../cli/20-community-adders/12-submission.md | 20 +++++ .../docs/cli/20-community-adders/index.md | 3 + apps/svelte.dev/content/docs/cli/index.md | 3 + apps/svelte.dev/scripts/sync-docs/index.ts | 19 ++++- apps/svelte.dev/scripts/sync-docs/types.ts | 2 +- 13 files changed, 263 insertions(+), 2 deletions(-) create mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md create mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md create mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md create mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md create mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md create mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/index.md create mode 100644 apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md create mode 100644 apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md create mode 100644 apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md create mode 100644 apps/svelte.dev/content/docs/cli/20-community-adders/index.md create mode 100644 apps/svelte.dev/content/docs/cli/index.md diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md b/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md new file mode 100644 index 0000000000..c6e9e8ea2d --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md @@ -0,0 +1,26 @@ +--- +title: Commands +--- + +## Intorduction + +The svelte cli `sv` aims to combine multiple tools into one single easy to remember command. + +## Usage + +The best way to use our cli is to run one of the following commands, depending on your package manager + +```bash +npx sv +pnpx sv +# todo: should we add other package managers or just leave npx? Same goes for all other snippets +``` + +## Commands + +| Command | Sample usage | Description | +| ------------------ | -------------------------------- | ---------------------------------------------- | +| [`create`](create) | `npx sv create ./my-project` | Scaffolds new projects | +| [add](add) | `npx sv add tailwindcss` | Customize your projects to add different tools | +| migrate | `npx sv migrate {migrationName}` | Migrate your project | +| check | `npx sv check` | ??? | diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md b/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md new file mode 100644 index 0000000000..7a690b3839 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md @@ -0,0 +1,39 @@ +--- +title: Create a project +--- + +## overview + +some cool description about the `create` command and it's capabilities + +## usage + +```bash +npx sv create +``` + +```bash +npx sv create ./my/path +``` + +## available options + +| Option | option values | default | description | +| ------------- | ------------------------------- | --------- | ---------------------------------------------------------- | +| --check-types | typescript \| checkjs \| none | typescipt | determine if type checking should be added to this project | +| --template | skeleton \| skeletonlib \| demo | skeleton | project template | +| --no-adders | - | - | skips interactive adder installer | +| --no-install | - | - | skips installing dependencies | + +## programatic interface + +```js +// todo: this gives error in the docs site when commented in, seems to be related that this package is not published to the registry at this point in time, as it seems to be trying to check types +// import { create } from 'sv'; + +// // todo: check if this is right +// create(cwd, { +// // add your options here +// // todo: list available option +// }); +``` diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md b/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md new file mode 100644 index 0000000000..477810a46c --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md @@ -0,0 +1,77 @@ +--- +title: Customize your project +--- + +## overview + +some cool description about the `add` command and it's capabilities + +## usage + +```bash +npx sv add +``` + +```bash +npx sv add tailwindcss +``` + +```bash +npx sv add tailwindcss --cwd ./my/path +``` + +## available options + +| Option | option values | default | description | +| ------------------ | ------------------------------------------ | ------- | -------------------------------------------- | +| -C, --cwd | - | ./ | path to the root of your svelte(kit) project | +| --no-install | - | - | skips installing dependencies | +| --no-preconditions | - | - | skips checking preconditions | +| --no-preconditions | - | - | skips checking preconditions | +| --community | [community adder names](#community-adders) | - | adds community adders | + +## available adders + +// todo: add unmerged adders + +drizzle + +eslint + +lucia + +mdsvex + +playwright + +prettier + +routify + +storybook + +tailwindcss + +vitest + +## community adders + +> The Svelte maintainers have not reviewed community adders for malicious code. Use at your discretion. + +```bash +npx sv add --community # interactive community adder selection +``` + +```bash +npx sv add --community shadcn-svelte #test +``` + +```bash +npx sv add --community shadcn-svelte --cwd ./my/path +``` + +```bash +npx sv add --community npm:your-custom-adder-published-to-npm --cwd ./my/path +``` + +// todo: list of community adders??? diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md b/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md new file mode 100644 index 0000000000..01c5e17a20 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md @@ -0,0 +1,13 @@ +--- +title: Migrate your project +--- + +## overview + +some cool description about the `migrate` command and it's capabilities + +## usage + +```bash +npx sv migrate svelte-5 +``` diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md b/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md new file mode 100644 index 0000000000..8988c531d2 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md @@ -0,0 +1,17 @@ +--- +title: Check your project +--- + +## overview + +some cool description about the `check` command and it's capabilities + +## usage + +```bash +npx sv check +``` + +## notes + +some note that `svelte-check` will need to be installed locally into the project diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/index.md b/apps/svelte.dev/content/docs/cli/10-getting-started/index.md new file mode 100644 index 0000000000..9518c9e224 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/index.md @@ -0,0 +1,3 @@ +--- +title: Getting started +--- diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md b/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md new file mode 100644 index 0000000000..80af57adfe --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md @@ -0,0 +1,28 @@ +--- +title: Usage +--- + +## Before we begin + +> The Svelte maintainers have not reviewed community adders for malicious code. Use at your discretion. + +That being said, we still want the community to be able to enhance the experience while creating new projects. That's why everyone is allowed to create community adders. The documentation for creating a new community adder can be found [here](docs) + +## usage + +```bash +npx sv add --community # interactive list +npx sv add --community supabase # apply supabase adder +npx sv add --community npm:your-npm-package # apply any adder from npm +npx sv add --community file:./path-to-your-adder # for local testing +``` + +## requirements + +technical requirements: + +- all adders must have exactly one dependency: `@sveltejs/add-core` +- if they need to include any other dependencies they will need to do some bundeling on their side +- the major version of the referenced `@sveltejs/add-core` library must match with the major version `sv` the user is currently executing + +See [submission](submission#requirements) to find additional requirements if you want list your community adder inside `sv` for the ease of use of other community members diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md b/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md new file mode 100644 index 0000000000..b1f0b3f27d --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md @@ -0,0 +1,15 @@ +--- +title: Docs +--- + +## community adder template + +We have a [community adder template](https://github.com/sveltejs/cli/tree/main/community-adder-template) that lives inside our GitHub monorepo. This should be a starting point for all new community adders. + +We do not provide any TS template, as the types provided by all the helper methods we expose should be enough to fullfill your needs! If you still want to use typescript, nobody will prevent you. + +## basic usage + +add example usage for our 5 common files (index.js, config/adder.js, config/options.js, config/check.js, config/test.js) and explain what they are. Ommitted at this point, since the code templates do not work + +Do we need to explain more? I think most of the things should be pretty self explanatory and can be added on demand diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md b/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md new file mode 100644 index 0000000000..1f20fcb57b --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md @@ -0,0 +1,20 @@ +--- +title: Submission +--- + +## overview + +normal text + +## requirements + +- must benefit the overall svelte ecosystem and the community +- must not be too specific to one presons needs +- todo: whatever else we can think of + +## process + +- create a fork of `sveltejs/cli` +- modify file `todo` to add your community adder +- create a PR +- once merged, it might take a while before we draft a new release of `sv`, only then your new community adder will be available diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/index.md b/apps/svelte.dev/content/docs/cli/20-community-adders/index.md new file mode 100644 index 0000000000..1ab3606e8f --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/index.md @@ -0,0 +1,3 @@ +--- +title: Community adders +--- diff --git a/apps/svelte.dev/content/docs/cli/index.md b/apps/svelte.dev/content/docs/cli/index.md new file mode 100644 index 0000000000..5f81cc866a --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/index.md @@ -0,0 +1,3 @@ +--- +title: CLI +--- diff --git a/apps/svelte.dev/scripts/sync-docs/index.ts b/apps/svelte.dev/scripts/sync-docs/index.ts index 9af5b20eb3..653955be4f 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -13,6 +13,7 @@ interface Package { repo: string; pkg: string; docs: string; + types: string; process_modules: (modules: Modules, pkg: Package) => Promise; } @@ -27,6 +28,7 @@ const packages: Package[] = [ repo: 'sveltejs/svelte', pkg: 'packages/svelte', docs: 'documentation/docs', + types: 'types', process_modules: async (modules: Modules) => { // Remove $$_attributes from ActionReturn const module_with_ActionReturn = modules.find((m) => @@ -50,6 +52,7 @@ const packages: Package[] = [ repo: 'sveltejs/kit', pkg: 'packages/kit', docs: 'documentation/docs', + types: 'types', process_modules: async (modules, pkg) => { const kit_base = `${pkg.local}/${pkg.pkg}/`; @@ -119,6 +122,17 @@ const packages: Package[] = [ svelte_kit_module!.types = [full_config, full_kit_config]; + return modules; + } + }, + { + name: 'cli', + local: `${REPOS}/svelte-cli`, + repo: 'sveltejs/cli', + pkg: 'packages/cli', + docs: 'documentation/docs', + types: 'dist', + process_modules: async (modules: Modules) => { return modules; } } @@ -144,7 +158,10 @@ for (const pkg of packages) { cpSync(`${pkg.local}/${pkg.docs}`, `${DOCS}/${pkg.name}`, { recursive: true }); migrate_meta_json(`${DOCS}/${pkg.name}`); - const modules = await pkg.process_modules(await read_types(`${pkg.local}/${pkg.pkg}/`, []), pkg); + const modules = await pkg.process_modules( + await read_types(`${pkg.local}/${pkg.pkg}/${pkg.types}/`, []), + pkg + ); const files = glob(`${DOCS}/${pkg.name}/**/*.md`); diff --git a/apps/svelte.dev/scripts/sync-docs/types.ts b/apps/svelte.dev/scripts/sync-docs/types.ts index d7986688af..4bdfd63395 100644 --- a/apps/svelte.dev/scripts/sync-docs/types.ts +++ b/apps/svelte.dev/scripts/sync-docs/types.ts @@ -11,7 +11,7 @@ export async function read_types(base: string, modules: Modules) { 'svelte/types/compiler/preprocess', // legacy entrypoint 'svelte/types/compiler/interfaces' // legacy entrypoint ]; - const code = read_d_ts_file(base + 'types/index.d.ts'); + const code = read_d_ts_file(base + 'index.d.ts'); const node = ts.createSourceFile('index.d.ts', code, ts.ScriptTarget.Latest, true); for (const statement of node.statements) { From 12fd11221bca75d830fbbb66104e66c874375303 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 9 Oct 2024 17:23:32 -0400 Subject: [PATCH 02/10] tweak sync script --- apps/svelte.dev/scripts/sync-docs/index.ts | 25 +++++++--------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/apps/svelte.dev/scripts/sync-docs/index.ts b/apps/svelte.dev/scripts/sync-docs/index.ts index 39222811d6..573b2da37b 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -10,13 +10,12 @@ import type { Modules } from '@sveltejs/site-kit/markdown'; interface Package { name: string; - local: string; repo: string; branch: string; pkg: string; docs: string; types: string; - process_modules: (modules: Modules, pkg: Package) => Promise; + process_modules?: (modules: Modules, pkg: Package) => Promise; } const dirname = fileURLToPath(new URL('.', import.meta.url)); @@ -26,7 +25,6 @@ const DOCS = path.join(dirname, '../../content/docs'); const packages: Package[] = [ { name: 'svelte', - local: `${REPOS}/svelte`, repo: 'sveltejs/svelte', branch: 'docs-fixes', pkg: 'packages/svelte', @@ -51,14 +49,13 @@ const packages: Package[] = [ }, { name: 'kit', - local: `${REPOS}/kit`, repo: 'sveltejs/kit', branch: 'svelte-dev-adjusted-docs', // TODO update! pkg: 'packages/kit', docs: 'documentation/docs', types: 'types', process_modules: async (modules, pkg) => { - const kit_base = `${pkg.local}/${pkg.pkg}/`; + const kit_base = `${REPOS}/${pkg.name}/${pkg.pkg}/`; { const code = read_d_ts_file(kit_base + 'src/types/private.d.ts'); @@ -108,14 +105,11 @@ const packages: Package[] = [ }, { name: 'cli', - local: `${REPOS}/svelte-cli`, repo: 'sveltejs/cli', + branch: 'chore/add-docs', pkg: 'packages/cli', docs: 'documentation/docs', - types: 'dist', - process_modules: async (modules: Modules) => { - return modules; - } + types: 'dist' } ]; @@ -141,17 +135,14 @@ for (const pkg of packages) { const dest = `${DOCS}/${pkg.name}`; fs.rmSync(dest, { force: true, recursive: true }); - fs.cpSync(`${pkg.local}/${pkg.docs}`, dest, { recursive: true }); + fs.cpSync(`${REPOS}/${pkg.name}/${pkg.docs}`, dest, { recursive: true }); migrate_meta_json(dest); - const modules = await pkg.process_modules( - await read_types(`${pkg.local}/${pkg.pkg}/${pkg.types}/`, []), - pkg - ); + const modules = await read_types(`${REPOS}/${pkg.name}/${pkg.pkg}/${pkg.types}/`, []); - const files = glob(`${dest}/**/*.md`); + await pkg.process_modules?.(modules, pkg); - for (const file of files) { + for (const file of glob(`${dest}/**/*.md`)) { const content = await preprocess(fs.readFileSync(file, 'utf-8'), modules); fs.writeFileSync(file, content); From c70bd72badcb4476ef43cb18f67a9d12ea1f183a Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 10 Oct 2024 13:25:42 -0400 Subject: [PATCH 03/10] =?UTF-8?q?only=20ingest=20types=20if=20specified=20?= =?UTF-8?q?=E2=80=94=C2=A0cli=20does=20not=20use=20them=20anywhere?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/svelte.dev/scripts/sync-docs/index.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/apps/svelte.dev/scripts/sync-docs/index.ts b/apps/svelte.dev/scripts/sync-docs/index.ts index 43fbab7a4a..55537f7963 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -14,7 +14,7 @@ interface Package { branch: string; pkg: string; docs: string; - types: string; + types: string | null; process_modules?: (modules: Modules, pkg: Package) => Promise; } @@ -109,7 +109,7 @@ const packages: Package[] = [ branch: 'chore/add-docs', pkg: 'packages/cli', docs: 'documentation/docs', - types: 'dist' + types: null } ]; @@ -138,9 +138,12 @@ for (const pkg of packages) { fs.cpSync(`${REPOS}/${pkg.name}/${pkg.docs}`, dest, { recursive: true }); migrate_meta_json(dest); - const modules = await read_types(`${REPOS}/${pkg.name}/${pkg.pkg}/${pkg.types}/`, []); + let modules: Modules = []; - await pkg.process_modules?.(modules, pkg); + if (pkg.types !== null) { + modules = await read_types(`${REPOS}/${pkg.name}/${pkg.pkg}/${pkg.types}/`, []); + await pkg.process_modules?.(modules, pkg); + } for (const file of glob(`${dest}/**/*.md`)) { const content = await preprocess(fs.readFileSync(file, 'utf-8'), modules); From a91e822d23cf2bcdafdedf9c7ed99f27e23abcdb Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 10 Oct 2024 13:25:48 -0400 Subject: [PATCH 04/10] update content --- .../cli/10-getting-started/10-commands.md | 10 +- .../docs/cli/10-getting-started/50-create.md | 10 +- .../docs/cli/10-getting-started/51-add.md | 46 +++---- .../docs/cli/10-getting-started/52-migrate.md | 30 +++-- .../docs/cli/10-getting-started/53-check.md | 126 ++++++++++++++++-- .../docs/cli/20-community-adders/10-usage.md | 6 +- .../docs/cli/20-community-adders/11-docs.md | 10 +- .../cli/20-community-adders/12-submission.md | 18 +-- 8 files changed, 180 insertions(+), 76 deletions(-) diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md b/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md index c6e9e8ea2d..b618d877ae 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md @@ -2,9 +2,9 @@ title: Commands --- -## Intorduction +## Introduction -The svelte cli `sv` aims to combine multiple tools into one single easy to remember command. +`sv`, the Svelte CLI, aims to combine multiple tools into one single easy to remember command. ## Usage @@ -21,6 +21,6 @@ pnpx sv | Command | Sample usage | Description | | ------------------ | -------------------------------- | ---------------------------------------------- | | [`create`](create) | `npx sv create ./my-project` | Scaffolds new projects | -| [add](add) | `npx sv add tailwindcss` | Customize your projects to add different tools | -| migrate | `npx sv migrate {migrationName}` | Migrate your project | -| check | `npx sv check` | ??? | +| [add](add) | `npx sv add [adder...]` | Customize your projects to add different tools | +| migrate | `npx sv migrate ` | Migrate your project | +| check | `npx sv check` | Typecheck your Svelte files | diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md b/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md index 7a690b3839..a7f5e7259c 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md @@ -2,11 +2,11 @@ title: Create a project --- -## overview +## Overview -some cool description about the `create` command and it's capabilities +`sv create` sets up a new SvelteKit project. It also offers numerous integrations with various technologies that are commonly-used for building web sites and web apps. You can set these up later with the `add` command. -## usage +## Usage ```bash npx sv create @@ -16,7 +16,7 @@ npx sv create npx sv create ./my/path ``` -## available options +## Available options | Option | option values | default | description | | ------------- | ------------------------------- | --------- | ---------------------------------------------------------- | @@ -28,7 +28,7 @@ npx sv create ./my/path ## programatic interface ```js -// todo: this gives error in the docs site when commented in, seems to be related that this package is not published to the registry at this point in time, as it seems to be trying to check types +// TODO: this gives type checking errors in the docs site when not commented out. Need to release sv, install it in the site, and uncomment this. // import { create } from 'sv'; // // todo: check if this is right diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md b/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md index 477810a46c..dda8b22107 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md @@ -2,11 +2,11 @@ title: Customize your project --- -## overview +## Overview -some cool description about the `add` command and it's capabilities +It also offers numerous integrations with various technologies that are commonly-used for building web sites and web apps. -## usage +## Usage ```bash npx sv add @@ -20,7 +20,7 @@ npx sv add tailwindcss npx sv add tailwindcss --cwd ./my/path ``` -## available options +## Available options | Option | option values | default | description | | ------------------ | ------------------------------------------ | ------- | -------------------------------------------- | @@ -30,31 +30,21 @@ npx sv add tailwindcss --cwd ./my/path | --no-preconditions | - | - | skips checking preconditions | | --community | [community adder names](#community-adders) | - | adds community adders | -## available adders +## Official adders -// todo: add unmerged adders +- auth +- drizzle +- eslint +- mdsvex +- paraglide +- playwright +- prettier +- routify +- storybook +- tailwindcss +- vitest -drizzle - -eslint - -lucia - -mdsvex - -playwright - -prettier - -routify - -storybook - -tailwindcss - -vitest - -## community adders +## Community adders > The Svelte maintainers have not reviewed community adders for malicious code. Use at your discretion. @@ -73,5 +63,3 @@ npx sv add --community shadcn-svelte --cwd ./my/path ```bash npx sv add --community npm:your-custom-adder-published-to-npm --cwd ./my/path ``` - -// todo: list of community adders??? diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md b/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md index 01c5e17a20..fa68122e28 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md @@ -1,13 +1,25 @@ ---- -title: Migrate your project ---- +# sv migrate -## overview +A CLI for migrating Svelte(Kit) codebases. -some cool description about the `migrate` command and it's capabilities +Run it using -## usage - -```bash -npx sv migrate svelte-5 ``` +npx sv migrate [migration] +``` + +## Migrations + +| Migration | From | To | Guide | +| ------------- | --------------------- | --------------------- | --------------------------------------------------------------- | +| `svelte-5` | Svelte 4 | Svelte 5 | [Website](https://svelte.dev/docs/v5-migration-guide) | +| `sveltekit-2` | SvelteKit 1.0 | SvelteKit 2.0 | [Website](https://kit.svelte.dev/docs/migrating-to-sveltekit-2) | +| `svelte-4` | Svelte 3 | Svelte 4 | [Website](https://svelte.dev/docs/v4-migration-guide) | +| `package` | `@sveltejs/package@1` | `@sveltejs/package@2` | [#8922](https://github.com/sveltejs/kit/pull/8922) | +| `routes` | SvelteKit pre-1.0 | SvelteKit 1.0 | [#5774](https://github.com/sveltejs/kit/discussions/5774) | + +Some migrations may annotate your codebase with tasks for completion that you can find by searching for `@migration`. + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/main/packages/migrate/CHANGELOG.md). diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md b/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md index 8988c531d2..6f7e687526 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md @@ -1,17 +1,123 @@ ---- -title: Check your project ---- +# Check your code with sv check -## overview +Provides CLI diagnostics checks for: -some cool description about the `check` command and it's capabilities +- Unused CSS +- Svelte A11y hints +- JavaScript/TypeScript compiler errors -## usage +Requires Node 16 or later. -```bash -npx sv check +### Usage: + +#### Local / in your project + +Installation: + +`npm i svelte-check --save-dev` + +Package.json: + +```json +{ + // ... + "scripts": { + "sv": "npx sv" + // ... + }, + // ... + "devDependencies": { + "svelte-check": "..." + // ... + } +} +``` + +Usage: + +`npm run sv check` + +### Args: + +| Flag | Description | +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--workspace ` | Path to your workspace. All subdirectories except node_modules and those listed in `--ignore` are checked | +| `--output ` | +| `--watch` | Will not exit after one pass but keep watching files for changes and rerun diagnostics | +| `--preserveWatchOutput` | Do not clear the screen in watch mode | +| `--tsconfig ` | Pass a path to a tsconfig or jsconfig file. The path can be relative to the workspace path or absolute. Doing this means that only files matched by the files/include/exclude pattern of the config file are diagnosed. It also means that errors from TypeScript and JavaScript files are reported. If not given, will do an upwards traversal looking for the next jsconfig/tsconfig.json | +| `--no-tsconfig` | Use this if you only want to check the Svelte files found in the current directory and below and ignore any JS/TS files (they will not be type-checked) | +| `--ignore ` | Only has an effect when used in conjunction with `--no-tsconfig`. Files/folders to ignore - relative to workspace root, comma-separated, inside quotes. Example: `--ignore "dist,build"`. When used in conjunction with `--tsconfig`, this will only have effect on the files watched, not on the files that are diagnosed, which is then determined by the `tsconfig.json` | +| `--fail-on-warnings` | Will also exit with error code when there are warnings | +| `--compiler-warnings ` | A list of Svelte compiler warning codes. Each entry defines whether that warning should be ignored or treated as an error. Warnings are comma-separated, between warning code and error level is a colon; all inside quotes. Example: `--compiler-warnings "css-unused-selector:ignore,unused-export-let:error"` | +| `--diagnostic-sources ` | A list of diagnostic sources which should run diagnostics on your code. Possible values are `js` (includes TS), `svelte`, `css`. Comma-separated, inside quotes. By default all are active. Example: `--diagnostic-sources "js,svelte"` | +| `--threshold ` | Filters the diagnostics to display. `error` will output only errors while `warning` will output warnings and errors. | + +### FAQ + +#### Why is there no option to only check specific files (for example only staged files)? + +`svelte-check` needs to know the whole project to do valid checks. Imagine you alter a component property `export let foo` to `export let bar`, but you don't update any of the component usages. They all have errors now but you would not catch them if you only run checks on changed files. + +### More docs, preprocessor setup and troubleshooting + +[See here](/docs/README.md). + +### Machine-Readable Output + +Setting the `--output` to `machine` or `machine-verbose` will format output in a way that is easier to read +by machines, e.g. inside CI pipelines, for code quality checks, etc. + +Each row corresponds to a new record. Rows are made up of columns that are separated by a +single space character. The first column of every row contains a timestamp in milliseconds +which can be used for monitoring purposes. The second column gives us the "row type", based +on which the number and types of subsequent columns may differ. + +The first row is of type `START` and contains the workspace folder (wrapped in quotes). + +###### Example: + +``` +1590680325583 START "/home/user/language-tools/packages/language-server/test/plugins/typescript/testfiles" +``` + +Any number of `ERROR` or `WARNING` records may follow. Their structure is identical and depends on the output argoument. + +If the argument is `machine` it will tell us the filename, the starting line and column numbers, and the error message. The filename is relative to the workspace directory. The filename and the message are both wrapped in quotes. + +###### Example: + +``` +1590680326283 ERROR "codeactions.svelte" 1:16 "Cannot find module 'blubb' or its corresponding type declarations." +1590680326778 WARNING "imported-file.svelte" 0:37 "Component has unused export property 'prop'. If it is for external reference only, please consider using `export const prop`" +``` + +If the argument is `machine-verbose` it will tell us the filename, the starting line and column numbers, the ending line and column numbers, the error message, the code of diagnostic, the human-friendly description of the code and the human-friendly source of the diagnostic (eg. svelte/typescript). The filename is relative to the workspace directory. Each diagnostic is represented as an [ndjson](https://en.wikipedia.org/wiki/JSON_streaming#Newline-Delimited_JSON) line prefixed by the timestamp of the log. + +###### Example: + +``` +1590680326283 {"type":"ERROR","fn":"codeaction.svelte","start":{"line":1,"character":16},"end":{"line":1,"character":23},"message":"Cannot find module 'blubb' or its corresponding type declarations.","code":2307,"source":"js"} +1590680326778 {"type":"WARNING","filename":"imported-file.svelte","start":{"line":0,"character":37},"end":{"line":0,"character":51},"message":"Component has unused export property 'prop'. If it is for external reference only, please consider using `export +const prop`","code":"unused-export-let","source":"svelte"} +``` + +The output concludes with a `COMPLETED` message that summarizes total numbers of files, errors and warnings that were encountered during the check. + +###### Example: + +``` +1590680326807 COMPLETED 20 FILES 21 ERRORS 1 WARNINGS 3 FILES_WITH_PROBLEMS +``` + +If the application experiences a runtime error, this error will appear as a `FAILURE` record. + +###### Example: + +``` +1590680328921 FAILURE "Connection closed" ``` -## notes +### Credits -some note that `svelte-check` will need to be installed locally into the project +- Vue's [VTI](https://github.com/vuejs/vetur/tree/master/vti) which laid the foundation for `svelte-check` diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md b/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md index 80af57adfe..ee7479a9c3 100644 --- a/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md @@ -8,7 +8,7 @@ title: Usage That being said, we still want the community to be able to enhance the experience while creating new projects. That's why everyone is allowed to create community adders. The documentation for creating a new community adder can be found [here](docs) -## usage +## Usage ```bash npx sv add --community # interactive list @@ -17,12 +17,12 @@ npx sv add --community npm:your-npm-package # apply any adder from npm npx sv add --community file:./path-to-your-adder # for local testing ``` -## requirements +## Requirements technical requirements: - all adders must have exactly one dependency: `@sveltejs/add-core` -- if they need to include any other dependencies they will need to do some bundeling on their side +- if they need to include any other dependencies they will need to do some bundling on their side - the major version of the referenced `@sveltejs/add-core` library must match with the major version `sv` the user is currently executing See [submission](submission#requirements) to find additional requirements if you want list your community adder inside `sv` for the ease of use of other community members diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md b/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md index b1f0b3f27d..b624dbf631 100644 --- a/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md @@ -2,14 +2,12 @@ title: Docs --- -## community adder template +## Community adder template We have a [community adder template](https://github.com/sveltejs/cli/tree/main/community-adder-template) that lives inside our GitHub monorepo. This should be a starting point for all new community adders. -We do not provide any TS template, as the types provided by all the helper methods we expose should be enough to fullfill your needs! If you still want to use typescript, nobody will prevent you. +We do not provide any TS template, as the types provided by all the helper methods we expose should be enough to fulfill your needs! If you still want to use TypeScript, that's totally fine as well. -## basic usage +## Basic usage -add example usage for our 5 common files (index.js, config/adder.js, config/options.js, config/check.js, config/test.js) and explain what they are. Ommitted at this point, since the code templates do not work - -Do we need to explain more? I think most of the things should be pretty self explanatory and can be added on demand +We have 5 common files: `index.js`, `config/adder.js`, `config/options.js`, `config/check.js`, `config/test.js`. Please check official adders for examples and do not be shy about asking questions in the GitHub issues or on Discord. diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md b/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md index 1f20fcb57b..2b919e4f65 100644 --- a/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md +++ b/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md @@ -2,19 +2,19 @@ title: Submission --- -## overview +## Overview -normal text +Community adders are still in development. We'd love to help get the first few released. Please open an issue or find us on Discord to discuss how to develop your adder and get it included. -## requirements +## Requirements -- must benefit the overall svelte ecosystem and the community -- must not be too specific to one presons needs -- todo: whatever else we can think of +- must benefit the overall ecosystem and community rather than being individually tailored +- should be a best-in-class tool that is ideally widely used in the community +- open source tools are generally preferred to commercial offerings -## process +## Process - create a fork of `sveltejs/cli` -- modify file `todo` to add your community adder +- modify the community manifest file to list your adder (TODO: this file does not exist yet) - create a PR -- once merged, it might take a while before we draft a new release of `sv`, only then your new community adder will be available +- wait for the the next release of `sv` From 1ffeab735fdabdd825e38716aef9e2b52db97db2 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 10 Oct 2024 13:31:31 -0400 Subject: [PATCH 05/10] fix --- .../docs/cli/10-getting-started/50-create.md | 2 +- .../docs/cli/10-getting-started/51-add.md | 2 +- .../docs/cli/10-getting-started/52-migrate.md | 4 ++- .../docs/cli/10-getting-started/53-check.md | 32 ++++++++++--------- 4 files changed, 22 insertions(+), 18 deletions(-) diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md b/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md index a7f5e7259c..a4d1170cef 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md @@ -1,5 +1,5 @@ --- -title: Create a project +title: sv create --- ## Overview diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md b/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md index dda8b22107..9f94ff93b8 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md @@ -1,5 +1,5 @@ --- -title: Customize your project +title: sv add --- ## Overview diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md b/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md index fa68122e28..7550b44653 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md @@ -1,4 +1,6 @@ -# sv migrate +--- +title: sv migrate +--- A CLI for migrating Svelte(Kit) codebases. diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md b/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md index 6f7e687526..5a2dba5c86 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md +++ b/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md @@ -1,10 +1,12 @@ -# Check your code with sv check +--- +title: sv check +--- Provides CLI diagnostics checks for: -- Unused CSS -- Svelte A11y hints -- JavaScript/TypeScript compiler errors +- Unused CSS +- Svelte A11y hints +- JavaScript/TypeScript compiler errors Requires Node 16 or later. @@ -20,16 +22,16 @@ Package.json: ```json { - // ... - "scripts": { - "sv": "npx sv" - // ... - }, - // ... - "devDependencies": { - "svelte-check": "..." - // ... - } + // ... + "scripts": { + "sv": "npx sv" + // ... + }, + // ... + "devDependencies": { + "svelte-check": "..." + // ... + } } ``` @@ -120,4 +122,4 @@ If the application experiences a runtime error, this error will appear as a `FAI ### Credits -- Vue's [VTI](https://github.com/vuejs/vetur/tree/master/vti) which laid the foundation for `svelte-check` +- Vue's [VTI](https://github.com/vuejs/vetur/tree/master/vti) which laid the foundation for `svelte-check` From 08f6550c680bdc48c332f916fc2a23f94eac596f Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 10 Oct 2024 13:58:29 -0400 Subject: [PATCH 06/10] sync --- .../svelte.dev/content/docs/cli/10-getting-started/index.md | 3 --- .../10-commands.md => 10-introduction/10-overview.md} | 6 ++---- apps/svelte.dev/content/docs/cli/10-introduction/index.md | 3 +++ .../50-create.md => 20-commands/10-create.md} | 0 .../{10-getting-started/51-add.md => 20-commands/20-add.md} | 0 .../53-check.md => 20-commands/30-check.md} | 0 .../52-migrate.md => 20-commands/40-migrate.md} | 0 apps/svelte.dev/content/docs/cli/20-commands/index.md | 3 +++ .../10-usage.md | 0 .../11-docs.md => 30-community-adders/20-docs.md} | 0 .../30-submission.md} | 2 -- .../{20-community-adders => 30-community-adders}/index.md | 0 12 files changed, 8 insertions(+), 9 deletions(-) delete mode 100644 apps/svelte.dev/content/docs/cli/10-getting-started/index.md rename apps/svelte.dev/content/docs/cli/{10-getting-started/10-commands.md => 10-introduction/10-overview.md} (92%) create mode 100644 apps/svelte.dev/content/docs/cli/10-introduction/index.md rename apps/svelte.dev/content/docs/cli/{10-getting-started/50-create.md => 20-commands/10-create.md} (100%) rename apps/svelte.dev/content/docs/cli/{10-getting-started/51-add.md => 20-commands/20-add.md} (100%) rename apps/svelte.dev/content/docs/cli/{10-getting-started/53-check.md => 20-commands/30-check.md} (100%) rename apps/svelte.dev/content/docs/cli/{10-getting-started/52-migrate.md => 20-commands/40-migrate.md} (100%) create mode 100644 apps/svelte.dev/content/docs/cli/20-commands/index.md rename apps/svelte.dev/content/docs/cli/{20-community-adders => 30-community-adders}/10-usage.md (100%) rename apps/svelte.dev/content/docs/cli/{20-community-adders/11-docs.md => 30-community-adders/20-docs.md} (100%) rename apps/svelte.dev/content/docs/cli/{20-community-adders/12-submission.md => 30-community-adders/30-submission.md} (98%) rename apps/svelte.dev/content/docs/cli/{20-community-adders => 30-community-adders}/index.md (100%) diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/index.md b/apps/svelte.dev/content/docs/cli/10-getting-started/index.md deleted file mode 100644 index 9518c9e224..0000000000 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Getting started ---- diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md b/apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md similarity index 92% rename from apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md rename to apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md index b618d877ae..d8328e59b9 100644 --- a/apps/svelte.dev/content/docs/cli/10-getting-started/10-commands.md +++ b/apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md @@ -1,9 +1,7 @@ --- -title: Commands +title: Overview --- -## Introduction - `sv`, the Svelte CLI, aims to combine multiple tools into one single easy to remember command. ## Usage @@ -23,4 +21,4 @@ pnpx sv | [`create`](create) | `npx sv create ./my-project` | Scaffolds new projects | | [add](add) | `npx sv add [adder...]` | Customize your projects to add different tools | | migrate | `npx sv migrate ` | Migrate your project | -| check | `npx sv check` | Typecheck your Svelte files | +| check | `npx sv check` | Typecheck your Svelte files | diff --git a/apps/svelte.dev/content/docs/cli/10-introduction/index.md b/apps/svelte.dev/content/docs/cli/10-introduction/index.md new file mode 100644 index 0000000000..8f14f7a7c9 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/10-introduction/index.md @@ -0,0 +1,3 @@ +--- +title: Introduction +--- diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md b/apps/svelte.dev/content/docs/cli/20-commands/10-create.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/10-getting-started/50-create.md rename to apps/svelte.dev/content/docs/cli/20-commands/10-create.md diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md b/apps/svelte.dev/content/docs/cli/20-commands/20-add.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/10-getting-started/51-add.md rename to apps/svelte.dev/content/docs/cli/20-commands/20-add.md diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md b/apps/svelte.dev/content/docs/cli/20-commands/30-check.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/10-getting-started/53-check.md rename to apps/svelte.dev/content/docs/cli/20-commands/30-check.md diff --git a/apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md b/apps/svelte.dev/content/docs/cli/20-commands/40-migrate.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/10-getting-started/52-migrate.md rename to apps/svelte.dev/content/docs/cli/20-commands/40-migrate.md diff --git a/apps/svelte.dev/content/docs/cli/20-commands/index.md b/apps/svelte.dev/content/docs/cli/20-commands/index.md new file mode 100644 index 0000000000..877406c009 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/20-commands/index.md @@ -0,0 +1,3 @@ +--- +title: Commands +--- diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md b/apps/svelte.dev/content/docs/cli/30-community-adders/10-usage.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/20-community-adders/10-usage.md rename to apps/svelte.dev/content/docs/cli/30-community-adders/10-usage.md diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md b/apps/svelte.dev/content/docs/cli/30-community-adders/20-docs.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/20-community-adders/11-docs.md rename to apps/svelte.dev/content/docs/cli/30-community-adders/20-docs.md diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md b/apps/svelte.dev/content/docs/cli/30-community-adders/30-submission.md similarity index 98% rename from apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md rename to apps/svelte.dev/content/docs/cli/30-community-adders/30-submission.md index 2b919e4f65..b86db0b4ef 100644 --- a/apps/svelte.dev/content/docs/cli/20-community-adders/12-submission.md +++ b/apps/svelte.dev/content/docs/cli/30-community-adders/30-submission.md @@ -2,8 +2,6 @@ title: Submission --- -## Overview - Community adders are still in development. We'd love to help get the first few released. Please open an issue or find us on Discord to discuss how to develop your adder and get it included. ## Requirements diff --git a/apps/svelte.dev/content/docs/cli/20-community-adders/index.md b/apps/svelte.dev/content/docs/cli/30-community-adders/index.md similarity index 100% rename from apps/svelte.dev/content/docs/cli/20-community-adders/index.md rename to apps/svelte.dev/content/docs/cli/30-community-adders/index.md From acda30f49da5ba332c2d70324567c91d380cedc3 Mon Sep 17 00:00:00 2001 From: Manuel Serret Date: Sat, 19 Oct 2024 11:40:08 +0200 Subject: [PATCH 07/10] fix merge issue --- apps/svelte.dev/scripts/sync-docs/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/svelte.dev/scripts/sync-docs/index.ts b/apps/svelte.dev/scripts/sync-docs/index.ts index 1af59f10a9..749da2a327 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -151,7 +151,7 @@ async function sync(pkg: Package) { } for (const file of glob(`${dest}/**/*.md`)) { - const content = await preprocess(fs.readFileSync(file, 'utf-8'), modules); + const content = await preprocess(file, modules); fs.writeFileSync(file, content); } From 236fbb2149e3d9131cfd2d6e1767df699deb182d Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Mon, 28 Oct 2024 13:29:05 -0400 Subject: [PATCH 08/10] sync --- .../docs/cli/10-introduction/10-overview.md | 17 +- .../content/docs/cli/20-commands/10-create.md | 39 ----- .../docs/cli/20-commands/10-sv-create.md | 55 ++++++ .../content/docs/cli/20-commands/20-add.md | 65 ------- .../content/docs/cli/20-commands/20-sv-add.md | 39 +++++ .../content/docs/cli/20-commands/30-check.md | 125 -------------- .../docs/cli/20-commands/30-sv-check.md | 161 ++++++++++++++++++ .../docs/cli/20-commands/40-migrate.md | 27 --- .../docs/cli/20-commands/40-sv-migrate.md | 35 ++++ .../docs/cli/30-community-adders/10-usage.md | 28 --- .../docs/cli/30-community-adders/20-docs.md | 13 -- .../cli/30-community-adders/30-submission.md | 18 -- .../docs/cli/30-community-adders/index.md | 3 - 13 files changed, 296 insertions(+), 329 deletions(-) delete mode 100644 apps/svelte.dev/content/docs/cli/20-commands/10-create.md create mode 100644 apps/svelte.dev/content/docs/cli/20-commands/10-sv-create.md delete mode 100644 apps/svelte.dev/content/docs/cli/20-commands/20-add.md create mode 100644 apps/svelte.dev/content/docs/cli/20-commands/20-sv-add.md delete mode 100644 apps/svelte.dev/content/docs/cli/20-commands/30-check.md create mode 100644 apps/svelte.dev/content/docs/cli/20-commands/30-sv-check.md delete mode 100644 apps/svelte.dev/content/docs/cli/20-commands/40-migrate.md create mode 100644 apps/svelte.dev/content/docs/cli/20-commands/40-sv-migrate.md delete mode 100644 apps/svelte.dev/content/docs/cli/30-community-adders/10-usage.md delete mode 100644 apps/svelte.dev/content/docs/cli/30-community-adders/20-docs.md delete mode 100644 apps/svelte.dev/content/docs/cli/30-community-adders/30-submission.md delete mode 100644 apps/svelte.dev/content/docs/cli/30-community-adders/index.md diff --git a/apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md b/apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md index d8328e59b9..9e4b22233e 100644 --- a/apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md +++ b/apps/svelte.dev/content/docs/cli/10-introduction/10-overview.md @@ -2,23 +2,18 @@ title: Overview --- -`sv`, the Svelte CLI, aims to combine multiple tools into one single easy to remember command. +The command line interface (CLI), `sv`, is a toolkit for creating and maintaining Svelte applications. ## Usage -The best way to use our cli is to run one of the following commands, depending on your package manager +The easiest way to run `sv` is with [`npx`](https://docs.npmjs.com/cli/v8/commands/npx) (or the equivalent command if you're using a different package manager — for example, `pnpx` if you're using [pnpm](https://pnpm.io/)): ```bash npx sv -pnpx sv -# todo: should we add other package managers or just leave npx? Same goes for all other snippets ``` -## Commands +If you're inside a project where `sv` is already installed, this will use the local installation, otherwise it will download the latest version and run it without installing it, which is particularly useful for [`sv create`](sv-create). -| Command | Sample usage | Description | -| ------------------ | -------------------------------- | ---------------------------------------------- | -| [`create`](create) | `npx sv create ./my-project` | Scaffolds new projects | -| [add](add) | `npx sv add [adder...]` | Customize your projects to add different tools | -| migrate | `npx sv migrate ` | Migrate your project | -| check | `npx sv check` | Typecheck your Svelte files | +## Acknowledgements + +Thank you to [Christopher Brown](https://github.com/chbrown) who originally owned the `sv` name on npm for graciously allowing it to be used for the Svelte CLI. You can find the original `sv` package at [`@chbrown/sv`](https://www.npmjs.com/package/@chbrown/sv). diff --git a/apps/svelte.dev/content/docs/cli/20-commands/10-create.md b/apps/svelte.dev/content/docs/cli/20-commands/10-create.md deleted file mode 100644 index a4d1170cef..0000000000 --- a/apps/svelte.dev/content/docs/cli/20-commands/10-create.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: sv create ---- - -## Overview - -`sv create` sets up a new SvelteKit project. It also offers numerous integrations with various technologies that are commonly-used for building web sites and web apps. You can set these up later with the `add` command. - -## Usage - -```bash -npx sv create -``` - -```bash -npx sv create ./my/path -``` - -## Available options - -| Option | option values | default | description | -| ------------- | ------------------------------- | --------- | ---------------------------------------------------------- | -| --check-types | typescript \| checkjs \| none | typescipt | determine if type checking should be added to this project | -| --template | skeleton \| skeletonlib \| demo | skeleton | project template | -| --no-adders | - | - | skips interactive adder installer | -| --no-install | - | - | skips installing dependencies | - -## programatic interface - -```js -// TODO: this gives type checking errors in the docs site when not commented out. Need to release sv, install it in the site, and uncomment this. -// import { create } from 'sv'; - -// // todo: check if this is right -// create(cwd, { -// // add your options here -// // todo: list available option -// }); -``` diff --git a/apps/svelte.dev/content/docs/cli/20-commands/10-sv-create.md b/apps/svelte.dev/content/docs/cli/20-commands/10-sv-create.md new file mode 100644 index 0000000000..26471b2bf4 --- /dev/null +++ b/apps/svelte.dev/content/docs/cli/20-commands/10-sv-create.md @@ -0,0 +1,55 @@ +--- +title: sv create +--- + +`sv create` sets up a new SvelteKit project, with options to [setup additional functionality](sv-add#Official-integrations). + +## Usage + +```bash +npx sv create [options] [path] +``` + +## Options + + + +### `--check-types