better-svelte-email 0.3.1 → 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anatole Dufour
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,37 +1,58 @@
-# better-svelte-email
-
-[![Tests](https://github.com/Konixy/better-svelte-email/actions/workflows/release.yml/badge.svg)](https://github.com/Konixy/better-svelte-email/actions/workflows/release.yml)
-[![npm version](https://img.shields.io/npm/v/better-svelte-email.svg?logo=npm)](https://www.npmjs.com/package/better-svelte-email)
-[![GitHub stars](https://img.shields.io/github/stars/Konixy/better-svelte-email?style=default&logo=github)](https://github.com/Konixy/better-svelte-email/stargazers)
-
-A Svelte preprocessor that transforms Tailwind CSS classes in email components to inline styles with responsive media query support.
+<p align="center">
+  <h3 align="center">Better Svelte Email</h3>
+	<p align="center">
+		Create beautiful emails in Svelte with first-class Tailwind support
+	</p>
+	<p align="center">
+		<a href="https://better-svelte-email.konixy.fr">Website</a>
+		 · 
+		<a href="https://github.com/Konixy/better-svelte-email">GitHub</a>
+	</p>
+  <p align="center">
+    <a href="https://github.com/Konixy/better-svelte-email/actions/workflows/release.yml">
+      <img src="https://github.com/Konixy/better-svelte-email/actions/workflows/release.yml/badge.svg" alt="Tests">
+    </a>
+    <a href="https://www.npmjs.com/package/better-svelte-email">
+      <img src="https://img.shields.io/npm/v/better-svelte-email.svg?logo=npm" alt="npm version">
+    </a>
+    <a href="https://github.com/Konixy/better-svelte-email/stargazers">
+      <img src="https://img.shields.io/github/stars/Konixy/better-svelte-email?style=default&logo=github" alt="GitHub stars">
+    </a>
+  </p>
+</p>
 
 ## Features
 
-✨ **Stable & Future-Proof** - Uses Svelte's public preprocessor API  
-🎨 **Tailwind CSS Support** - Transforms Tailwind classes to inline styles for email clients  
-📱 **Responsive Emails** - Preserves responsive classes (`sm:`, `md:`, `lg:`) as media queries  
-⚡ **Build-Time Transformation** - Zero runtime overhead  
-🔍 **TypeScript First** - Fully typed with comprehensive type definitions  
-✅ **Well Tested** - Extensive test coverage with unit and integration tests
+- **Stable & Future-Proof** - Uses Svelte's public preprocessor API
+- **Tailwind CSS Support** - Transforms Tailwind classes to inline styles for email clients
+- **Built-in Email Preview** - Visual email preview and test sending
+- **TypeScript First** - Fully typed with comprehensive type definitions
+- **Well Tested** - Extensive test coverage with unit and integration tests
+
+_See [Roadmap](./ROADMAP.md) for future features and planned improvements._
 
 ## Why?
 
-Email clients don't support modern CSS in `<style>` tags, requiring inline styles. But writing inline styles is tedious and hard to maintain. This preprocessor lets you write Tailwind CSS classes and automatically transforms them to inline styles at build time.
+Existing Svelte email solutions have significant limitations:
+
+- **svelte-email** hasn't been updated in over 2 years
+- **svelte-email-tailwind** suffers from stability issues and maintaining it is not sustainable anymore
+
+Better Svelte Email is a complete rewrite built on Svelte's official preprocessor API, providing the rock-solid foundation your email infrastructure needs. It brings the simplicity, reliability, and feature richness of [React Email](https://react.email/) to the Svelte ecosystem.
+
+## Quick Start
 
-## Installation
+### 1. Install the package
 
 ```bash
-npm install better-svelte-email
+npm i -D better-svelte-email
 # or
-bun add better-svelte-email
+bun add -D better-svelte-email
 # or
-pnpm add better-svelte-email
+pnpm add -D better-svelte-email
 ```
 
-## Quick Start
-
-### 1. Configure the Preprocessor
+### 2. Configure the Preprocessor
 
 Add the preprocessor to your `svelte.config.js`:
 
@@ -41,13 +62,7 @@ import { betterSvelteEmailPreprocessor } from 'better-svelte-email';
 
 /** @type {import('@sveltejs/kit').Config} */
 const config = {
-	preprocess: [
-		vitePreprocess(),
-		betterSvelteEmailPreprocessor({
-			pathToEmailFolder: '/src/lib/emails',
-			debug: false
-		})
-	],
+	preprocess: [vitePreprocess(), betterSvelteEmailPreprocessor()],
 	kit: {
 		adapter: adapter()
 	}
@@ -56,19 +71,22 @@ const config = {
 export default config;
 ```
 
-### 2. Create Email Components
+### 3. Create Email Components
 
 Create your email templates in `src/lib/emails/`:
 
 ```svelte
 <!-- src/lib/emails/welcome.svelte -->
 <script>
+	import { Html, Head, Body, Preview, Container, Text, Button } from 'better-svelte-email';
+
 	let { name = 'User' } = $props();
 </script>
 
 <Html>
 	<Head />
 	<Body class="bg-gray-100">
+		<Preview preview="Welcome Email" />
 		<Container class="mx-auto p-8">
 			<Text class="mb-4 text-2xl font-bold">
 				Welcome, {name}!
@@ -76,7 +94,7 @@ Create your email templates in `src/lib/emails/`:
 
 			<Button
 				href="https://example.com"
-				class="rounded bg-blue-600 px-6 py-3 text-white sm:bg-green-600"
+				class="rounded bg-orange-600 px-6 py-3 text-white sm:text-sm"
 			>
 				Get Started
 			</Button>
@@ -85,7 +103,7 @@ Create your email templates in `src/lib/emails/`:
 </Html>
 ```
 
-### 3. Render and Send
+### 4. Render and Send
 
 ```typescript
 // src/routes/api/send-email/+server.ts
@@ -110,89 +128,90 @@ export async function POST({ request }) {
 }
 ```
 
-## How It Works
+## Email Preview Component
+
+Better Svelte Email includes a built-in preview component for visually developing and testing your email templates during development.
 
-The preprocessor transforms your Tailwind classes in three steps:
+### Setup
 
-### 1. Non-Responsive Classes → Inline Styles
+Create a preview route in your SvelteKit app:
 
 ```svelte
-<!-- Input -->
-<Button class="bg-blue-500 p-4 text-white">Click</Button>
-
-<!-- Output -->
-<Button
-	styleString="background-color: rgb(59, 130, 246); color: rgb(255, 255, 255); padding: 16px;"
->
-	Click
-</Button>
+<!-- src/routes/preview/+page.svelte -->
+<script lang="ts">
+	import { EmailPreview } from 'better-svelte-email/preview';
+
+	let { data } = $props();
+</script>
+
+<EmailPreview emailList={data.emails} />
 ```
 
-### 2. Responsive Classes → Media Queries
+```typescript
+// src/routes/preview/+page.server.ts
+import { emailList, createEmail, sendEmail } from 'better-svelte-email/preview';
+import { env } from '$env/dynamic/private';
 
-```svelte
-<!-- Input -->
-<Button class="bg-blue-500 sm:bg-red-500">Click</Button>
+export function load() {
+	const emails = emailList({
+		path: '/src/lib/emails' // optional, defaults to '/src/lib/emails'
+	});
 
-<!-- Output -->
-<Button class="sm_bg-red-500" styleString="background-color: rgb(59, 130, 246);">Click</Button>
+	return { emails };
+}
 
-<!-- Injected into <Head> -->
-<style>
-	@media (max-width: 475px) {
-		.sm_bg-red-500 {
-			background-color: rgb(239, 68, 68) !important;
-		}
-	}
-</style>
+export const actions = {
+	...createEmail,
+	...sendEmail({ resendApiKey: env.RESEND_API_KEY })
+};
 ```
 
-### 3. Mixed Classes → Both
+### Features
 
-```svelte
-<!-- Input -->
-<Button class="rounded bg-blue-500 p-4 sm:bg-red-500 md:p-6">Click</Button>
-
-<!-- Output -->
-<Button
-	class="sm_bg-red-500 md_p-6"
-	styleString="border-radius: 4px; background-color: rgb(59, 130, 246); padding: 16px;"
->
-	Click
-</Button>
+- **HTML Source View** - Inspect the generated HTML with syntax highlighting
+- **Copy to Clipboard** - Quickly copy the rendered HTML
+- **Test Email Sending** - Send test emails directly from the preview UI using Resend
+- **Template List** - Browse all your email templates in one place
+
+### Environment Variables
+
+To enable test email sending, add your Resend API key to your `.env` file:
+
+```env
+RESEND_API_KEY=re_your_api_key_here
 ```
 
-## Configuration
+Get your API key from [Resend](https://resend.com/).
+
+### Custom Email Provider
 
-### Options
+If you prefer to use a different email provider, you can pass a custom send function:
 
 ```typescript
-interface PreprocessorOptions {
-	/**
-	 * Path to folder containing email components
-	 * @default '/src/lib/emails'
-	 */
-	pathToEmailFolder?: string;
-
-	/**
-	 * Custom Tailwind configuration
-	 * @default undefined
-	 */
-	tailwindConfig?: TailwindConfig;
-
-	/**
-	 * Enable debug logging
-	 * @default false
-	 */
-	debug?: boolean;
-}
+export const actions = {
+	...createEmail,
+	...sendEmail({
+		customSendEmailFunction: async ({ from, to, subject, html }) => {
+			// Use your preferred email service (SendGrid, Mailgun, etc.)
+			try {
+				await yourEmailService.send({ from, to, subject, html });
+				return { success: true };
+			} catch (error) {
+				return { success: false, error };
+			}
+		}
+	})
+};
 ```
 
-### Custom Tailwind Config
+## Configuration
+
+Here are the available options:
 
 ```javascript
 betterSvelteEmailPreprocessor({
 	pathToEmailFolder: '/src/lib/emails',
+	debug: false,
 	tailwindConfig: {
 		theme: {
 			extend: {
@@ -205,12 +224,18 @@ betterSvelteEmailPreprocessor({
 });
 ```
 
+## Minimum Svelte Version
+
+The minimum supported Svelte version is 5.14.3.
+For older versions, you can use [`svelte-email-tailwind`](https://github.com/steveninety/svelte-email-tailwind).
+
 ## Supported Features
 
 ### ✅ Supported
 
 - ✅ Static Tailwind classes
-- ✅ All standard Tailwind utilities (colors, spacing, typography, etc.)
+- ✅ Custom Tailwind classes (`bg-[#fff]`, `my:[40px]`, ...)
+- ✅ All standard Tailwind (v3) utilities (colors, spacing, typography, etc.)
 - ✅ Responsive breakpoints (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)
 - ✅ HTML elements and Svelte components
 - ✅ Nested components
@@ -218,133 +243,24 @@ betterSvelteEmailPreprocessor({
 - ✅ Each blocks (`{#each}`)
 - ✅ Custom Tailwind configurations
 
-### ❌ Not Supported (Yet)
+### ❌ Not Supported (Yet) (See [Roadmap](./ROADMAP.md))
 
+- ❌ Tailwind v4
+- ❌ CSS Object (`style={{ color: 'red' }}`)
 - ❌ Dynamic class expressions (`class={someVar}`)
 - ❌ Arbitrary values in responsive classes (`sm:[color:red]`)
 - ❌ Container queries
 
-## API Reference
-
-### Main Export
-
-```typescript
-import { betterSvelteEmailPreprocessor } from 'better-svelte-email';
-```
-
-### Advanced Exports
-
-For advanced use cases, you can use individual functions:
-
-```typescript
-import {
-	parseClassAttributes,
-	transformTailwindClasses,
-	generateMediaQueries,
-	injectMediaQueries
-} from 'better-svelte-email';
-```
-
-## Testing
-
-The library includes comprehensive tests:
-
-```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with UI
-npm run test:ui
-
-# Run tests with coverage
-npm run test:coverage
-```
-
-## Examples
-
-### Simple Button
-
-```svelte
-<Button class="rounded bg-blue-500 px-4 py-2 text-white">Click Me</Button>
-```
-
-### Responsive Layout
-
-```svelte
-<Container class="mx-auto w-full max-w-2xl p-4 sm:p-6 md:p-8">
-	<Text class="text-lg sm:text-xl md:text-2xl">Responsive Text</Text>
-</Container>
-```
-
-### Complex Email
-
-```svelte
-<Html>
-	<Head />
-	<Body class="bg-gray-100 font-sans">
-		<Container class="mx-auto my-8 max-w-2xl rounded-lg bg-white shadow-lg">
-			<Section class="p-8">
-				<Text class="mb-4 text-3xl font-bold text-gray-900">Welcome to Our Service</Text>
-
-				<Text class="mb-6 text-gray-600">
-					Thank you for signing up. We're excited to have you on board!
-				</Text>
-
-				<Button
-					href="https://example.com/verify"
-					class="rounded-lg bg-blue-600 px-8 py-4 font-semibold text-white sm:bg-green-600"
-				>
-					Verify Your Email
-				</Button>
-			</Section>
-		</Container>
-	</Body>
-</Html>
-```
-
-## Troubleshooting
-
-### Classes not being transformed
-
-1. Make sure your file is in the configured `pathToEmailFolder`
-2. Check that your classes are static strings, not dynamic expressions
-3. Enable debug mode to see warnings: `{ debug: true }`
-
-### Media queries not working
-
-1. Ensure you have a `<Head />` component in your email
-2. Check that you're using standard breakpoints (`sm:`, `md:`, etc.)
-3. Verify the media queries are being injected (view the rendered HTML)
-
-### Type errors
-
-Make sure you have the latest version of Svelte (requires 5.14.3 or higher):
-
-```bash
-npm install svelte@latest
-```
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## License
-
-MIT
-
 ## Author
 
-Konixy
+Anatole Dufour ([@Konixy](https://github.com/Konixy))
 
 ## Development
 
 ### Running Tests
 
 ```bash
-bun test
+bun run test
 ```
 
 All tests must pass before pushing to main. The CI/CD pipeline will automatically run tests on every push and pull request.
@@ -357,36 +273,23 @@ bun run build
 
 ### Contributing
 
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+To do so, you'll need to:
+
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+2. Create a feature branch (`git checkout -b feat/amazing-feature`)
 3. Make your changes
-4. Run tests (`bun test`)
+4. Run tests (`bun run test`)
 5. Commit your changes using [conventional commits](https://www.conventionalcommits.org/):
    - `feat:` - New features
    - `fix:` - Bug fixes
    - `docs:` - Documentation changes
    - `test:` - Test additions/changes
    - `chore:` - Maintenance tasks
-6. Push to your branch (`git push origin feature/amazing-feature`)
+6. Push to your branch (`git push origin feat/amazing-feature`)
 7. Open a Pull Request
 
-### Releases
-
-Releases are automated via GitHub Actions. When you bump the version in `package.json` and push to `main`, a new release will be automatically created with a generated changelog.
-
-See [RELEASE.md](./RELEASE.md) for detailed release process documentation.
-
-## Acknowledgments
-
-- Built on top of [Svelte 5](https://svelte.dev/)
-- Uses [tw-to-css](https://github.com/dvkndn/tw-to-css) for Tailwind to CSS conversion
-- Uses [magic-string](https://github.com/rich-harris/magic-string) for efficient source transformations
-
-## Related Projects
-
-- [react-email](https://react.email/) - React version for email templates
-- [svelte-email](https://github.com/carstenlebek/svelte-email) - Original Svelte email library
-
-## Support
+## Acknowledgements
 
-If you find this project useful, please consider giving it a ⭐️ on GitHub!
+Many components and logic were inspired by or adapted from [svelte-email-tailwind](https://github.com/steveninety/svelte-email-tailwind) and [react-email](https://react.email/). Huge thanks to the authors and contributors of these projects for their excellent work.