wellington

README

Wellington

Wellington adds spriting to the lightning fast libsass. No need to learn a new tool, this all happens right in your Sass!

Speed Matters

Benchmarks

# Vanilla Sass from sass-spec
wt vanilla_css_huge.scss        0.10s user 0.01s system 98% cpu 0.120 total
compass vanilla_css_huge.scss   0.27s user 0.04s system 98% cpu 0.315 total
# 2.7x speedup

# 40,000 line of code Sass project
wt        14.935s
compass   73.800s
# 5x speedup!

What it does

Take a Sass file as follows:

$images: sprite-map("sprites/*.png");
div {
  width: image-width(sprite-file($images, "cat"));
  height: image-height(sprite-file($images, "cat"));
  background: sprite($images, "cat");
}

The following CSS file is generated

div {
  width: 140px;
  height: 79px;
  background: url("genimg/sprites-wehqi.png") 0px 0px;
}

Try before you buy

You can try out Wellington on Codepen, fork the Wellington Playground!

Check out the Wellington collection

Installation

Wellington can be installed via brew

brew install wellington
wt -h

Run Wellington in docker

docker run -v $(pwd):/data -it drewwells/wellington wt proj.scss

Documentation

Mixins

@include sprite-dimensions($map, "file")

Sprite-dimensions outputs the height and width properties of the specified image.

div {
  @include sprite-dimensions($spritemap, "file");
}

Output

div {
	width: 100px;
	height: 50px;
}

Functions

Don't see a function you want? Check out handlers and submit a pull request!

sprite-map("glob/pattern"[, $spacing: 10px])

sprite-map generates a sprite from the matched images optinally with spacing between the images. No output is generated by this function, instead the return is used in other functions.

$spritemap: sprite-map("*.png");

Output

sprite($map, $name: "image"[, $offsetX: 0px, $offsetY: 0px])|

sprite generates a background url with background position to the position of the specified "image" in the spritesheet. Optionally, offsets can be used to slightly modify the background position.

div {
	background: sprite($spritemap, "image");
}

Output

div {
	background: url("spritegen.png") -0px -149px;
}

sprite-file($map, $name: "image")

Sprite-file returns an encoded string only useful for passing to image-width or image-height.

div {
	background: sprite-file($spritemap, "image");
}

Output

div {
	background: {encodedstring};
}

image-height($path)

image-height returns the height of the image specified by $path.

div {
	height: image-height(sprite-file($spritemap, "image"));
}
div {
	height: image-height("path/to/image.png");
}

Output

div {
	height: 50px;
}
div {
	height: 50px;
}

image-width($path)

image-width returns the width of the image specified by $path.

.first {
	width: image-width(sprite-file($spritemap, "image"));
}
.second {
	width: image-width("path/to/image.png");
}

Output

.first {
	width: 50px;
}
.second {
	width: 50px;
}

inline-image($path[, $encode: false])

inline-image base64 encodes binary images (png, jpg, gif are currently supported). SVG images are by default url escaped. Optionally SVG can be base64 encoded by specifying $encode: true. Base64 encoding incurs a (10-30%) file size penalty.

.png {
	background: inline-image("path/to/image.png");
}
.svg {
	background: inline-image("path/to/image.svg", $encode: false);
}

Output

.png {
	background: inline-image("data:image/png;base64,iVBOR...");
}
.svg {
	background: inline-image("data:image/svg+xml;utf8,%3C%3F...");
}

image-url($path)

image-url returns a relative path to an image in the image directory from the built css directory.

div {
	background: image-url("path/to/image.png");
}

Output

div {
	background: url('../imgdirectory/path/to/image.png");
}

font-url($path, [$raw:false])

font-url returns a relative path to fonts in your font directory. You must set the font path to use this function. By default, font-url will return url('path/to/font'), set $raw: true to only return the path

div {
	$path: font-url("arial.eot", true);
	@font-face {
		src: font-url("arial.eot");
		src: url("#{$path}");
	}
}

Output

div {
	@font-face {
		src: url("../font/arial.eot");
		src: url("../font/arial.eot");
	}
}

Why?

Sass is a fantastic language. It adds a lot of power to standard CSS. If only our clients were happy with the functionality that Sass provided. For the life of Sass, there has been only one tool that attempted to extend Sass for everything that's needed to build a site. While Ruby is great for development, it does have some drawbacks. As our Sass powered website grew, Compass and Ruby Sass started to become a real drag on build times and development happiness. A typical build including transpiling Sass to CSS, RequireJS JavaScript, and minfication of CSS, JS, and images would spend half the time processing the Sass.

There had to be a better way. Libsass was starting to gain some traction, but it didn't do everything we needed. So I wrote Wellington to be a drop in replacement for the spriting functions familar to those used to Compass. This makes it super simple to swap out Compass with Wellington in your Sass projects.

See how the sausage is made

Building from source

Install Go and add $GOPATH/bin to your $PATH. Detailed instructions. Wellington requires Go 1.4+.

go get -u github.com/wellington/wellington
cd $GOPATH/src/github.com/wellington/wellington

make

# You should not have wt in your path
wt -h

It's a good idea to export PKG_CONFIG_PATH so that pkg-config can find libsass.pc. Otherwise, go ... commands will fail.

export PKG_CONFIG_PATH=$GOPATH/src/github.com/wellington/wellington/libsass/lib/pkgconfig

Set your fork as the origin.

cd $GOPATH/src/github.com/wellington/wellington
git remote rm origin
git remote add origin git@github.com:username/wellington.git

Testing

make test

Profiling

make profile

Build a Docker Container. The wt container is 33.6 MB in size, but builds in a much larger container 844.7 MB.

make build
make docker #launch a container

Please use pull requests for contributing code. CircleCI will automatically test and lint your contributions. Thanks for helping!

License

Wellington is licensed under MIT.

Documentation

Index

• Constants
• Variables
• func FileHandler(gen string) http.Handler
• func HTTPHandler(ctx *context.Context) func(w http.ResponseWriter, r *http.Request)
• func Init(handle io.Writer)
• func IsSass(r io.Reader) bool
• func LoadAndBuild(sassFile string, gba *BuildArgs, partialMap *SafePartialMap) error
• func ToScssReader(r io.Reader) (io.ReadCloser, error)
• type BuildArgs
  • func NewBuildArgs() *BuildArgs
• type Parser
  • func NewParser() *Parser
  • func StartParser(ctx *context.Context, in io.Reader, out io.Writer, partialMap *SafePartialMap) (*Parser, error)
  • func (p *Parser) GetItems(pwd, filename, input string) ([]lexer.Item, string, error)
  • func (p *Parser) ImportPath(dir, file string) (string, string, error)
  • func (p *Parser) LookupFile(position int) string
  • func (p *Parser) Start(r io.Reader, pkgdir string) ([]byte, error)
• type Replace
• type Response
• type SafePartialMap
  • func NewPartialMap() *SafePartialMap
  • func (p *SafePartialMap) AddRelation(mainfile string, subfile string)
• type Watcher
  • func NewWatcher() *Watcher
  • func (w *Watcher) Watch() error

Constants

const MaxTopLevel int = 20

Sets the default size of the slice holding the top level files for a sass partial in SafePartialMap.M

Variables

var (
	// Debug future ability to toggle the logging level and destination.
	Debug *log.Logger
)

Functions

func FileHandler

func FileHandler(gen string) http.Handler

FileHandler starts a file server serving files out of the specified build directory.

func HTTPHandler

func HTTPHandler(ctx *context.Context) func(w http.ResponseWriter, r *http.Request)

HTTPHandler starts a CORS enabled web server that takes as input Sass and outputs CSS.

func Init

func Init(handle io.Writer)

Init setups an application logger

func IsSass

func IsSass(r io.Reader) bool

IsSass determines if the given reader is Sass (not Scss). This is predicted by the presence of semicolons

func LoadAndBuild

func LoadAndBuild(sassFile string, gba *BuildArgs, partialMap *SafePartialMap) error

LoadAndBuild kicks off parser and compiling TODO: make this function testable

func ToScssReader

func ToScssReader(r io.Reader) (io.ReadCloser, error)

ToScssReader ...

Types

type BuildArgs

type BuildArgs struct {
	Imgs, Sprites spritewell.SafeImageMap
	Dir           string
	BuildDir      string
	Includes      string
	Font          string
	Gen           string
	Style         int
	Comments      bool
}

BuildArgs holds universal arguments for a build that the parser uses during the initial build and the filewatcher passes back to the parser on any file changes.

func NewBuildArgs

func NewBuildArgs() *BuildArgs

NewBuildArgs creates a BuildArgs and initializes Cache maps for sprites and images

type Parser

type Parser struct {
	Idx                  int
	Chop                 []Replace
	Pwd, Input, MainFile string
	SassDir, BuildDir,

	ProjDir string
	ImageDir   string
	Includes   []string
	Items      []lexer.Item
	Output     []byte
	Line       map[int]string
	LineKeys   []int
	PartialMap *SafePartialMap
	// contains filtered or unexported fields
}

Parser represents a parser engine that returns parsed and imported code from the input useful for doing text manipulation before passing to libsass.

func NewParser

func NewParser() *Parser

NewParser returns a pointer to a Parser object.

func StartParser

func StartParser(ctx *context.Context, in io.Reader, out io.Writer, partialMap *SafePartialMap) (*Parser, error)

StartParser accepts build arguments TODO: Remove pkgdir, can be referenced from context TODO: Should this be called StartParser or NewParser? TODO: Should this function create the partialMap or is this the right way to inject one?

func (*Parser) GetItems

func (p *Parser) GetItems(pwd, filename, input string) ([]lexer.Item, string, error)

GetItems recursively resolves all imports. It lexes the input adding the tokens to the Parser object. TODO: Convert this to byte slice in/out

func (*Parser) ImportPath

func (p *Parser) ImportPath(dir, file string) (string, string, error)

ImportPath accepts a directory and file path to find partials for importing. Returns the new pwd, string of the file contents, and error. File can contain a directory and should be evaluated if successfully found. Dir is used to provide relative context to the importee. If no file is found pwd is echoed back.

Paths are looked up in the following order: {includepath}/_file.scss {includePath}/_file.sass {includepath}/file.scss {includePath}/file.sass {Dir{dir+file}}/_{Base{file}}.scss {Dir{dir+file}}/_{Base{file}}.sass {Dir{dir+file}}/{Base{file}}.scss {Dir{dir+file}}/{Base{file}}.sass

func (*Parser) LookupFile

func (p *Parser) LookupFile(position int) string

LookupFile translates line positions into line number and file it belongs to

func (*Parser) Start

func (p *Parser) Start(r io.Reader, pkgdir string) ([]byte, error)

Start reads the tokens from the lexer and performs conversions and/or substitutions for sprite*() calls.

Start creates a map of all variables and sprites (created via sprite-map calls). TODO: Remove pkgdir, it can be put on Parser

type Replace

type Replace struct {
	Start, End int
	Value      []byte
}

Replace holds token values for replacing source input with parsed input. DEPRECATED

type Response

type Response struct {
	Contents string    `json:"contents"`
	Start    time.Time `json:"start"`
	Elapsed  string    `json:"elapsed"`
	Error    string    `json:"error"`
}

Response is the object returned on HTTP responses from wellington

type SafePartialMap

type SafePartialMap struct {
	sync.RWMutex
	M map[string][]string
}

SafePartialMap is a thread safe map of partial sass files to top level files. The file watcher will detect changes in a partial and kick off builds for all top level files that contain that partial.

func NewPartialMap

func NewPartialMap() *SafePartialMap

NewPartialMap creates a initialized SafeParitalMap with with capacity 100

func (*SafePartialMap) AddRelation

func (p *SafePartialMap) AddRelation(mainfile string, subfile string)

AddRelation links a partial Sass file with the top level file by adding a thread safe entry into partialMap.M.

type Watcher

type Watcher struct {
	FileWatcher *fsnotify.Watcher
	PartialMap  *SafePartialMap
	Dirs        []string
	BArgs       *BuildArgs
}

Watcher holds all data needed to kick off a build of the css when a file changes. FileWatcher is the object that triggers builds when a file changes. PartialMap contains a mapping of partials to top level files. Dirs contains all directories that have top level files. GlobalBuildArgs contains build args that apply to all sass files.

func NewWatcher

func NewWatcher() *Watcher

NewWatcher returns a new watcher pointer

func (*Watcher) Watch

func (w *Watcher) Watch() error

Watch is the main entry point into filewatcher and sets up the SW object that begins monitoring for file changes and triggering top level sass rebuilds.