better-svelte-email 1.1.0-beta.0 → 1.2.0

package/README.md

@@ -61,6 +61,7 @@ For older versions, you can use [`svelte-email-tailwind`](https://github.com/ste
 - Nested components
 - All svelte features such as each blocks (`{#each}`) and if blocks (`{#if}`), and more
 - Custom Tailwind configurations
+- Custom CSS injection (for app theme integration)
 
 ## Author
 

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export * from './components/index.js';
-export { default as Renderer, toPlainText, type TailwindConfig, type RenderOptions } from './render/index.js';
+export { default as Renderer, toPlainText, type TailwindConfig, type RendererOptions, type RenderOptions } from './render/index.js';

package/dist/preview/index.d.ts

@@ -49,10 +49,12 @@ export declare const getEmailComponent: (emailPath: string, file: string) => Pro
  * import Renderer from 'better-svelte-email/render';
  *
  * const renderer = new Renderer({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: '#FF3E00'
+ *   tailwindConfig: {
+ *     theme: {
+ *       extend: {
+ *         colors: {
+ *           brand: '#FF3E00'
+ *         }
  *       }
  *     }
  *   }
@@ -108,17 +110,19 @@ export declare const SendEmailFunction: ({ from, to, subject, html }: {
  * import Renderer from 'better-svelte-email/render';
  *
  * const renderer = new Renderer({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: '#FF3E00'
+ *   tailwindConfig: {
+ *     theme: {
+ *       extend: {
+ *         colors: {
+ *           brand: '#FF3E00'
+ *         }
  *       }
  *     }
  *   }
  * });
  *
  * export const actions = {
- *   ...createEmail(renderer),
+ *   ...createEmail({ renderer }),
  *   ...sendEmail({ resendApiKey: PRIVATE_RESEND_API_KEY, renderer })
  * };
  * ```

package/dist/preview/index.js

@@ -98,10 +98,12 @@ const getEmailSource = async (emailPath, file) => {
  * import Renderer from 'better-svelte-email/render';
  *
  * const renderer = new Renderer({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: '#FF3E00'
+ *   tailwindConfig: {
+ *     theme: {
+ *       extend: {
+ *         colors: {
+ *           brand: '#FF3E00'
+ *         }
  *       }
  *     }
  *   }
@@ -176,17 +178,19 @@ const defaultSendEmailFunction = async ({ from, to, subject, html }, resendApiKe
  * import Renderer from 'better-svelte-email/render';
  *
  * const renderer = new Renderer({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: '#FF3E00'
+ *   tailwindConfig: {
+ *     theme: {
+ *       extend: {
+ *         colors: {
+ *           brand: '#FF3E00'
+ *         }
  *       }
  *     }
  *   }
  * });
  *
  * export const actions = {
- *   ...createEmail(renderer),
+ *   ...createEmail({ renderer }),
  *   ...sendEmail({ resendApiKey: PRIVATE_RESEND_API_KEY, renderer })
  * };
  * ```

package/dist/render/index.d.ts

@@ -2,6 +2,28 @@ import { type DefaultTreeAdapterTypes } from 'parse5';
 import type { Config } from 'tailwindcss';
 export type TailwindConfig = Omit<Config, 'content'>;
 export type { DefaultTreeAdapterTypes as AST };
+/**
+ * Options for creating a Renderer instance
+ */
+export type RendererOptions = {
+    /** Tailwind CSS configuration */
+    tailwindConfig?: TailwindConfig;
+    /**
+     * Custom CSS to inject into email rendering (e.g., app theme variables).
+     *
+     * This CSS is injected during Tailwind compilation, making variables and styles
+     * available for processing. Useful for maintaining consistent styling between
+     * your app and emails (e.g., shadcn-svelte theme variables).
+     *
+     *
+     * @example
+     * ```ts
+     * import appStyles from './app.css?raw';
+     * const renderer = new Renderer({ customCSS: appStyles });
+     * ```
+     */
+    customCSS?: string;
+};
 /**
  * Options for rendering a Svelte component
  */
@@ -16,13 +38,19 @@ export type RenderOptions = {
  * @example
  * ```ts
  * import Renderer from 'better-svelte-email/renderer';
- * import EmailComponent from './email.svelte';
+ * import EmailComponent from '../emails/email.svelte';
+ * import layoutStyles from 'src/routes/layout.css?raw';
  *
  * const renderer = new Renderer({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: '#FF3E00'
+ *   // Inject custom CSS such as app theme variables
+ *   customCSS: layoutStyles,
+ *   // Or provide a tailwind v3 config to extend the default theme
+ *   tailwindConfig: {
+ *     theme: {
+ *       extend: {
+ *         colors: {
+ *           brand: '#FF3E00'
+ *         }
  *       }
  *     }
  *   }
@@ -35,7 +63,9 @@ export type RenderOptions = {
  */
 export default class Renderer {
     private tailwindConfig;
+    private customCSS?;
     constructor(tailwindConfig?: TailwindConfig);
+    constructor(options?: RendererOptions);
     /**
      * Renders a Svelte component to email-safe HTML with inlined Tailwind CSS.
      *

package/dist/render/index.js

@@ -17,13 +17,19 @@ import { convert } from 'html-to-text';
  * @example
  * ```ts
  * import Renderer from 'better-svelte-email/renderer';
- * import EmailComponent from './email.svelte';
+ * import EmailComponent from '../emails/email.svelte';
+ * import layoutStyles from 'src/routes/layout.css?raw';
  *
  * const renderer = new Renderer({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: '#FF3E00'
+ *   // Inject custom CSS such as app theme variables
+ *   customCSS: layoutStyles,
+ *   // Or provide a tailwind v3 config to extend the default theme
+ *   tailwindConfig: {
+ *     theme: {
+ *       extend: {
+ *         colors: {
+ *           brand: '#FF3E00'
+ *         }
  *       }
  *     }
  *   }
@@ -36,8 +42,22 @@ import { convert } from 'html-to-text';
  */
 export default class Renderer {
     tailwindConfig;
-    constructor(tailwindConfig = {}) {
-        this.tailwindConfig = tailwindConfig;
+    customCSS;
+    constructor(optionsOrConfig = {}) {
+        // Detect whether the argument is a bare TailwindConfig (old API)
+        // or a RendererOptions object (new API).
+        if (optionsOrConfig &&
+            typeof optionsOrConfig === 'object' &&
+            ('tailwindConfig' in optionsOrConfig || 'customCSS' in optionsOrConfig)) {
+            const options = optionsOrConfig;
+            this.tailwindConfig = options.tailwindConfig || {};
+            this.customCSS = options.customCSS;
+        }
+        else {
+            const config = optionsOrConfig;
+            this.tailwindConfig = config || {};
+            this.customCSS = undefined;
+        }
     }
     /**
      * Renders a Svelte component to email-safe HTML with inlined Tailwind CSS.
@@ -64,7 +84,7 @@ export default class Renderer {
         let ast = parse(body);
         ast = removeAttributesFunctions(ast);
         let classesUsed = [];
-        const tailwindSetup = await setupTailwind(this.tailwindConfig);
+        const tailwindSetup = await setupTailwind(this.tailwindConfig, this.customCSS);
         walk(ast, (node) => {
             if (isValidNode(node)) {
                 const classAttr = node.attrs?.find((attr) => attr.name === 'class');

package/dist/render/utils/css/resolve-all-css-variables.d.ts

@@ -3,6 +3,5 @@ export interface VariableDefinition {
     declaration: Declaration;
     selector: string;
     variableName: string;
-    definition: string;
 }
 export declare function resolveAllCssVariables(root: Root): void;

package/dist/render/utils/css/resolve-all-css-variables.js

@@ -1,4 +1,5 @@
 import valueParser from 'postcss-value-parser';
+const MAX_CSS_VARIABLE_RESOLUTION_ITERATIONS = 10;
 function getSelector(decl) {
     const parent = decl.parent;
     if (parent?.type === 'rule') {
@@ -57,79 +58,108 @@ function doSelectorsIntersect(first, second) {
     return false;
 }
 export function resolveAllCssVariables(root) {
-    const variableDefinitions = new Set();
-    const variableUses = [];
-    // First pass: collect variable definitions and uses
-    root.walkDecls((decl) => {
-        // Skip @layer (properties) { ... } to avoid variable resolution conflicts
-        if (isInPropertiesLayer(decl)) {
-            return;
-        }
-        if (decl.prop.startsWith('--')) {
-            variableDefinitions.add({
-                declaration: decl,
-                selector: getSelector(decl),
-                variableName: decl.prop,
-                definition: decl.value
-            });
-        }
-        else if (decl.value.includes('var(')) {
-            const parseVariableUses = (value) => {
-                const parsed = valueParser(value);
-                parsed.walk((node) => {
-                    if (node.type === 'function' && node.value === 'var') {
-                        const varNameNode = node.nodes[0];
-                        const varName = varNameNode ? valueParser.stringify(varNameNode).trim() : '';
-                        // Find fallback (after the comma)
-                        let fallback;
-                        const commaIndex = node.nodes.findIndex((n) => n.type === 'div' && n.value === ',');
-                        if (commaIndex !== -1) {
-                            fallback = valueParser.stringify(node.nodes.slice(commaIndex + 1)).trim();
-                        }
-                        const raw = valueParser.stringify(node);
-                        variableUses.push({
-                            declaration: decl,
-                            selector: getSelector(decl),
-                            inAtRule: isInAtRule(decl),
-                            atRuleSelector: getAtRuleSelector(decl),
-                            fallback,
-                            variableName: varName,
-                            raw
-                        });
-                        // If fallback contains var(), recursively parse those too
-                        if (fallback?.includes('var(')) {
-                            parseVariableUses(fallback);
-                        }
-                    }
+    let iteration = 0;
+    while (iteration < MAX_CSS_VARIABLE_RESOLUTION_ITERATIONS) {
+        const variableDefinitions = new Set();
+        const variableUses = [];
+        // First pass: collect variable definitions and uses
+        root.walkDecls((decl) => {
+            // Skip @layer (properties) { ... } to avoid variable resolution conflicts
+            if (isInPropertiesLayer(decl)) {
+                return;
+            }
+            if (decl.prop.startsWith('--')) {
+                variableDefinitions.add({
+                    declaration: decl,
+                    selector: getSelector(decl),
+                    variableName: decl.prop
                 });
-            };
-            parseVariableUses(decl.value);
-        }
-    });
-    // Second pass: resolve variables
-    for (const use of variableUses) {
-        let hasReplaced = false;
-        for (const definition of variableDefinitions) {
-            if (use.variableName !== definition.variableName) {
-                continue;
             }
-            // Check if use is in an at-rule and definition is in a matching rule
-            if (use.inAtRule &&
-                use.atRuleSelector &&
-                doSelectorsIntersect(use.atRuleSelector, definition.selector)) {
-                use.declaration.value = use.declaration.value.replaceAll(use.raw, definition.definition);
-                hasReplaced = true;
-                break;
+            if (decl.value.includes('var(')) {
+                const parseVariableUses = (value) => {
+                    const parsed = valueParser(value);
+                    parsed.walk((node) => {
+                        if (node.type === 'function' && node.value === 'var') {
+                            const varNameNode = node.nodes[0];
+                            const varName = varNameNode ? valueParser.stringify(varNameNode).trim() : '';
+                            // Find fallback (after the comma)
+                            let fallback;
+                            const commaIndex = node.nodes.findIndex((n) => n.type === 'div' && n.value === ',');
+                            if (commaIndex !== -1) {
+                                fallback = valueParser.stringify(node.nodes.slice(commaIndex + 1)).trim();
+                            }
+                            const raw = valueParser.stringify(node);
+                            variableUses.push({
+                                declaration: decl,
+                                selector: getSelector(decl),
+                                inAtRule: isInAtRule(decl),
+                                atRuleSelector: getAtRuleSelector(decl),
+                                fallback,
+                                variableName: varName,
+                                raw
+                            });
+                            // If fallback contains var(), recursively parse those too
+                            if (fallback?.includes('var(')) {
+                                parseVariableUses(fallback);
+                            }
+                        }
+                    });
+                };
+                parseVariableUses(decl.value);
             }
-            // Check if both are in rules with matching selectors
-            if (!use.inAtRule && doSelectorsIntersect(use.selector, definition.selector)) {
-                use.declaration.value = use.declaration.value.replaceAll(use.raw, definition.definition);
-                hasReplaced = true;
-                break;
+        });
+        // Early exit: If no variable uses found, we're done
+        if (variableUses.length === 0) {
+            break;
+        }
+        // Second pass: resolve variables
+        let replacedInThisIteration = false;
+        for (const use of variableUses) {
+            let hasReplaced = false;
+            for (const definition of variableDefinitions) {
+                if (use.variableName !== definition.variableName) {
+                    continue;
+                }
+                // Check if use is in an at-rule and definition is in a matching rule
+                if (use.inAtRule &&
+                    use.atRuleSelector &&
+                    doSelectorsIntersect(use.atRuleSelector, definition.selector)) {
+                    use.declaration.value = use.declaration.value.replaceAll(use.raw, definition.declaration.value);
+                    hasReplaced = true;
+                    replacedInThisIteration = true;
+                    break;
+                }
+                // Check if use is in a top-level at-rule (no atRuleSelector) and definition is in :root or universal
+                if (use.inAtRule &&
+                    !use.atRuleSelector &&
+                    (definition.selector.includes(':root') || definition.selector === '*')) {
+                    use.declaration.value = use.declaration.value.replaceAll(use.raw, definition.declaration.value);
+                    hasReplaced = true;
+                    replacedInThisIteration = true;
+                    break;
+                }
+                // Check if both are in rules with matching selectors
+                if (!use.inAtRule && doSelectorsIntersect(use.selector, definition.selector)) {
+                    use.declaration.value = use.declaration.value.replaceAll(use.raw, definition.declaration.value);
+                    hasReplaced = true;
+                    replacedInThisIteration = true;
+                    break;
+                }
+            }
+            if (!hasReplaced && use.fallback) {
+                use.declaration.value = use.declaration.value.replaceAll(use.raw, use.fallback);
+                replacedInThisIteration = true;
             }
         }
-        if (!hasReplaced && use.fallback) {
-            use.declaration.value = use.declaration.value.replaceAll(use.raw, use.fallback);
+        // Early exit: If nothing was replaced, no point continuing
+        if (!replacedInThisIteration) {
+            break;
         }
+        iteration++;
+    }
+    // Warning for circular references
+    if (iteration === MAX_CSS_VARIABLE_RESOLUTION_ITERATIONS) {
+        console.warn(`[better-svelte-email] CSS variable resolution hit maximum iterations (${MAX_CSS_VARIABLE_RESOLUTION_ITERATIONS}). ` +
+            `This may indicate circular variable references.`);
     }
 }

package/dist/render/utils/tailwindcss/sanitize-custom-css.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeCustomCss(css: string): string;

package/dist/render/utils/tailwindcss/sanitize-custom-css.js

@@ -0,0 +1,10 @@
+import postcss from 'postcss';
+export function sanitizeCustomCss(css) {
+    const root = postcss.parse(css);
+    root.walkAtRules((atRule) => {
+        if (atRule.name === 'import' || atRule.name === 'plugin') {
+            atRule.remove();
+        }
+    });
+    return root.toString();
+}

package/dist/render/utils/tailwindcss/setup-tailwind.d.ts

@@ -1,7 +1,12 @@
 import { type Root } from 'postcss';
 import type { TailwindConfig } from '../../index.js';
 export type TailwindSetup = Awaited<ReturnType<typeof setupTailwind>>;
-export declare function setupTailwind(config: TailwindConfig): Promise<{
+/**
+ * Set up Tailwind CSS compiler with optional custom CSS injection
+ * @param config - Tailwind configuration
+ * @param customCSS - Optional custom CSS string to inject (e.g., your theme CSS variables)
+ */
+export declare function setupTailwind(config: TailwindConfig, customCSS?: string): Promise<{
     addUtilities: (candidates: string[]) => void;
     getStyleSheet: () => Root;
 }>;

package/dist/render/utils/tailwindcss/setup-tailwind.js

@@ -4,11 +4,19 @@ import indexCss from './tailwind-stylesheets/index.js';
 import preflightCss from './tailwind-stylesheets/preflight.js';
 import themeCss from './tailwind-stylesheets/theme.js';
 import utilitiesCss from './tailwind-stylesheets/utilities.js';
-export async function setupTailwind(config) {
+import { sanitizeCustomCss } from './sanitize-custom-css.js';
+/**
+ * Set up Tailwind CSS compiler with optional custom CSS injection
+ * @param config - Tailwind configuration
+ * @param customCSS - Optional custom CSS string to inject (e.g., your theme CSS variables)
+ */
+export async function setupTailwind(config, customCSS) {
+    // Inject customCSS after base imports for theme variable resolution during compilation
     const baseCss = `
 @layer theme, base, components, utilities;
 @import "tailwindcss/theme.css" layer(theme);
 @import "tailwindcss/utilities.css" layer(utilities);
+${customCSS ? sanitizeCustomCss(customCSS) : ''}
 @config;
 `;
     const compiler = await compile(baseCss, {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "better-svelte-email",
 	"description": "Svelte email renderer with Tailwind support",
-	"version": "1.1.0-beta.0",
+	"version": "1.2.0",
 	"author": "Konixy",
 	"repository": {
 		"type": "git",
@@ -38,7 +38,7 @@
 		"@sveltejs/vite-plugin-svelte": "^6.2.1",
 		"@tailwindcss/vite": "^4.1.17",
 		"@types/html-to-text": "^9.0.4",
-		"@types/node": "^24.10.1",
+		"@types/node": "22",
 		"@vitest/coverage-v8": "^4.0.14",
 		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",
@@ -51,7 +51,7 @@
 		"publint": "^0.3.15",
 		"rehype-autolink-headings": "^7.1.0",
 		"rehype-slug": "^6.0.0",
-		"svelte": "5.44.0",
+		"svelte": "5.45.2",
 		"svelte-check": "^4.3.4",
 		"tailwindcss-motion": "^1.1.1",
 		"typescript": "^5.9.3",
@@ -119,7 +119,7 @@
 		"build": "bun run prepack && vite build",
 		"preview": "vite preview",
 		"package": "svelte-package",
-		"package:watch": "nodemon -x \"bun run package\" -i dist -e ts,svelte",
+		"package:watch": "svelte-package --watch",
 		"prepare": "svelte-kit sync || echo ''",
 		"prepack": "svelte-kit sync && svelte-package && publint",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",