Configuring jsx-email ​

When running email from the command line or programmatically using the render function, jsx-email will attempt to find and use a jsx-email.config file. jsx-email will traverse a directory structure looking for config files until it reaches a git repository root directory, or the OS's home directory. This is quite fast, and allows for scoping your configuration file at the filesystem level you'd like to. By default, jsx-email looks for configuration files with the following file extensions and locations:

.config/jsx-emailrc.js
.config/jsx-emailrc.cjs
.config/jsx-emailrc.mjs
.config/jsx-email.config.js
.config/jsx-email.config.cjs
.config/jsx-email.config.mjs
.jsx-emailrc.js
.jsx-emailrc.cjs
.jsx-emailrc.mjs
jsx-email.config.js
jsx-email.config.cjs
jsx-email.config.mjs

.config/jsx-emailrc.js
.config/jsx-emailrc.cjs
.config/jsx-emailrc.mjs
.config/jsx-email.config.js
.config/jsx-email.config.cjs
.config/jsx-email.config.mjs
.jsx-emailrc.js
.jsx-emailrc.cjs
.jsx-emailrc.mjs
jsx-email.config.js
jsx-email.config.cjs
jsx-email.config.mjs

Config File ​

The most basic configuration file might look like this:

import { defineConfig } from 'jsx-email/config';

export const config = defineConfig({
  render: { minify: true }
});

import { defineConfig } from 'jsx-email/config';

export const config = defineConfig({
  render: { minify: true }
});

The named export config is required regardless of how the file is constructed. Note the use of the defineConfig import and the config named export - while any plain object will be accepted and parsed, the use of defineConfig is encouraged for ensuring your config is compliant.

Intellisense ​

Since jsx-email ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints:

/** @type {import('jsx-email/config').JsxEmailConfig} */
export const config = { ... };

/** @type {import('jsx-email/config').JsxEmailConfig} */
export const config = { ... };

Async Configuration ​

The config export inherently supports Promise. This is helpful when needing to perform other async operations before returning a value to the export. This can be done in a few ways:

export const config = (async () => { ... })();

export const config = (async () => { ... })();

Or

export const config = new Promise((resolve, reject) => { ... })

export const config = new Promise((resolve, reject) => { ... })

Alternatively, when using the defineConfig function, an async function may be passed to it as the first argument:

export const config = defineConfig(async () => {
  const data = await asyncFunction()
  return {
    ...
  }
});

export const config = defineConfig(async () => {
  const data = await asyncFunction()
  return {
    ...
  }
});

Available Properties ​

jsx-email configuration files support the following properties:

esbuild?: {
  plugins?: Plugin[]
}

esbuild?: {
  plugins?: Plugin[]
}

Optional. Default: undefined. Allows the configuration file to specify ESBuild Plugins to use during the initial transform from JSX/TSX to JavaScript for the build and preview commands.

::: note ESBuild plugins are only run when using the CLI's build or preview commands. ESBuild, and by extension the esbuild configuration option, are not used when using render directly in code :::

logLevel?: 'debug' | 'info' | 'warn' | 'error';

logLevel?: 'debug' | 'info' | 'warn' | 'error';

Optional. Default: info. The level at which logs for jsx-email will appear in the terminal / console.

plugins?: JsxEmailPlugin[];

plugins?: JsxEmailPlugin[];

Optional. An array of plugins; objects which contain a valid JsxEmailPlugin definition.

render?: RenderOptions;

render?: RenderOptions;

Optional. The value specified will be merged with the render function options when a render takes place. Please see the render documentation for more details.