voxmedia/sass-theme-template-loader

Name: sass-theme-template-loader

Owner: Vox Media

Description: Themed CSS stylesheet generator for Sass assets

Created: 2015-10-12 14:25:23.0

Updated: 2018-05-11 20:54:05.0

Pushed: 2016-01-11 18:09:58.0

Homepage:

Size: 22

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Sass theme template loader for Webpack

When creating themed websites, a common strategy is to generate pre-rendered CSS templates with theme values interpolated into them. This Webpack loader provides a system for passing raw Sass variable fields through to a rendered CSS template using the SassThematic workflow.

This loader expects that you're already using the extract-text-webpack-plugin to pull your CSS assets out into separate files. This loader will render Sass markup with embedded template fields, and then generate a template version of all extracted CSS assets.

Example

In _theme.scss: This file identifies the names of relevant theme variables.

or-theme: green;

In _vars.scss:

or-other: red;

In main.scss:

ort 'theme';
ort 'vars';

med {
lor: $color-theme;


hemed {
lor: $color-other;

Rendered main.css:

med { color: <%= @theme[:color_theme] %>; }
hemed { color: red; }

Install

Include extract-text-webpack-plugin and sass-theme-template-loader in your package:

install --save extract-text-webpack-plugin
install --save sass-theme-template-loader

Configure

The sass-theme-template loader handles primary Sass rendering. Use this loader instead of other Sass loaders.

ExtractText = require('extract-text-webpack-plugin');
SassThemeTemplate = require('sass-theme-template-loader');

config = {
try: {
'main': 'main.js',
'other': 'other.js'

tput: {
path: '/path/to/output'

dule: {
loaders: [
  { test: /\.scss$/, loader: ExtractText.extract('style', 'css!sass-theme-template') },
]

ugins: [
new ExtractText('[name].css'),
new SassThemeTemplate({
  cwd: __dirname,
  includePaths: ['./shared/'],
  varsFile: './_vars.scss',
  filename: '[name].css.erb',
  output: true, // << or a dirpath to write out templates
  templateOpen: '<%= @theme[:',
  templateClose: '] %>',
  templateSnakeCase: true,
  templateFormat: {
    'chorus': {
      header: '<%= @theme[:css_header] %>',
      footer: '<%= @theme[:css_footer] %>'
    }
  }
})

Setup:

The SassThemeTemplate plugin piggy-backs off of the ExtractText plugin. Like extract-text-webpack-plugin, this build tool also uses a loader and a plugin in tandem.

1. Install the sass-theme-template loader as the first (right-most) Sass loader. This should replace all other Sass loaders.
2. Install the SassThemeTemplate after the ExtractText plugin. Configuration options are the same as SassThematic.

How it works:

The sass-theme-template loader will render your Sass markup with theme-specific variable names stubbed out as template fields. In addition, it will validate your usage of Sass theme variables to assure these post-rendered values are not used in pre-rendered contexts. The following pre-rendered implementations are not allowed:

• Theme variables as arguments are NOT allowed: color: tint($theme-fail, 10%);
• Theme variables in operations are NOT allowed: top: $theme-fail + 5;
• Theme variables in interpolations are NOT allowed: margin: #{$theme-fail}px;

After Sass has been rendered with template fields passed through, you're welcome to pass your CSS along to any number of susequent CSS loaders (ie: autoprefixer, etc). ExtractText should be configured to pull your final CSS assets out of your JavaScript build.

Finally, the SassThemeTemplate plugin finds all extracted CSS assets, and does a final pass to fill in theme values for the extracted assets, and creates an alternate version of each asset with template interpolations.