Email dev server

For v2, the recommended workflow is the @better-svelte-email/cli command-line tool. It starts a dedicated email preview server in any project folder: file watching, live reload, HTML/source views, and rendering through @better-svelte-email/server. You do not need a SvelteKit preview route.

Right now, dev is the only command the CLI provides; other subcommands may be added later.

@better-svelte-email/preview (deprecated)

The @better-svelte-email/preview package (EmailPreview, createEmail, sendEmail, SvelteKit +page.server.ts wiring) is deprecated. It remains published for backward compatibility with apps that already embed the inline preview. New projects should use @better-svelte-email/cli instead.

For the classic SvelteKit-integrated flow (v1-style, legacy package), see Email Preview.

Install the CLI

Pick one (or combine dev dependency + npx for CI).

Dev dependency (typical)

npm install -D @better-svelte-email/cli

The package exposes the bse binary in node_modules/.bin. Use npm scripts (see Run the dev server) or:

npx @better-svelte-email/cli dev

One-off / no install

npx @better-svelte-email/cli dev

This downloads and runs the CLI without adding it to package.json.

Global install

npm install -g @better-svelte-email/cli
bse dev

Your email templates should import primitives from @better-svelte-email/components. The CLI uses @better-svelte-email/server internally to render those components.

Run the dev server

From the project root (where package.json lives).

Without installing the package (uses npx):

npx @better-svelte-email/cli dev

After npm install -D @better-svelte-email/cli:

bse dev

After a global install:

bse dev

This watches src/lib/emails by default and serves the preview UI on port 3000, with JSON APIs under /api/* on the same origin. The CLI installs its internal @better-svelte-email/preview-server runtime automatically.

package.json script

// package.json — "scripts"
{
	"scripts": {
		"email:dev": "npx @better-svelte-email/cli dev"
	}
}

Equivalent if the CLI is installed locally (resolves node_modules/.bin/bse):

{
	"scripts": {
		"email:dev": "bse dev"
	}
}

Then:

npm run email:dev

Send test email (using Resend)

Use Send Email in the preview toolbar (next to Copy HTML) to send a test email using your Resend API key and sender address (defaults to onboarding@resend.dev). You can optionally save credentials to .bse/resend.json in the project; otherwise they last until you stop the dev server.

See cli flags to provide credentials from the command line.

CLI options

Custom emails directory

npx @better-svelte-email/cli dev -d src/emails

Tailwind / app styles

npx @better-svelte-email/cli dev -c src/app.css

Resend api key and sender address

Use Send Email in the preview toolbar (next to Copy HTML). On first use, enter your Resend API key and sender address (defaults to onboarding@resend.dev). You can optionally save credentials to .bse/resend.json in the project; otherwise they last until you stop the dev server.

From the CLI you can also pass:

bse dev --resend-api-key re_xxx --resend-from onboarding@resend.dev --resend-persist

--resend-persist writes .bse/resend.json when used with --resend-api-key.

Troubleshooting

No templates in the list

1. Confirm .svelte files exist under the directory passed to -d (default src/lib/emails).
2. Run the CLI from the repository root that contains that path (npx @better-svelte-email/cli dev, or bse dev if the CLI is installed globally).
3. Check the path is relative to the project root, not an absolute path unless intended.

Styles look wrong

Pass -c to the same CSS entry you use for Tailwind v4 / variables in the app, or ensure src/app.css / src/routes/layout.css exists so the CLI can pick it up automatically.

Port already in use

npx @better-svelte-email/cli dev -p 3005

With --preview-dev, also set --preview-port to a free port different from -p.

Legacy package reference

If you must keep @better-svelte-email/preview in a SvelteKit app, the API surface is described in the v1 Email Preview doc (createEmail, sendEmail, emailList, etc.). Prefer migrating to npx @better-svelte-email/cli dev (or a local/global bse) when you can.