assemble-core

    0.31.0 • Public • Published

    assemble-core

    NPM version NPM monthly downloads Build Status Gitter

    Built on top of base and templates, assemble-core is used in assemble to provide the baseline features and API necessary for rendering templates, working with the file system, and running tasks.

    Implementors and hackers can use assemble-core to create rich and powerful build tooling, project scaffolding systems, documentation generators, or even your completely custom static site generators.

    Table of contents - [What can I do with assemble-core?](#what-can-i-do-with-assemble-core) - [Install](#install) - [Install](#install-1) - [Usage](#usage) - [Examples](#examples) - [API](#api) * [File System API](#file-system-api) + [.src](#src) + [.dest](#dest) + [.copy](#copy) + [.symlink](#symlink) * [Task API](#task-api) + [.task](#task) + [.build](#build) + [.watch](#watch) - [FAQ](#faq) - [Toolkit suite](#toolkit-suite) - [About](#about) * [Related projects](#related-projects) * [Tests](#tests) * [Contributing](#contributing) * [Release History](#release-history) * [Authors](#authors) * [License](#license)

    (TOC generated by verb using markdown-toc)

    What can I do with assemble-core?

    Create your own:

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

    Install

    NPM

    Install

    Install with npm:

    $ npm install --save assemble-core

    yarn

    Install with yarn:

    $ yarn add assemble-core && yarn upgrade

    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();
     
    var view = app.view('foo', {content: 'Hi, my name is <%= name %>'});
     
    app.render(view, { name: 'Brian' }, function(err, res) {
      console.log(res.content);
      //=> 'Hi, my name is Brian'
    });

    Render a view from a collection:

    var app = assemble();
    app.create('pages');
     
    app.page('foo', {content: 'Hi, my name is <%= name %>'})
      .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();

    File System API

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

    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

    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']);
    });

    FAQ

    How does assemble-core differ from assemble?

    feature assemble-core assemble notes
    front-matter parsing No Yes use assemble or use parser-front-matter as an .onLoad middleware.
    CLI No Yes Create your own CLI experience, or use assemble
    Built-in template collections No Yes Use .create() to add collections
    Built-in template engine No Yes assemble ships with engine-handlebars. Use .engine() to register any consolidate-compatible template engine.

    Toolkit suite

    assemble-core is a standalone application that was created using applications and plugins from the toolkit suite:

    Building blocks

    • base: framework for rapidly creating high quality node.js applications, using plugins like building blocks.
    • templates: used to create the foundation of assemble-core's API, along with support for managing template collections, template engines and template rendering support

    Plugins

    About

    Related projects

    Assemble is built on top of these great projects:

    • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
    • boilerplate: Tools and conventions for authoring and using declarative configurations for project "boilerplates" that can be… more | [homepage](https://github.com/jonschlinkert/boilerplate "Tools and conventions for authoring and using declarative configurations for project "boilerplates" that can be consumed by any build system or project scaffolding tool.")
    • composer: API-first task runner with three methods: task, run and watch. | homepage
    • generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
    • scaffold: Conventions and API for creating declarative configuration objects for project scaffolds - similar in format… 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 and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

    $ npm install && npm test

    Contributing

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

    Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

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

    Release History

    key

    Changelog entries are classified using the following labels from keep-a-changelog:

    • added: for new features
    • changed: for changes in existing functionality
    • deprecated: for once-stable features removed in upcoming releases
    • removed: for deprecated features removed in this release
    • fixed: for any bug fixes

    Custom labels used in this changelog:

    • dependencies: bumps dependencies
    • housekeeping: code re-organization, minor edits, or other changes that don't fit in one of the other categories.

    Heads up!

    Please let us know if any of the following heading links are broken. Thanks!

    0.31.0 - 2017-11-2011

    dependencies

    • Bumps assemble-streams to ensure that view is decorated with .toStream() when created by app (instead of a collection). This is arguably a bugfix, but it might break someone's code.

    0.30.0 - 2017-08-01

    dependencies

    • Bumps assemble-fs and assemble-render-file to get updates that merge the dest path information onto the context so that it can be used to calculate relative paths for navigation, pagination, etc.

    0.29.0 - 2017-02-01

    dependencies

    • Bumps assemble-fs to v0.9.0 to take advantage of improvements to .dest() handling.

    0.28.0 - 2017-02-01

    dependencies

    • Bumps templates to v1.2.0 to take advantage of new methods available on lists

    0.27.0 - 2016-12-27

    dependencies

    • Bumps templates to v1.0.0 to take advantage of new template inheritance features!
    • Bumps assemble-fs to v0.8.0

    0.26.0 - 2016-08-06

    dependencies

    • Bumps assemble-fs to v0.7.0 to take advantage of handle.once
    • Bumps templates to v0.25.0 to take advantage of async collection loaders. No changes to existing API.

    0.25.0 - 2016-07-05

    changed

    • Minor code organization and private properties were changed. This is technically a housekeeping change since these methods weren't exposed on the API, but it's possible someone was using them in an unintended way.

    0.24.0

    dependencies

    removed

    • The bump in templates removes the renameKey option from the .data method. Use the namespace option instead.

    0.23.0

    fixed

    0.22.0

    dependencies

    • Bumps templates to v0.22.0 to take advantage of fixes and improvements to lookup methods: .find and getView. No API changes were made. Please let us know if regressions occur.
    • Bumps base to take advantages of code optimizations.

    fixed

    • fixes List bug that was caused collection helpers to explode

    changed

    • Improvements to lookup functions: app.getView() and app.find()

    0.21.0

    dependencies

    removed

    • Support for the queue property was removed on collections. See templates for additional details.

    0.20.0

    dependencies

    changed

    • Some changes were made to context handling that effected one unit test out of ~1,000. although it's unlikely you'll be effected by the change, it warrants a minor bump

    0.19.0

    dependencies

    housekeeping

    • Externalizes tests (temporarily) to base-test-runner, until we get all of the tests streamlined to the same format.

    0.18.0

    dependencies

    • Bumps assemble-loader to v0.5.0, which includes which fixes a bug where renameKey was not always being used when defined on collection loader options.
    • Bumps templates to v0.18.0, which includes fixes for resolving layouts

    0.17.0

    dependencies

    0.16.0

    dependencies

    0.15.0

    dependencies

    0.14.0

    dependencies

    deprecated

    • .handleView method is now deprecated, use .handleOnce instead

    changed

    • Private method .mergePartialsSync rename was reverted to .mergePartials to be consistent with other updates in .render and .compile.

    added

    • adds logging methods from base-logger (.log, .verbose, etc)
    • No other breaking changes, but some new features were added to templates for handling context in views and helpers.

    0.13.0

    • Breaking change: bumps templates to v0.13.0 to fix obscure rendering bug when multiple duplicate partials were rendered in the same view. But the fix required changing the .mergePartials method to be async. If you're currently using .mergePartials, you can continue to do so synchronously using the .mergePartialsSync method.

    0.9.0

    • Updates composer to v0.11.0, which removes the .watch method in favor of using the base-watch plugin.

    0.8.0

    • Bumps several deps. templates was bumped to 0.9.0 to take advantage of event handling improvements.

    0.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.

    0.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.

    0.5.0

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

    [0.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

    (Changelog generated by helper-changelog)

    Authors

    Jon Schlinkert

    Brian Woodward

    License

    Copyright © 2017, Jon Schlinkert. MIT


    This file was generated by verb-generate-readme, v0.4.2, on February 11, 2017.

    Install

    npm i assemble-core

    DownloadsWeekly Downloads

    24,715

    Version

    0.31.0

    License

    MIT

    Last publish

    Collaborators

    • doowb
    • jonschlinkert