@ts-svg/svelte 0.0.1-beta.0 → 0.0.1

package/README.md

@@ -0,0 +1,226 @@
+# ts-svg
+
+Type-safe SVG bundling for Vite. `ts-svg` scans a directory (including subdirectories), generates **typed virtual modules**, and lets you import SVGs as framework components with great DX (autocomplete + type checking) and proper bundling/tree-shaking.
+
+## Why ts-svg?
+
+- **Type-safe imports**: virtual modules are generated with types, so importing from `virtual:ts-svg/...` is typed.
+- **Great DX**: namespace import + `<Icon.` gives instant autocomplete for every icon in that folder.
+- **Optimized output**: SVGs are optimized (SVGO) and transformed into **Svelte components**.
+- **Tree-shakable**: only the SVGs you actually use end up bundled.
+
+## Packages
+
+- **Svelte / SvelteKit:** `@ts-svg/svelte`
+- (Other framework adapters will be available soon)
+
+---
+
+## SvelteKit Setup (`@ts-svg/svelte`)
+
+### 1) Install
+
+```bash
+npm i -D @ts-svg/svelte
+```
+
+### 2) Add the Vite plugin
+
+Add `tsSvg()` to `vite.config.ts`. The `path` option is required.
+
+```ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+import { tsSvg } from '@ts-svg/svelte';
+
+export default defineConfig({
+	plugins: [
+		sveltekit(),
+		// Step 1: Add the vite plugin
+		tsSvg({
+			path: './src/lib/svgs',
+			// svgoConfig: {...} // optional: override default SVGO config
+		}),
+	],
+});
+```
+
+`path` is the folder to scan. All `.svg` files inside it (and subfolders) become typed virtual modules.
+
+### 3) Reference the generated ambient types
+
+In `src/app.d.ts`, add a reference to the generated `ambient.d.ts`:
+
+```ts
+// Step 2: Import the generated types
+/// <reference types="../.ts-svg/ambient.d.ts" />
+```
+
+### 4) Ignore the generated directory
+
+Add `.ts-svg` to both `.gitignore` and `.prettierignore`:
+
+```gitignore
+.ts-svg
+```
+
+### 5) Generate types in CI (recommended)
+
+In CI (or any non-dev environment), you may not want to rely on the dev server to trigger generation.
+Prepend the CLI `ts-svg` in `package.json` scripts that run in CI:
+
+```json
+{
+	"scripts": {
+		"prepare": "ts-svg && svelte-kit sync || echo ''",
+		"check": "ts-svg && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "ts-svg && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+	}
+}
+```
+
+---
+
+## Usage
+
+Put SVGs under the directory you configured (e.g. `./src/lib/svgs`).
+
+Then import from `virtual:ts-svg`:
+
+- Root folder: `virtual:ts-svg`
+- Subfolder: `virtual:ts-svg/<subfolder>`
+
+### Recommended: namespace import for icon folders
+
+If you have `./src/lib/svgs/icons/*.svg`:
+
+```svelte
+<script lang="ts">
+	import * as Icon from 'virtual:ts-svg/icons'; // recommended
+	// or import one-by-one:
+	import { Home } from 'virtual:ts-svg/icons';
+</script>
+
+<Icon.Book class="size-200" />
+<Home />
+
+<style>
+	:global(.size-200) {
+		width: 200px;
+		height: 200px;
+	}
+
+	:global(svg) {
+		width: 150px;
+		height: 150px;
+	}
+</style>
+```
+
+Typing `<Icon.` will show all icons in autocomplete.
+
+### Props
+
+Imported SVGs are Svelte components and accept normal props (e.g. `class`, `style`, etc.).
+
+For a complete SvelteKit example (config, generated types, and usage), see the sample setup here: [examples/sveltekit](https://github.com/chunnamwong/ts-svg/tree/main/examples/svelte).
+
+---
+
+## Tip: Create a local re-export for nicer imports
+
+If it’s hard to remember import paths like `virtual:ts-svg/icons`, you can create a local module and re-export your namespace.
+
+Create `src/lib/Icon.ts`:
+
+```ts
+export * as Icon from 'virtual:ts-svg/icons';
+```
+
+Then import from your app code:
+
+```svelte
+<script lang="ts">
+    import { Icon } from '$lib/Icon';
+</script>
+```
+
+You can do the same pattern for other subdirectories (e.g. `brand`, `images`, etc.):
+
+---
+
+## Configuration
+
+### `path` (required)
+
+The directory to scan for `.svg` files.
+
+### `svgoConfig` (optional)
+
+Override the default SVGO configuration used during optimization.
+
+```ts
+tsSvg({
+	path: './src/lib/svgs',
+	svgoConfig: {
+		// your custom svgo config
+	},
+});
+```
+
+---
+
+## Generated output
+
+`ts-svg` generates this file:
+
+- `.ts-svg/ambient.d.ts` (referenced from `src/app.d.ts`)
+
+---
+
+## FAQ
+
+### Do I need to commit `.ts-svg`?
+
+No. It’s generated output. Add it to `.gitignore` and regenerate it in CI using `ts-svg` in your scripts.
+
+### How do subfolders map to imports?
+
+A subfolder becomes an import path segment.
+
+Example:
+
+- `src/lib/svgs/icons/Home.svg` → `import { Home } from 'virtual:ts-svg/icons'`
+
+### How do I stay safe with tree shaking?
+
+Tree-shaking works best when the bundler can see **exactly which exports you use**.
+
+If you use a namespace import:
+
+```ts
+import * as Icon from 'virtual:ts-svg/icons';
+```
+
+✅ **Do** access **specific exports**:
+
+```svelte
+<Icon.Home />
+<Icon.Book />
+```
+
+⚠️ **Don’t** pass around or “touch” the whole namespace object (e.g. iterating keys, spreading, or indexing dynamically). If the bundler detects the namespace object itself is used as a value, it may conservatively treat **all exports as used**, which can cause **all icons to be bundled**, even if you only use a few.
+
+Examples to avoid:
+
+```ts
+Object.keys(Icon); // iterating namespace
+const Comp = Icon[name]; // dynamic access
+const list = { ...Icon }; // spreading namespace
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-svg/svelte",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.1",
   "description": "Vite Plugin for loading all svg files inside a folder with types.",
   "keywords": [
     "vite-plugin",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "svgo": "^4.0.0",
-    "@ts-svg/core": "^0.0.1-beta.0"
+    "@ts-svg/core": "^0.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.6.0"

package/src/index.js

@@ -45,7 +45,7 @@ declare module '*.svg?svelte' {
 	export default component;
 }
 `,
-		async transform(_code, id) {
+		async transform(_code, id, options) {
 			if (!id.endsWith('.svg?svelte')) {
 				return;
 			}
@@ -57,7 +57,7 @@ declare module '*.svg?svelte' {
 			);
 			const componentCode = optimizedSvgSource.replace(/<svg([^>]*)>/, '<svg$1 {...$$$$props}>');
 			const component = compile(componentCode, {
-				generate: this.environment.name === 'ssr' ? 'server' : undefined,
+				generate: options?.ssr ? 'server' : undefined,
 			});
 			return {
 				code: component.js.code,