https://github.com/forwardemail/nodemailer-base64-to-s3
:zap: Convert your Base64-Encoded Data URI's in `<img>` tags to Amazon S3/CloudFront URL's. A better alternative than embedding images with CID using Nodemailer.
https://github.com/forwardemail/nodemailer-base64-to-s3
amazon automatic aws base64 cdn cloudfront data-uri email encoded engine javascript node nodejs nodemailer plugin s3 template upload
Last synced: 5 months ago
JSON representation
:zap: Convert your Base64-Encoded Data URI's in `<img>` tags to Amazon S3/CloudFront URL's. A better alternative than embedding images with CID using Nodemailer.
- Host: GitHub
- URL: https://github.com/forwardemail/nodemailer-base64-to-s3
- Owner: forwardemail
- License: mit
- Created: 2016-10-09T19:14:24.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-09-28T20:52:27.000Z (about 2 years ago)
- Last Synced: 2025-04-20T16:12:28.595Z (6 months ago)
- Topics: amazon, automatic, aws, base64, cdn, cloudfront, data-uri, email, encoded, engine, javascript, node, nodejs, nodemailer, plugin, s3, template, upload
- Language: JavaScript
- Homepage: https://lad.js.org
- Size: 840 KB
- Stars: 29
- Watchers: 2
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nodemailer-base64-to-s3
[](https://github.com/forwardemail/nodemailer-base64-to-s3/actions/workflows/ci.yml)
[](https://github.com/sindresorhus/xo)
[](https://github.com/prettier/prettier)
[](https://lass.js.org)
[]()
> Convert your base64 encoded data URI's in `![]()
` tags to Amazon S3/CloudFront URL's
> It's the perfect alternative to cid-based [embedded images][nodemailer-doc]!
## Table of Contents
* [Features](#features)
* [Install](#install)
* [Usage](#usage)
* [Options](#options)
* [Gmail Example](#gmail-example)
* [Contributors](#contributors)
* [License](#license)
## Features
> **Tip:** This package is bundled with [Lad][] and already pre-configured for you.
* Converts `![]()
` tags with base64 encoded data URI's to absolute paths stored on [S3][] (or optionally [CloudFront][]).
* Supports all standard data URI image types (PNG, JPEG, GIF, SVG)
* Converts SVG images to PNG images using [Sharp][sharp] (since SVG doesn't render in all email clients)
* Checks Amazon S3 bucket before uploading images to prevent a redundant double-upload of the same file (better performance)
* Uses [rev-hash][] to prevent asset naming collisions in your S3 bucket (and to avoid Gmail image cache issues).
* Encodes your images using gzip so your downloads are [compressed and faster][s3-article] (uses `zlib.gzip`) via [zlib][].
* Perfect alternative to [cid][cid-url] embedded images.
* Built for [Lad][] and [font-awesome-assets][].
## Install
[npm][]:
```sh
npm install nodemailer-base64-to-s3
```
## Usage
```js
const base64ToS3 = require('nodemailer-base64-to-s3');
const nodemailer = require('nodemailer');
const transport = nodemailer.createTransport({
// pass some options here to create a transport
// this example simply shows a JSONTransport type
//
jsonTransport: true
});
transport.use('compile', base64ToS3(options));
```
## Options
Accepts the following arguments and returns a [Nodemailer plugin][nodemailer-plugin].
* `options` (Object) - configuration options for `base64ToS3`
* `maxAge` (Number) - `Cache-Control` headers `max-age` value in milliseconds (defaults to 1 year = `31557600000`)
* `dir` (String) - Amazon S3 directory inside of `aws.params.Bucket` to upload assets to (defaults to `/` (root) - must end with a trailing forward slash `/`) – if you want to upload to a particular folder in a bucket, then set it here
* `cloudFrontDomainName` (String) - Amazon CloudFront domain name (e.g. `gzpnk2i1spnlm.cloudfront.net`) (will use `process.env.AWS_CLOUDFRONT_DOMAIN` environment variable by default if available)
* `aws` (Object) **Required** - configuration options for Amazon Web Services
* `params` (Object) **Required**
* `Bucket` (String) **Required** - AWS Bucket Name
* `fallbackDir` (String) - a fallback directory to write to in case Amazon S3 upload fails (automatically set to `os.tmpdir()` otherwise if `NODE_ENV` is production then it is set to false and disabled) - you may want to specify the full path to your build directory so files are stored there (e.g. `fallbackDir: path.join(__dirname, 'build', 'img', 'nodemailer')`)
* `fallbackPrefix` (String or Boolean) - the prefix to use for relative paths, e.g. you don't want to have `file:///some/tmp/dir/foo.png`, but you want to have `https://example.com/img/foo.png` instead - so specify that prefix here (e.g. `fallbackPrefix: 'http://localhost:3000/img/nodemailer/'` if you have a build directory `fallbackDir` of `path.join(__dirname, 'build', 'img', 'nodemailer')` and `path.join(__dirname, 'build')` is being served by your web server). The default value is `false` and therefore `file:///` relative path will be used instead.
* `logger` (Object) - a logger to use in the event of an error while uploading to S3 (defaults to `console`)
## Gmail Example
**This is a screenshot taken directly from Gmail on a Retina-supported device.**
Above we have a [Lad][] sample email sent using [Nodemailer][nodemailer] and [Nunjucks][nunjucks].
> What does it look like behind the scenes?
Here's a snippet from the navbar shown in the screenshot above. We utilize [font-awesome-assets][font-awesome-assets] for rendering the icons/images and code block.
```nunjucks
```
## Contributors
| Name | Website |
| -------------- | -------------------------- |
| **Nick Baugh** | |
## License
[MIT](LICENSE) © [Nick Baugh](http://niftylettuce.com/)
##
[npm]: https://www.npmjs.com/
[font-awesome-assets]: https://github.com/crocodilejs/font-awesome-assets
[cid-url]: https://sendgrid.com/blog/embedding-images-emails-facts/
[s3-article]: http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/ServingCompressedFiles.html
[nodemailer-doc]: https://nodemailer.com/using-embedded-images/
[nodemailer-plugin]: https://github.com/nodemailer/nodemailer#plugin-api
[s3]: https://aws.amazon.com/s3/#pricing
[cloudfront]: https://aws.amazon.com/cloudfront/pricing/
[rev-hash]: https://github.com/sindresorhus/rev-hash
[zlib]: https://nodejs.org/api/zlib.html
[nodemailer]: https://nodemailer.com
[nunjucks]: https://github.com/mozilla/nunjucks
[lad]: https://lad.js.org
[sharp]: https://github.com/lovell/sharp