rparree/assemble-core

The core assemble application with no presets or defaults. All configuration is left to the implementor.

assemble-core

The core assemble application with no presets or defaults. All configuration is left to the implementor.

This library, assemble-core, was designed to give implementors and hackers the baseline features and API for creating rich and powerful node.js applications. Learn more about what you can do with assemble-core.

• Install
• Usage
• Examples
• API
  • Templates API
  • File System API
    • .src
    • .dest
    • .copy
    • .symlink
  • Task API
    • .task
    • .build
    • .watch
• About
• Related projects
• Tests
  • Running tests
  • Test coverage
• Contributing
• History
• Author
• License

(TOC generated by verb)

Install

Install with npm

$ npm i assemble-core --save

Usage

var assemble = require('assemble-core');
var app = assemble();

Examples

view collections

Create a custom view collection:

var app = assemble();
app.create('pages');

Now you can add pages with app.page() or app.pages():

app.page('home.hbs', {content: 'this is the home page!'});

render

Render a view:

var app = assemble();
app.create('pages');

app.page('foo', {content: 'Hi, my name is <%= name %>'})
  .use(function (view) {
    if (!view.contents) {
      view.contents = fs.readFileSync(view.path);
    }
  })
  .set('data.name', 'Brian')
  .render(function (err, res) {
    console.log(res.content);
    //=> 'Hi, my name is Brian'
  });

API

Assemble

Create an assemble application. This is the main function exported by the assemble module.

Params

• options {Object}: Optionally pass default options to use.

Example

var assemble = require('assemble');
var app = assemble();

Templates API

Assemble has an extensive API for working with templates and template collections. In fact, the entire API from the templates library is available on Assemble.

While we work on getting the assemble docs updated with these methods you can visit the templates library to learn more about the full range of features and options.

---

File System API

Assemble has the following methods for working with the file system:

• src
• dest
• copy
• symlink

Assemble v0.6.0 has full vinyl-fs support, so any gulp plugin should work with assemble.

.src

Use one or more glob patterns or filepaths to specify source files.

Params

• glob {String|Array}: Glob patterns or file paths to source files.
• options {Object}: Options or locals to merge into the context and/or pass to src plugins

Example

app.src('src/*.hbs', {layout: 'default'});

.dest

Specify the destination to use for processed files.

Params

• dest {String|Function}: File path or custom renaming function.
• options {Object}: Options and locals to pass to dest plugins

Example

app.dest('dist/');

.copy

Copy files from A to B, where A is any pattern that would be valid in app.src and B is the destination directory.

Params

• patterns {String|Array}: One or more file paths or glob patterns for the source files to copy.
• dest {String|Function}: Desination directory.
• returns {Stream}: The stream is returned, so you can continue processing files if necessary.

Example

app.copy('assets/**', 'dist/');

.symlink

Glob patterns or paths for symlinks.

Params

• glob {String|Array}

Example

app.symlink('src/**');

---

Task API

Assemble has the following methods for running tasks and controlling workflows:

• task
• build
• watch

.task

Define a task. Tasks are functions that are stored on a tasks object, allowing them to be called later by the build method. (the CLI calls build to run tasks)

Params

• name {String}: Task name
• fn {Function}: function that is called when the task is run.

Example

app.task('default', function() {
  return app.src('templates/*.hbs')
    .pipe(app.dest('dist/'));
});

.build

Run one or more tasks.

Params

• tasks {Array|String}: Task name or array of task names.
• cb {Function}: callback function that exposes err

Example

app.build(['foo', 'bar'], function(err) {
  if (err) console.error('ERROR:', err);
});

.watch

Watch files, run one or more tasks when a watched file changes.

Params

• glob {String|Array}: Filepaths or glob patterns.
• tasks {Array}: Task(s) to watch.

Example

app.task('watch', function() {
  app.watch('docs/*.md', ['docs']);
});

About

What can I do with it?

You can use assemble-core to create your own custom:

• blog engine
• project generator / scaffolder
• e-book development framework
• build system
• landing page generator
• documentation generator
• front-end UI framework
• rapid prototyping application
• static site generator
• web application

Related projects

Assemble is built on top of these great projects:

• assemble: Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt,… more | homepage
• boilerplate: Tools and conventions for authoring and publishing boilerplates that can be generated by any build… more | homepage
• composer: API-first task runner with three methods: task, run and watch. | homepage
• generate: Fast, composable, highly extendable project generator for node.js | homepage
• scaffold: Conventions and API for creating scaffolds that can by used by any build system or… more | homepage
• templates: System for creating and managing template collections, and rendering templates with any node.js template engine.… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Tests

Running tests

Install dev dependencies:

$ npm i -d && npm test

Test coverage

As of December 16, 2015:

Statements : 100% (38/38)
Branches   : 100% (8/8)
Functions  : 100% (10/10)
Lines      : 100% (38/38)

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

If Assemble doesn't do what you need, [please let us know][issue].

History

v0.7.0

• Bumps templates to 0.8.0 to take advantage of isType method for checking a collection type, and a number of improvements to how collections and views are instantiated and named.

v0.6.0

• Bumps assemble-fs plugin to 0.5.0, which introduces onStream and preWrite middleware handlers.
• Bumps templates to 0.7.0, which fixes how non-cached collections are initialized. This was done as a minor instead of a patch since - although it's a fix - it could theoretically break someone's setup

v0.5.0

• Bumps templates to latest, 0.6.0, since it uses the latest base-methods, which introduces prototype mixins. No API changes.

v0.4.0

• Removed emitter-only since it was only includes to be used in the default listeners that were removed in an earlier release. In rare cases this might be a breaking change, but not likely.
• Adds lazy-cache
• Updates assemble-streams plugin to latest

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2015 Jon Schlinkert Released under the MIT license.

---

This file was generated by verb on December 16, 2015.