Consider adding examples of using Assemble in gulp

[jpgcode]

Starting Assemble 0.6 the API changed a lot. The gulp-assemble project is deprecated and there is some documentation there of how to use it but sometimes is hard to make Assemble works in gulp reading only the documentation.

A simple gulpfile with Assemble configured using partials and layouts would be good to add to your recipes.

Also, Grunt version was using handlebars-helpers as extra helpers, in the new one, these helpers are not coming as default, so if you could add some example of how to use them it would be good.

[stefanwalther]

Yep, good idea, take it.

[jonschlinkert]

you might want to read over the FAQ before advocating using assemble with gulp.

[stefanwalther]

I think key of a recipe would be to show how easy you can use assemble with existing gulp tasks, resp. using all possible gulp-tasks within assemble. That's really so powerful.

But, just read that the title of this thread is the misleading, should really be "Leverage the power of gulp within assemble" ;-)

[jpgcode]

You got it @stefanwalther! I know Assemble works as node.js module directly. However, a lot of people are using Gulp for their projects (including me). So having examples within Gulp will be helpful for a lot of people.

[jonschlinkert]

ok, this got me thinking about how we can begin documenting how assemble differs from gulp, and from that we can more easily explain how to use assemble in a gulpfile.js more effectively. This is totally possible, and would be really nice for a lot of gulp users to know the caveats and how to work around them. (I'm going to put some thoughts down here to remind me what to add to the docs... might be a bit lenghty).

To be clear, most gulp users can just use assemble in their gulpfiles without any additional consideration.

However... you will run into an issue related rendering or middleware handling at some point. Not because of bugs, but because the more advanced your build gets, the more likely it will be that you need some special feature that assemble offers that - when not handled by assemble directly - might required some manual intervention.

For example, gulp.src and gulp.dest do not call assemble's middleware handlers. but assemble's app.src and app.dest do. So while you can easily require in assemble-handle and add the handlers to your gulp pipeline, that's something you'll need to know to do in the first place - and that's just one example.

We tried very hard to make assemble work with gulp "out of the box" for as many common use cases we could think of, but everyone has their own edge cases, so we'll just need to learn though this together.

Anyway, sorry for the long-winded preamble. I just did this graphic as a starting point to explain the differences. This is what I would call an "abstract build cycle".

Assemble has a fairly extensive render cycle that begins before the file transformation cycle. There are more than a dozen points in the render cycle where middleware handlers are called. Beyond that, assemble has "smart plugins" that run on "app", collection and view instances, as well as events that are fired in concert with the plugins and middleware. When assemble pipeline plugins are run (plugins that run on vinyl files), those plugins also sometimes have special logic to coordinate with assemble's render cycle.

We try to keep custom logic in those plugins to an absolute minimum: the goal is to create a gulp plugin, but if there absolutely must be any assemble logic at all, we publish the plugin as an assemble plugin.

[jpgcode]

Thanks for the clear explanation @jonschlinkert it makes sense! I'm not sure if I'm using it wrong (I'm not node.js/gulp expert). But this is how I'm using Assemble inside my gulpfile:

gulp.task('load', (cb) => {

  //Set main assemble options
  app.layouts('app/layouts/*.hbs');
  app.pages('app/pages/**/*.hbs');
  app.partials('app/components/**/*.hbs');
  app.engine('hbs', require('engine-handlebars'));
  app.data(['app/{pages,components,data}/**/*.json']);

  //Custom helpers
  app.helper('get', function(prop) {
    return get(this.context, prop);
  });

  app.helper('pagename', function(){
    let url = get(this.context, 'view.path');;
    let pagenameArr = url.split('/');
    let pagename = _.last(pagenameArr);
        pagename = pagename.split('.')[0];
    return pagename;
  });

  cb();
});


gulp.task('assemble', ['load'], () => {

    return app.toStream('pages')
      .pipe(app.renderFile())
      .pipe(extname())
      .pipe(flatten())
      .pipe(plumber())
      .pipe(app.dest(config.tmp));
});

I'm not using gulp.src or gulp.dest to get/output my files. I'm using assemble just as I would use it separately in assemblefile.js, I'm just defining the assemble task in my gulpfile so I can call it when needed, probably this is not the "Gulp" way, but it works correctly. (So far).

Last Dec, I started to integrate Assemble 0.6+ in my development workflow, and as for now I have been able to make it work using the above approach. However, was a very hard path that I had to follow to get to the point I'm now, so my initial idea behind this ticket was to clearly define what is the best approach to use Assemble inside Gulp. It would be good if you could take a look my code and give me some recommendations to see if I'm really taking fully advantage of Assemble with my current approach or I could do it differently.

On any case, my code as it is for now is fully working and I'm happy so far, so probably that could help someone else trying to do the same thing I wanted some months ago.

Here my complete code: https://github.com/jpgcode/gulp-starterkit/blob/master/gulp/tasks/assemble.js

Assemble is AWESOME!
Thanks for your dedication and sharing!

[jonschlinkert]

I'm not using gulp.src or gulp.dest to get/output my files.

that's the key. there are only a few things you need to remember, then you're up and running. everything you're doing looks great.

based on your comments and having time to think about it, it might be even more effective if we just put a list of tips or FAQs together for how to use assemble effectively in a gulpfile. none of it should be rocket science or hacky, it's just using one node.js tool effectively with another.