Appearance

CLI ​

The Command Line Interface and developer tooling for Email Craft

Install ​

Install the package from your command line

console
pnpm install email-craft
pnpm install email-craft
console
bun install email-craft
bun install email-craft
console
npm install email-craft
npm install email-craft
console
yarn install email-craft
yarn install email-craft

Nearly all installations of this package will want it installed into devDependencies so please make sure to add the -D flag.

Usage ​

Installing this package will add an email binary, which will be available to pnpm exec, npx, and yarn.

Invoking the CLI without parameters or flags will produce help information in the console. From there, all of the functions of the CLI can be viewed, along with any applicable parameters and flags:

console
→ pnpm exec email

email-craft v0.0.0

A CLI for working with Email Templates made with email-craft

Usage
  $ email [...options]

Commands
  build       <template file or dir path>
  check       <template file path>
  create      <template name>
  help        [<command>]
  preview     <template dir path>

Options
  --help      Displays this message
  --version   Displays the current email-craft version

Examples
  $ email
  $ email --help
  $ email build ./src/templates/Invite.tsx
  $ email create invite
  $ email preview ./src/templates
→ pnpm exec email

email-craft v0.0.0

A CLI for working with Email Templates made with email-craft

Usage
  $ email [...options]

Commands
  build       <template file or dir path>
  check       <template file path>
  create      <template name>
  help        [<command>]
  preview     <template dir path>

Options
  --help      Displays this message
  --version   Displays the current email-craft version

Examples
  $ email
  $ email --help
  $ email build ./src/templates/Invite.tsx
  $ email create invite
  $ email preview ./src/templates

To view help for specific commands, use email help <command>. e.g. email help build.

Build ​

The build command compiles and renders an email template to HTML for use with an email provider. The command takes a directory or single file as input:

console
$ cd ~/code/email-app
$ email build ./emails
$ cd ~/code/email-app
$ email build ./emails

Or for a single file:

console
$ cd ~/code/email-app
$ email build ./emails/Batman.tsx
$ cd ~/code/email-app
$ email build ./emails/Batman.tsx

Check ​

email-craft can run a client compatibility check on any template, comparing it to the compatibility tables from `caniuse.com and display any email client incompatibility issues. This check is incredibly helpful in diagnosing and debugging display issues between multiple email clients.

console
$ email check ./emails/Batman.tsx
$ email check ./emails/Batman.tsx

Example output:

console
Checking email template for Client Compatibility...

Found 1 files:
   ./emails/Batman.tsx

Starting build...

Build complete

./emails/Batman.tsx

  error  Class selector is not supported by:
           gmail.mobile-webmail
           protonmail.desktop-webmail
           protonmail.ios

  error  border-radius is not supported by:
           outlook.windows
           outlook.windows-mail

  ...

  warn  target attribute is only partially supported by:
          apple-mail.macos
          apple-mail.ios
          outlook.windows
          outlook.windows-mail
          outlook.ios
          outlook.android

Check Complete: 14 error(s), 20 warning(s)
Checking email template for Client Compatibility...

Found 1 files:
   ./emails/Batman.tsx

Starting build...

Build complete

./emails/Batman.tsx

  error  Class selector is not supported by:
           gmail.mobile-webmail
           protonmail.desktop-webmail
           protonmail.ios

  error  border-radius is not supported by:
           outlook.windows
           outlook.windows-mail

  ...

  warn  target attribute is only partially supported by:
          apple-mail.macos
          apple-mail.ios
          outlook.windows
          outlook.windows-mail
          outlook.ios
          outlook.android

Check Complete: 14 error(s), 20 warning(s)

Preview ​

Email Craft ships with a Preview Tool as part of the CLI. Our Preview is fast, simple, and smooth. It doesn't require installing any crazy dependencies, downloading additional "clients," or copying your project's dependencies. It just works. And the best part: it works with monorepos out of the box.

To use the Preview Tool, open your terminal and navigate to your project. We're assuming you've already installed the CLI as shown above, and that you've already run email create to create an email in an emails directory.

console
$ cd ~/code/email-app
$ email preview ./emails
$ cd ~/code/email-app
$ email preview ./emails

The Preview Tool will start up and open a new window in your browser, and you'll be presented with a page that looks like:

Preview 1

Preview 1

Preview 1

Preview 1

Deploying Your Preview App ​

As part of the CLI, users have the ability to build their templates into a deployable preview app. The resulting app can be deployed anywhere, not just select service providers. To build templates into a deployable app, run:

console
$ email preview <templates-path> --build-path <build-path>
$ email preview <templates-path> --build-path <build-path>

where <build-path> is the path you want the build output files placed.