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!

OS Support

Binaries are provided for Linux and OS X. Building from source will work on any os libSass supports. Windows support has been dropped due to Issue #160

Use with Grunt or Gulp

See the Grunt example See the Gulp Example

Speed Matters

Benchmarks

# 40,000 line of code Sass project with 1200 images
wt         3.679s
compass   73.800s
# 20x faster!

For more benchmarks, see realbench

What it does

wt is a Sass preprocessor tool geared towards projects written in Sass. It focuses on tasks that make working on a Sass site friendlier and much faster. wt extends the Sass language to include spriting and image operations not currently possible in the core language.

$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 output CSS

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

Available commands

$ wt -h

wt is a Sass project tool made to handle large projects. It uses the libSass compiler for efficiency and speed.

Usage:
  wt [flags]
  wt [command]

Available Commands:
  serve       Starts a http server that will convert Sass to CSS
  compile     Compile Sass stylesheets to CSS
  watch       Watch Sass files for changes and rebuild CSS

Flags:
  -b, --build="": Path to target directory to place generated CSS, relative paths inside project directory are preserved
      --comment[=true]: Turn on source comments
  -c, --config="": Temporarily disabled: Location of the config file
      --cpuprofile="": Go runtime cpu profilling for debugging
      --css-dir="": Compass backwards compat, does nothing. Reference locations relative to Sass project directory
      --debug[=false]: Show detailed debug information
  -d, --dir="": Path to locate images for spriting and image functions
      --font=".": Path to directory containing fonts
      --gen=".": Path to place generated images
      --images-dir="": Compass backwards compat, use -d instead
      --javascripts-dir="": Compass backwards compat, ignored
      --no-line-comments[=false]: UNSUPPORTED: Disable line comments
  -p, --proj="": Path to directory containing Sass stylesheets
      --relative-assets[=false]: UNSUPPORTED: Make compass asset helpers generate relative urls to assets.
      --sass-dir="": Compass backwards compat, use -p instead
  -s, --style="nested": nested style of output CSS
                        available options: nested, expanded, compact, compressed
      --time[=false]: Retrieve timing information
  -v, --version[=false]: Show the app version

Use "wt [command] --help" for more information about a command.

Try before you buy

You can try out Wellington on Codepen, fork the Wellington Playground! This live example has images you can use, or you can bring your Sass.

There are many examples on Codepen just see the Wellington collection

Installation

Wellington can be installed via brew

brew install wellington
wt -h

Building from source

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

go get -u github.com/wellington/wellington/wt

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

Or, use wellington from a docker container

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

Documentation

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

Testing

make test

Profiling

make profile

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

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!

Getting Help

Ask questions in the QA forum on Google Group

License

Wellington is licensed under MIT.

Documentation

Index

• Constants
• Variables
• func FileHandler(gen string) http.Handler
• func FromBuildArgs(dst io.Writer, dstmap string, src io.Reader, gba *BuildArgs) (libsass.Compiler, error)
• func HTTPHandler(gba *BuildArgs, httpPath string) func(w http.ResponseWriter, r *http.Request)
• func Init(handle io.Writer)
• func IsSass(r io.Reader) bool
• func LoadAndBuild(path string, gba *BuildArgs, pMap *SafePartialMap) error
• func ToScssReader(r io.Reader) (io.ReadCloser, error)
• type Build
  • func NewBuild(args *BuildArgs, pMap *SafePartialMap) *Build
  • func (b *Build) Close() error
  • func (b *Build) Run() error
• type BuildArgs
  • func (b *BuildArgs) Paths() []string
  • func (b *BuildArgs) WithPaths(paths []string)
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) Start(r io.Reader, pkgdir string) ([]byte, error)
• type Replace
• type Response
• type SafePartialMap
  • func NewPartialMap() *SafePartialMap
  • func (p *SafePartialMap) Add(key string, paths []string)
  • func (p *SafePartialMap) AddRelation(mainfile string, subfile string)
  • func (p *SafePartialMap) Get(key string) ([]string, bool)
• type WatchOptions
  • func NewWatchOptions() *WatchOptions
• type Watcher
  • func NewWatcher(opts *WatchOptions) (*Watcher, error)
  • func (w *Watcher) Close() error
  • func (w *Watcher) Init()
  • func (w *Watcher) Watch() error

Examples

• NewBuild

Constants

const MaxTopLevel int = 20

MaxTopLevel 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
)

var ErrPartialMap = errors.New("No partial map found")

ErrPartialMap when no partial map is found

Functions

func FileHandler

func FileHandler(gen string) http.Handler

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

func FromBuildArgs

func FromBuildArgs(dst io.Writer, dstmap string, src io.Reader, gba *BuildArgs) (libsass.Compiler, error)

FromBuildArgs creates a compiler from BuildArgs

func HTTPHandler

func HTTPHandler(gba *BuildArgs, httpPath string) 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(path string, gba *BuildArgs, pMap *SafePartialMap) error

LoadAndBuild kicks off parser and compiling. It expands directories to recursively locate Sass files TODO: make this function testable

func ToScssReader

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

ToScssReader ...

Types

type Build

type Build struct {
	// contains filtered or unexported fields
}

Build holds a set of read only arguments to the builder. Channels from this are used to communicate between the workers and loaders executing builds.

func NewBuild

func NewBuild(args *BuildArgs, pMap *SafePartialMap) *Build

NewBuild accepts arguments to reate a new Builder

Example

ps := []string{"test/sass/file.scss"}
args := &BuildArgs{}
args.WithPaths(ps)
b := NewBuild(args, NewPartialMap())

err := b.Run()
if err != nil {
	log.Fatal(err)
}

Output:

div {
  color: black; }

func (*Build) Close

func (b *Build) Close() error

Close shuts down the builder ensuring all go routines have properly closed before returning.

func (*Build) Run

func (b *Build) Run() error

Run compiles all valid Sass files found in the passed paths. It will block until all files are compiled.

type BuildArgs

type BuildArgs struct {
	Payload  context.Context
	ImageDir string

	// BuildDir is the base build directory used. When recursive
	// file matching is involved, this directory will be used as the
	// parent.
	BuildDir string
	Includes []string
	// Project is the source for Sass files and is searched
	// recursively for those files
	Project   string
	Font      string
	Gen       string
	Style     int
	Comments  bool
	CacheBust string
	// emit source map files alongside css files
	SourceMap bool
	// indicates the working directory which wt is run in
	WorkDir string
	// contains filtered or unexported fields
}

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 (*BuildArgs) Paths

func (b *BuildArgs) Paths() []string

Paths retrieves the paths in the arguments

func (*BuildArgs) WithPaths

func (b *BuildArgs) WithPaths(paths []string)

WithPaths creates a new BuildArgs with paths applied

type Parser

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

	ProjDir string
	Imports    libsass.Imports
	ImageDir   string
	Includes   []string
	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 (*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"`
	Version  string    `json:"version"`
}

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) Add

func (p *SafePartialMap) Add(key string, paths []string)

Add places a path in the partial map

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.

func (*SafePartialMap) Get

func (p *SafePartialMap) Get(key string) ([]string, bool)

Get is a thread-safe way to access the partial map

type WatchOptions

type WatchOptions struct {
	PartialMap *SafePartialMap
	Paths      []string
	BArgs      *BuildArgs
}

WatchOptions containers the necessary parameters to run the file watcher

func NewWatchOptions

func NewWatchOptions() *WatchOptions

NewWatchOptions returns a new WatchOptions

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

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(opts *WatchOptions) (*Watcher, error)

NewWatcher returns a new watcher pointer

func (*Watcher) Close

func (w *Watcher) Close() error

Close shuts down the fsevent stream

func (*Watcher) Init

func (w *Watcher) Init()

Init initializes the watcher with fsnotify watcher

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.