@ogygia/tsdown-plugin-svelte 0.1.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +89 -20
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,21 +1,44 @@
|
|
|
1
1
|
# @ogygia/tsdown-plugin-svelte
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@ogygia/tsdown-plugin-svelte)
|
|
4
|
+
[](./LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
Ship Svelte components from a [tsdown](https://tsdown.dev) build.
|
|
7
|
+
|
|
8
|
+
Keep one build for your whole library. Your `.ts` goes through tsdown as usual, and your `.svelte` components ship next to it, the way `svelte-package` ships them, with no second build step.
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
src/ dist/
|
|
12
|
+
├─ index.ts → ├─ index.mjs + index.d.mts (tsdown)
|
|
13
|
+
├─ Button.svelte → ├─ Button.svelte (plain JS, uncompiled)
|
|
14
|
+
│ ├─ Button.svelte.d.ts (typed props)
|
|
15
|
+
└─ theme.css → └─ theme.css (copied)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Why
|
|
19
|
+
|
|
20
|
+
- **Components ship uncompiled.** Each `.svelte` file lands in `dist` at the same path, as source. Your users' own Svelte compiles it, so your library never pins them to the Svelte version you built with.
|
|
21
|
+
- **Write TypeScript everywhere, ship plain JS.** TypeScript is removed from the `<script>` and from the template: `{item as Row}`, `{user!.name}` and `{#snippet row(item: Row)}` are all fine. What ships needs no TypeScript setup on the user's side.
|
|
22
|
+
- **Typed props.** A `.svelte.d.ts` is generated beside every component, with svelte2tsx, the same engine `svelte-package` uses.
|
|
23
|
+
- **Safe stripping.** Types are found with Svelte's own parser, not with patterns, so a string or comment that merely looks like a type is never touched.
|
|
24
|
+
- **Styles come along.** Plain `.css` files under `src` are copied as they are.
|
|
9
25
|
|
|
10
26
|
## Install
|
|
11
27
|
|
|
12
28
|
```sh
|
|
13
|
-
pnpm add -D @ogygia/tsdown-plugin-svelte
|
|
29
|
+
pnpm add -D @ogygia/tsdown-plugin-svelte
|
|
14
30
|
```
|
|
15
31
|
|
|
16
|
-
|
|
32
|
+
It needs `tsdown` (0.15 or newer) and `svelte` 5. For the defaults, also install:
|
|
17
33
|
|
|
18
|
-
|
|
34
|
+
```sh
|
|
35
|
+
pnpm add -D svelte2tsx typescript @sveltejs/vite-plugin-svelte
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `svelte2tsx` and `typescript` generate the `.svelte.d.ts` types. Skip them with `dts: false`.
|
|
39
|
+
- `@sveltejs/vite-plugin-svelte` provides the default preprocessor. Skip it by passing your own `preprocess`.
|
|
40
|
+
|
|
41
|
+
## Usage
|
|
19
42
|
|
|
20
43
|
```ts
|
|
21
44
|
// tsdown.config.ts
|
|
@@ -27,22 +50,70 @@ export default defineConfig({
|
|
|
27
50
|
unbundle: true,
|
|
28
51
|
dts: true,
|
|
29
52
|
plugins: [svelte()],
|
|
30
|
-
//
|
|
53
|
+
// the shipped components stay as files: never bundle them, or Svelte, into your JS
|
|
31
54
|
deps: { neverBundle: ['svelte', /\.svelte$/] }
|
|
32
55
|
});
|
|
33
56
|
```
|
|
34
57
|
|
|
58
|
+
`unbundle: true` keeps one output file per source file, so `import Button from './Button.svelte'` in your `.ts` still points at the shipped component.
|
|
59
|
+
|
|
60
|
+
Then expose the components to Svelte-aware tools with the `svelte` export condition:
|
|
61
|
+
|
|
62
|
+
```jsonc
|
|
63
|
+
// package.json
|
|
64
|
+
{
|
|
65
|
+
"type": "module",
|
|
66
|
+
"exports": {
|
|
67
|
+
".": {
|
|
68
|
+
"types": "./dist/index.d.mts",
|
|
69
|
+
"svelte": "./dist/index.mjs",
|
|
70
|
+
"default": "./dist/index.mjs"
|
|
71
|
+
},
|
|
72
|
+
"./Button.svelte": {
|
|
73
|
+
"types": "./dist/Button.svelte.d.ts",
|
|
74
|
+
"svelte": "./dist/Button.svelte"
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
"files": ["dist"]
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
35
81
|
## Options
|
|
36
82
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
83
|
+
```ts
|
|
84
|
+
svelte({
|
|
85
|
+
root: process.cwd(),
|
|
86
|
+
src: 'src',
|
|
87
|
+
out: 'dist',
|
|
88
|
+
preprocess: vitePreprocess({ script: true }),
|
|
89
|
+
dts: true
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
| Option | Default | What it does |
|
|
94
|
+
| ------------ | ---------------------------------- | --------------------------------------------------------------- |
|
|
95
|
+
| `root` | `process.cwd()` | The package root that `src` and `out` are relative to. |
|
|
96
|
+
| `src` | `'src'` | Where your components and `.css` files live. |
|
|
97
|
+
| `out` | `'dist'` | Where they are written. Match tsdown's `outDir`. |
|
|
98
|
+
| `preprocess` | `vitePreprocess({ script: true })` | Svelte preprocessors for the script and styles (one or a list). |
|
|
99
|
+
| `dts` | `true` | Write a `.svelte.d.ts` beside each component. |
|
|
100
|
+
|
|
101
|
+
In a monorepo, set `root` to the package's own folder when tsdown runs from somewhere else:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
svelte({ root: fileURLToPath(new URL('.', import.meta.url)) });
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## How it works
|
|
44
108
|
|
|
45
|
-
|
|
109
|
+
1. At the start of the build, every `.svelte` under `src` is run through your preprocessors, which turns its `<script lang="ts">` into JS.
|
|
110
|
+
2. Svelte's parser then reads the file once more, still as TypeScript, and every type-only span in the template is cut out: `as` and `satisfies` casts, `!` assertions, annotations and generic arguments. `lang="ts"` is removed from each script.
|
|
111
|
+
3. The result is emitted as a build asset at the same path in `out`. Emitting assets, rather than writing files, means tsdown's `clean` never wipes them.
|
|
112
|
+
4. After the bundle is written, svelte2tsx generates declarations into a scratch folder, and only the `*.svelte.d.ts` files are copied next to the components. tsdown keeps owning the declarations for your `.ts` files.
|
|
113
|
+
|
|
114
|
+
## Using the TypeScript strip on its own
|
|
115
|
+
|
|
116
|
+
`strip_markup_ts` is exported for tools that ship Svelte source another way. Run it on the output of `preprocess()`, when the script is JS but the template still has types:
|
|
46
117
|
|
|
47
118
|
```ts
|
|
48
119
|
import { preprocess } from 'svelte/compiler';
|
|
@@ -52,8 +123,6 @@ const { code } = await preprocess(source, preprocessors, { filename });
|
|
|
52
123
|
const plain_js = strip_markup_ts(code, filename);
|
|
53
124
|
```
|
|
54
125
|
|
|
55
|
-
It uses Svelte's own parser, so it only ever removes type syntax, never a look-alike in a string or comment.
|
|
56
|
-
|
|
57
126
|
## License
|
|
58
127
|
|
|
59
|
-
MIT
|
|
128
|
+
[MIT](./LICENSE)
|
package/package.json
CHANGED