Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Yeoman Static scaffold

    Yeoman Generator for a basic front-end project workflow.

    If you like the combination of Jade + LESS + CoffeeScript, you might like this!


    1. Install Node.js

    Skip this section if you have a node evironment setup.

    OS X


    This guides assumes you have installed the following tools successfully:

    • Xcode
    • Xcode developer tools
    • git
    • Homebrew

    Use nave (or similar) to manage your Node.js installations. You should always try to use the latest stable version of Node.js.

    In a terminal, run:

    brew install node
    npm install -g nave
    nave use stable

    2. Install development tools

    npm install -g bower grunt-cli yo generator-static http-server
    • bower installs and manages many client-side dependencies (e.g. jQuery)
    • grunt-cli used to execute grunt tasks defined in the project
    • yo and generator-static will install yeoman and this generator
    • http-server is used for serving the site in development

    3. Create a project

    Now, to create a new static site project, run the following command:

    mkdir my_project && cd my_project
    yo static:app

    Replace my_project with your own project name.

    yeoman will handle installing the various dependencies initially (using npm and bower).

    4. Write code!

    • all stylesheets (css/less/scss) go in <PROJECT_ROOT>/app/assets/styles/
    • all scripts (js and coffee) go in <PROJECT_ROOT>/app/assets/scripts/
    • all html (or jade) go in <PROJECT_ROOT>/app/views/

    5. Build/Debug

    Grunt is used as the task runner. To build the your code run:


    If you are in a staging or production evironment you should set NODE_ENV so the code is optimised. For example:

    NODE_ENV=production grunt


    NODE_ENV=staging grunt

    During development

    A good way to debug the code as you develop the site is as follows:

    • open one terminal window and use nave to select your Node.js installation
    • navigate into your project's root directory and run grunt default watch
    • open a second terminal window and (again) use nave to select your Node.js installation
    • navigate into <PROJECT_ROOT>/dist/app/ and run http-server -c-1
    • you should now have a live development server running at http://localhost:8080/views which serves up the site

    More info

    Project Structure

    	.... assets/
    	.... .... images/
    	.... .... styles/
    	.... .... scripts/
    	.... views/ <- contains jade templates for site pages
    	.bowerrc <- bower cli configuration
    	.editorconfig <- editor configuration rules (indent style, line endings)
    	.gitignore <- contains sensible defaults for files/folders to ignore
    	bower.json  <- bower package definition packages
    	defaults.json <- default configuration for grunt tasks  <- grunt tasks definition module
    	package.json  <- npm package definition

    Project settings

    The project's default settings are found in defaults.json. If you wish to override any values, create a file called locals.json and define the new values for the desired keys.

    If you want to add new settings to use in your project, ensure you have defined default values for them in defaults.json and you can then override them in locals.json if necessary.

    Jade templates have access to settings using the settings context variable.

    A note about Jade templates

    This project relies on Jade templates to compose the site's pages. Templates are placed in the <PROJECT_ROOT>/app/views/ folder.

    Any template whose name begins with _ (underscore) is considered a 'partial' and is not compiled into the output directory (<PROJECT_ROOT>/dist/views/ by default). These can be included and extended by other templates and partial.

    A note about IE

    Project generated by this generator incorporate respond.js to enable media queries for IE < 9.

    Use cases

    Adding a client-side dependency

    Let us assume you want to use lodash on your site.

    1. In the project's root directory where bower.json is located, run bower install --save lodash

    2. Open and look for the comment starting with # CHECKPOINT: [js]

    3. Add lodash.js* to the list of modules to include in JS application bundle. You should now have something similar to the following lines:

         '<%= paths.dist + paths.scripts %>bundle.js': [
           '<%= paths.components %>jquery/jquery.js'
           # CHECKPOINT: [js] list the modules you want to include into the
           # js application bundle here. This includes third party modules,
           # compiled coffee files and any other js modules you manually
           # included in the project tree
           # NOTE: ordering matters
           '<%= paths.components %>lodash/lodash.js'
           '<%= paths.temp + paths.scripts %>my-module.js'
    4. (Optional) If you are running grunt watch in terminal, kill it

    5. Run grunt (or grunt default watch if you want to watch for changes)

    *Note: Use unminified version of modules whenever possible

    Working with styles

    In, you will find that the less task only compiles <PROJECT_ROOT>/app/assets/styles/style.less. This means that you should style.less to define the style for the entire site. A typical style.less may contain something similar to the following:

    @import 'bootstrap/less/variables';
    @import 'variables';
    @import 'bootstrap/less/mixins';
    @import 'bootstrap/less/reset';
    @import 'bootstrap/less/scaffolding';
    @import 'bootstrap/less/grid';
    @import 'bootstrap/less/layouts';
    @import 'bootstrap/less/type';
    @import 'bootstrap/less/tables';
    @import 'bootstrap/less/sprites';
    @import 'bootstrap/less/buttons';
    @import 'bootstrap/less/component-animations';
    @import 'bootstrap/less/responsive-utilities';
    @import 'bootstrap/less/utilities';
    @import 'icons';
    @import 'buttons';
    @import 'type';
    @import 'structure';
    @import 'theme';

    Referencing assets

    There are two places where you might want to reference assets (css/js/img): in Jade templates or LESS/CSS stylesheets.

    Jade templates

    When writing templates you have access to a function called asset(path, environmentSuffix). So, for example, to include javascript asset in a template (let's call it _base.jade for this example), you would write the following:

    // somewhere in _base.jade
    // ...
    block scripts
      script(type='text/javascript', src=asset('scripts/bundle.js', '.min'))
    // ...

    The second argument in the asset functions indicates that this asset is environment-sensitive. That is: if we are running grunt in development (e.g. NODE_ENV=development), then use the unminified version otherwise use minified version. So for example given the lines above:

    With NODE_ENV=development, they would compile to:

    <script type="text/javascript" src="/assets/scripts/bundle.js?rel=5826269c"></script>

    With NODE_ENV=production, they would compile to:

    <script type="text/javascript" src="/assets/scripts/bundle.min.js?rel=af26cd84"></script>
    LESS/CSS stylesheets

    In stylesheets, you simply reference assets using $ASSET(<asset_path>). For example:

    .mast {
      background: url($ASSET(images/texture.png)) repeat;

    There is a grunt task called replace that will look through the compiled LESS/CSS and replace any instances of the $ASSET() string with the resolved path of asset

    1. The asset helper being used here uses the cache busting technique of appending the first 8 digits of the md5 checksum for a given asset as a request parameter. This can be turned off by setting "ASSET_CACHE_BUSTING": false in your local settings file (locals.json).
    2. Asset paths passed to the asset helper for both Jade templates and stylesheets are relative to the ASSET_ROOT which is app/assets/ by default (see defaults.json).




    npm i generator-static

    Downloadsweekly downloads







    last publish


    • avatar