Nuns Practicing Misanthropy
Wondering what’s next for npm?Check out our public roadmap! »


0.2.8 • Public • Published


Teacup is templates in CoffeeScript.

Compose DSL functions to build strings of HTML.
Package templates and helpers in CommonJS, AMD modules, or vanilla coffeescript.
Integrate with the tools you love: Express, Backbone, Rails, and more.

Build Status

The Basics

Use the renderable helper to create a function that returns an HTML string when called.

{renderableulli} = require 'teacup'
template = renderable (items)->
  ul ->
    li item for item in items
console.log template(['One''Two'])
# Outputs <ul><li>One</li><li>Two</li></ul> 

Use the render helper to render a template to a string immediately.

{renderulli} = require 'teacup'
output = render ->
  ul ->
    li 'First Item'
    li 'Second Item'
console.log output
# Outputs <ul><li>First Item</li><li>Second Item</li></ul> 


To use Teacup as your Express template engine:

Install from npm

$ npm install teacup

Register Teacup as a view engine.

express = require 'express'
teacup = require 'teacup/lib/express'
app = express()
app.configure ->
  app.engine "coffee"teacup.renderFile

Then write your views as regular old coffee files that export a renderable template.

# views/ 
{renderabledivh1} = require 'teacup'
module.exports = renderable ({title}) ->
  div '#example'->
    h1 "Hello, #{title}"

You can use Teacup templates even if your Express app is not using CoffeeScript.


If you are using connect-assets to compile your CoffeeScript in an asset pipeline, you can use the Teacup middleware which registers connect-assets js and css helpers with Teacup.

Grab the module to get started

$ npm install teacup

Then configure the middleware

express = require 'express'
connectAssets = require 'teacup/lib/connect-assets'
app = express()
app.configure ->
  app.use connectAssets(src: 'assets'jsDir: 'javascripts'cssDir: 'stylesheets')

And in your templates:

{renderablejscsshtmlheadbody} = require 'teacup'
module.exports = renderable ->
  html ->
    head ->
      js 'app'
      css 'app'
    body ->
      # ... 

The Teacup middleware passes the provided options to connect-assets and returns an instance of the connect-assets middleware.


To use for client-side rendering, all you need is teacup.js. You can toss it in a script tag, require() and browserify it, load it with an AMD loader, send it down an asset pipeline like Rails or connect-assets, or use some sweet custom build process.

Teacup claims window.teacup if you arent using AMD or CommonJS.

{renderableulli} = teacup
template = renderable (items)->
  ul ->
    li item for item in items
console.log template(['One''Two'])


Feel free to write your template in the same file as a Backbone View and call it from view.render() like so:

{renderabledivh1ullipforminput} = teacup
template = renderable (kids) ->
  div ->
    h1 "Welcome to our tea party"
    p "We have a few kids at the table..."
    ul ->
      kids.each (kid) ->
        li kid.get 'name'
    form ->
      input placeholder: 'Add another'
class PartyView extends Backbone.View
  constructor: (kids) ->
    @kids = new Backbone.Collection kids
  render: ->
    @$el.html template(@kids)
    @$('form input').focus()

Check out teacup-backbone-example for a complete Backbone + Express app.


The Teacup::Rails gem makes Teacup available to the asset pipeline in Rails 3.1+.



Teacup escapes input by default. To disable escaping, use the raw helper.

{renderrawh1div} = require 'teacup'
inner = render ->
  h1 'Header'
console.log render ->
  div inner
# Outputs <div>&lt;h1&gt;Header&lt;/h1&gt;</div> 
console.log render ->
  div ->
    raw inner
# Outputs <div><h1>Header</h1></div> 


The text helper inserts a string in the template without wrapping it in a tag. It creates a text node.

{rendertextbemp} = require 'teacup'
console.log render ->
  p ->
    text 'Sometimes you just want '
    b 'plain'
    text ' text.'
# Outputs <p>Sometimes you just want <b>plain</b> text.</p> 


Write view helpers as renderable functions and require them as needed.

Here's a helpers file that defines a set of microformats.

# views/ 
{renderablespantext} = require 'teacup'
moment = require 'moment'
module.exports =
  hcalendar: renderable ({date, location, summary}) ->
    span ".vevent"->
      span ".summary"summary
      text " on "
      span ".dtstart"moment(date).format("YYYY-MM-DD")
      text " was in "
      span ".location"location

And a view that uses one of the helpers.

# views/ 
{renderableulli} = require 'teacup'
{hcalendar} = require './microformats'
module.exports = renderable ({events}) ->
  ul ->
    for event in events
      li ->
        hcalendar event

Compiling Templates

Just use the CoffeeScript compiler. Uglify will make em real small.

$ coffee -cl -o build src


How's this different from CoffeeCup?

CoffeeCup is the currently maintained fork of CoffeeKup and is what we were using at Good Eggs before switching to Teacup. The problem with CoffeeCup is that it uses some eval magic to put the tag functions in scope. This magic breaks closure scope so you can't actually write templates using the functional constructs that you'd expect.


Markaby begat CoffeeKup begat CoffeeCup and DryKup which begat Teacup.


$ git clone && cd teacup
$ npm install
$ npm test


npm i [email protected]





Last publish


  • avatar
  • avatar
  • avatar
  • avatar
  • avatar