Foundation for Emails

2.5.1 · active · verified Sun Apr 19

Foundation for Emails, currently at stable version 2.5.1, is a robust open-source framework designed for building responsive HTML emails that render consistently across various email clients, including challenging ones like Outlook. Originally known as Ink, it transitioned to a Sass-based codebase with its 2.0.0 release, incorporating the Inky templating language, which simplifies email layout by converting custom HTML tags into complex, client-compatible table structures. While releases were infrequent for several years, recent activity (v2.3.0, v2.4.0, v2.5.0, v2.5.1 between 2022-2024) indicates a more active maintenance phase. Its key differentiators include comprehensive testing across email clients, the Inky templating system, and support for both Node.js-based build workflows (via a template stack) and integration into Ruby on Rails projects via a dedicated gem.

Common errors

```
Error: Node Sass version X is incompatible with ^4.0.0.
```
cause Using an outdated or incompatible version of `node-sass` or `gulp-sass` after Foundation for Emails migrated to Dart Sass in v2.4.0.

fix Update `gulp-sass` to a version compatible with Dart Sass (e.g., `gulp-sass@5.0.0` or newer), and ensure `sass` (Dart Sass) is installed as a dependency instead of `node-sass`. You may need to remove `node-sass` from `package.json` and reinstall dependencies.
```
npm ERR! code ELIFECYCLE npm ERR! errno 1 npm ERR! foundation-emails-template@x.x.x start: `gulp --tasks-simple`
```
cause Common build failure in the `foundation-emails-template` due to Node.js version incompatibility or issues with `gulp` setup, particularly after long periods without updates.

fix Verify you are using a compatible Node.js version (historically Node.js v10.x was recommended for the template). Update global `foundation-cli` and `gulp` (`npm install -g foundation-cli gulp`). If problems persist, try deleting `node_modules`, `package-lock.json`, and reinstalling `npm install`.
```
ReferenceError: "import" and "export" may only appear at the top level
```
cause Attempting to use ES Modules syntax (`import`/`export`) in a CommonJS (`require()`) environment, often when a build tool or Node.js version isn't configured for ESM, or when trying to directly import Foundation's internal JS files.

fix Foundation for Emails' JavaScript components are typically bundled for client-side inclusion, not designed for direct Node.js ESM/CJS module import. Ensure your build pipeline correctly handles module compilation if you're attempting to customize Foundation's JS. If you're importing external modules, ensure your project supports ESM (e.g., by setting `"type": "module"` in `package.json` or using a transpiler like Babel).

Warnings

breaking Foundation for Emails v2.0.0 was a complete rewrite, transitioning from the original 'Ink' framework to a Sass-based codebase with the new Inky templating language. Existing Ink projects require significant migration.
Fix: Refer to the official Migration Guide for upgrading from Ink 1.0 to Foundation for Emails 2.0.
breaking Version 2.4.0 migrated the primary style parser to Dart Sass from Node Sass. This change can break existing build pipelines that relied on Node Sass, especially for users with specific `gulp-sass` or `node-sass` versions.
Fix: Ensure your Gulp build system uses `gulp-sass` v5 or newer with Dart Sass. Update `node-sass` related dependencies in your `package.json` to be compatible or remove them if migrating fully to Dart Sass. Check `gulpfile.babel.js` in the `foundation-emails-template` for updated configurations.
gotcha The official email template stack for Foundation for Emails (the recommended way to get started) historically required Node.js no greater than version 10 for stable operation. Using newer Node.js versions might lead to `npm install` or build failures.
Fix: Use Node Version Manager (nvm) to install and switch to Node.js v10.x. For example: `nvm install 10 && nvm use 10`. More recent versions (2.5.0+) may have improved Node compatibility, but testing with v10 is safest if issues arise.
deprecated Foundation for Emails is slated to be merged into the Inky project, with Inky becoming a complete email framework combining templating and styling. The `foundation-emails` repository will continue to receive maintenance but new feature development will occur in Inky v2.
Fix: While `foundation-emails` remains functional, consider monitoring the `Inky` project for future directions and new feature development. Existing projects will likely continue to receive maintenance updates.
gotcha JavaScript is generally not supported in most popular email clients for security reasons, and will be blocked. Foundation for Emails includes some minor JavaScript for responsive elements like collapsing navigation, but it's not a general-purpose JS framework for interactive email features.
Fix: Avoid relying on JavaScript for critical functionality or interactive elements within your email designs. Focus on CSS and HTML for responsive layouts. Any included JS is for enhancements where supported, not core functionality.

Install

npm install foundation-emails npm
yarn add foundation-emails yarn
pnpm add foundation-emails pnpm

Quickstart

Sets up a new Foundation for Emails project using the official template, demonstrating the core `npm install`, `npm start`, and `npm run build` commands for local development and production compilation.

git clone https://github.com/foundation/foundation-emails-template my-responsive-email
cd my-responsive-email

# The README suggests Node.js <= 10, but recent updates may support newer. 
# If using nvm, uncomment and adjust:
# nvm install 10
# nvm use 10

# Install project dependencies (Gulp, Inky, Sass, etc.)
npm install

# Start the development server with live-reloading
# This will compile your Inky HTML, Sass, and inline CSS
npm start

# To build for production, which inlines all CSS
npm run build

# After `npm start`, edit `src/pages/index.html` (Inky HTML) and `src/assets/scss/app.scss` (Sass)
# Example Inky (in src/pages/index.html or a partial):
/*
<container>
  <row>
    <columns small="12" large="6">
      <h1>Hello, Responsive Email!</h1>
      <p>This is a Foundation for Emails template.</p>
      <button href="#">Click Me</button>
    </columns>
    <columns small="12" large="6">
      <img src="https://placehold.co/300x200" alt="Placeholder Image">
    </columns>
  </row>
</container>
*/

view raw JSON →