Skip to content

Commit 45b5771

Browse files
manuel3108manuel3108
authored
chore: add docs (#71)
1 parent 59ddada commit 45b5771

File tree

13 files changed

+339
-0
lines changed

13 files changed

+339
-0
lines changed

‎cli

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
repos/cli

‎documentation/docs/10-introduction/10-overview.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Overview
3+
---
4+
5+
The command line interface (CLI), `sv`, is a toolkit for creating and maintaining Svelte applications.
6+
7+
## Usage
8+
9+
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/)):
10+
11+
```bash
12+
npx sv <command> <args>
13+
```
14+
15+
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).

‎documentation/docs/10-introduction/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
---
2+
title: Introduction
3+
---

‎documentation/docs/20-commands/10-sv-create.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: sv create
3+
---
4+
5+
`sv create` sets up a new SvelteKit project, with options to [setup additional functionality](sv-add#Official-adders).
6+
7+
## Usage
8+
9+
```bash
10+
npx sv create
11+
```
12+
13+
```bash
14+
npx sv create ./my/path
15+
```
16+
17+
## Available options
18+
19+
| Option | option values | default | description |
20+
| ------------- | ------------------------------- | --------- | ---------------------------------------------------------- |
21+
| --check-types | typescript \| checkjs \| none | typescipt | determine if type checking should be added to this project |
22+
| --template | skeleton \| skeletonlib \| demo | skeleton | project template |
23+
| --no-adders | - | - | skips interactive adder installer |
24+
| --no-install | - | - | skips installing dependencies |
25+
26+
## Programmatic interface
27+
28+
```js
29+
// 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.
30+
// import { create } from 'sv';
31+
32+
// // todo: check if this is right
33+
// create(cwd, {
34+
// // add your options here
35+
// // todo: list available option
36+
// });
37+
```

‎documentation/docs/20-commands/20-sv-add.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: sv add
3+
---
4+
5+
`sv add` updates your code to add new functionality to an existing project.
6+
7+
## Usage
8+
9+
```bash
10+
npx sv add
11+
```
12+
13+
```bash
14+
npx sv add tailwindcss
15+
```
16+
17+
```bash
18+
npx sv add tailwindcss --cwd ./my/path
19+
```
20+
21+
## Available options
22+
23+
| Option | option values | default | description |
24+
| ------------------ | ------------------------------------------ | ------- | -------------------------------------------- |
25+
| -C, --cwd | - | ./ | path to the root of your svelte(kit) project |
26+
| --no-install | - | - | skips installing dependencies |
27+
| --no-preconditions | - | - | skips checking preconditions |
28+
| --no-preconditions | - | - | skips checking preconditions |
29+
| --community | [community adder names](#community-adders) | - | adds community adders |
30+
31+
## Official adders
32+
33+
- auth
34+
- drizzle
35+
- eslint
36+
- mdsvex
37+
- paraglide
38+
- playwright
39+
- prettier
40+
- routify
41+
- storybook
42+
- tailwindcss
43+
- vitest
44+
45+
## Community adders
46+
47+
> The Svelte maintainers have not reviewed community adders for malicious code. Use at your discretion.
48+
49+
```bash
50+
npx sv add --community # interactive community adder selection
51+
```
52+
53+
```bash
54+
npx sv add --community shadcn-svelte #test
55+
```
56+
57+
```bash
58+
npx sv add --community shadcn-svelte --cwd ./my/path
59+
```
60+
61+
```bash
62+
npx sv add --community npm:your-custom-adder-published-to-npm --cwd ./my/path
63+
```

‎documentation/docs/20-commands/30-sv-check.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: sv check
3+
---
4+
5+
Provides CLI diagnostics checks for:
6+
7+
- Unused CSS
8+
- Svelte A11y hints
9+
- JavaScript/TypeScript compiler errors
10+
11+
Requires Node 16 or later.
12+
13+
### Usage:
14+
15+
#### Local / in your project
16+
17+
Installation:
18+
19+
`npm i svelte-check --save-dev`
20+
21+
Package.json:
22+
23+
```json
24+
{
25+
// ...
26+
"scripts": {
27+
"sv": "npx sv"
28+
// ...
29+
},
30+
// ...
31+
"devDependencies": {
32+
"svelte-check": "..."
33+
// ...
34+
}
35+
}
36+
```
37+
38+
Usage:
39+
40+
`npm run sv check`
41+
42+
### Args:
43+
44+
| Flag | Description |
45+
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46+
| `--workspace <path>` | Path to your workspace. All subdirectories except node_modules and those listed in `--ignore` are checked |
47+
| `--output <human\|human-verbose\|machine\|machine-verbose>` |
48+
| `--watch` | Will not exit after one pass but keep watching files for changes and rerun diagnostics |
49+
| `--preserveWatchOutput` | Do not clear the screen in watch mode |
50+
| `--tsconfig <path>` | 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 |
51+
| `--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) |
52+
| `--ignore <path1,path2>` | 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` |
53+
| `--fail-on-warnings` | Will also exit with error code when there are warnings |
54+
| `--compiler-warnings <code1:error\|ignore,code2:error\|ignore>` | 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"` |
55+
| `--diagnostic-sources <js,svelte,css>` | 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"` |
56+
| `--threshold <error\|warning>` | Filters the diagnostics to display. `error` will output only errors while `warning` will output warnings and errors. |
57+
58+
### FAQ
59+
60+
#### Why is there no option to only check specific files (for example only staged files)?
61+
62+
`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.
63+
64+
### More docs, preprocessor setup and troubleshooting
65+
66+
[See here](/docs/README.md).
67+
68+
### Machine-Readable Output
69+
70+
Setting the `--output` to `machine` or `machine-verbose` will format output in a way that is easier to read
71+
by machines, e.g. inside CI pipelines, for code quality checks, etc.
72+
73+
Each row corresponds to a new record. Rows are made up of columns that are separated by a
74+
single space character. The first column of every row contains a timestamp in milliseconds
75+
which can be used for monitoring purposes. The second column gives us the "row type", based
76+
on which the number and types of subsequent columns may differ.
77+
78+
The first row is of type `START` and contains the workspace folder (wrapped in quotes).
79+
80+
###### Example:
81+
82+
```
83+
1590680325583 START "/home/user/language-tools/packages/language-server/test/plugins/typescript/testfiles"
84+
```
85+
86+
Any number of `ERROR` or `WARNING` records may follow. Their structure is identical and depends on the output argoument.
87+
88+
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.
89+
90+
###### Example:
91+
92+
```
93+
1590680326283 ERROR "codeactions.svelte" 1:16 "Cannot find module 'blubb' or its corresponding type declarations."
94+
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`"
95+
```
96+
97+
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.
98+
99+
###### Example:
100+
101+
```
102+
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"}
103+
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
104+
const prop`","code":"unused-export-let","source":"svelte"}
105+
```
106+
107+
The output concludes with a `COMPLETED` message that summarizes total numbers of files, errors and warnings that were encountered during the check.
108+
109+
###### Example:
110+
111+
```
112+
1590680326807 COMPLETED 20 FILES 21 ERRORS 1 WARNINGS 3 FILES_WITH_PROBLEMS
113+
```
114+
115+
If the application experiences a runtime error, this error will appear as a `FAILURE` record.
116+
117+
###### Example:
118+
119+
```
120+
1590680328921 FAILURE "Connection closed"
121+
```
122+
123+
### Credits
124+
125+
- Vue's [VTI](https://github.com/vuejs/vetur/tree/master/vti) which laid the foundation for `svelte-check`

‎documentation/docs/20-commands/40-sv-migrate.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: sv migrate
3+
---
4+
5+
A CLI for migrating Svelte(Kit) codebases.
6+
7+
Run it using
8+
9+
```
10+
npx sv migrate [migration]
11+
```
12+
13+
## Migrations
14+
15+
| Migration | From | To | Guide |
16+
| ------------- | --------------------- | --------------------- | --------------------------------------------------------------- |
17+
| `svelte-5` | Svelte 4 | Svelte 5 | [Website](https://svelte.dev/docs/v5-migration-guide) |
18+
| `sveltekit-2` | SvelteKit 1.0 | SvelteKit 2.0 | [Website](https://kit.svelte.dev/docs/migrating-to-sveltekit-2) |
19+
| `svelte-4` | Svelte 3 | Svelte 4 | [Website](https://svelte.dev/docs/v4-migration-guide) |
20+
| `package` | `@sveltejs/package@1` | `@sveltejs/package@2` | [#8922](https://github.com/sveltejs/kit/pull/8922) |
21+
| `routes` | SvelteKit pre-1.0 | SvelteKit 1.0 | [#5774](https://github.com/sveltejs/kit/discussions/5774) |
22+
23+
Some migrations may annotate your codebase with tasks for completion that you can find by searching for `@migration`.
24+
25+
## Changelog
26+
27+
[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/main/packages/migrate/CHANGELOG.md).

‎documentation/docs/20-commands/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
---
2+
title: Commands
3+
---

‎documentation/docs/30-community-adders/10-usage.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Usage
3+
---
4+
5+
## Before we begin
6+
7+
> The Svelte maintainers have not reviewed community adders for malicious code. Use at your discretion.
8+
9+
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)
10+
11+
## Usage
12+
13+
```bash
14+
npx sv add --community # interactive list
15+
npx sv add --community supabase # apply supabase adder
16+
npx sv add --community npm:your-npm-package # apply any adder from npm
17+
npx sv add --community file:./path-to-your-adder # for local testing
18+
```
19+
20+
## Requirements
21+
22+
technical requirements:
23+
24+
- all adders must have exactly one dependency: `@sveltejs/add-core`
25+
- if they need to include any other dependencies they will need to do some bundling on their side
26+
- the major version of the referenced `@sveltejs/add-core` library must match with the major version `sv` the user is currently executing
27+
28+
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

‎documentation/docs/30-community-adders/20-docs.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Docs
3+
---
4+
5+
## Community adder template
6+
7+
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.
8+
9+
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.
10+
11+
## Basic usage
12+
13+
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.

0 commit comments

Comments
 (0)