Build systems > Gulp

[addyosmani]

Gulp is a streaming build system. Like Grunt, but faster and less config. There currently aren't a lot of tutorials about Gulp out there at the moment.

It would be useful to cover some of the same items in #2, but with a focus on using Gulp plugins, talking about how it differs from other build systems etc.

[sindresorhus]

@travm might be interested as he has written a couple of articles on Gulp.

[addyosmani]

Thanks @sindresorhus! Being relatively new there are still a lot of best practices around Gulp that have yet to be documented and I'd love to see a chapter on it in here.

[travm]

I'd be glad to help out. Just let me know how we'll be organizing the information and where to begin work.

[addyosmani]

Fantastic. Will let you know as soon as we have the basic setup for contributing committed.

[addyosmani]

Okay, now that we've got the basics for #8 (build system) in place, I think we're ready to start accepting contributions. @travm would you like to propose what topics a Gulp chapter should ideally cover? Would love to have you author if you'd be down for that.

[travm]

Using what was mentioned in issue #9 by @rowoot I think this would be a good start.

• Introduction
  • Why Gulp?
  • How Is It Different?
• Getting started
  • Installation (How Detailed Should This Be?)
  • Debugging (Common Installation/Getting Started Issues - or should this be included in the final section below?)
• gulp Specific/Simple Code Walkthroughs
  • Adding A Linter
  • CSS Preprocessing
  • Local Server/Live Reload
  • Running Tests
  • Deployment
• Best Practices
• Troubleshooting/Common Issues

How detailed would we want the installation notes to be? Since most Node tools will share a similar installation process, should we start from the very base of installing Node? Or, should we assume that the reader has already viewed the introduction chapter for Node and npm?

[addyosmani]

That looks like a great start. I would say we should assume that Node and npm are already available and setup. We'll cover how to do this in the first chapter so that there doesn't have to be repetition there. We can always refer readers back if they aren't familiar with the tools needed to setup :)

[michealbenedict]

I like @travm's idea of having code walkthroughs (assuming these are links to plunkr/jsbin/jsfiddle) as part of the tool specific content. I somewhat feel that there could be an overlap between "Best practices" content and the tool specific content. Probably we should roll up the "Best practices" section?

[travm]

@addyosmani Sounds great! Let's create the folder/file structure for the chapters and the sections and how they relate, just to be sure we wont have any conflicts as users begin writing content. Should each chapter and section have it's own separated .md file or will we be adding information to a shared .md file? Should we separate each chapter inside of its own folder? I'm not sure what would be best for everyone contributing and how this would affect the build that has been setup.

@rowoot I think you're right. Unless we can identify specific cases where we need a Best Practices section, I think we could probably roll that up until we absolutely need it. We may need to check with the authors for the other tools to ensure those tools don't need a separate Best Practices section. It may be best to leave it as an optional section as needed, where the other sections we've outlined should be consistent.

[michealbenedict]

@travm and @addyosmani What are your thoughts on the following structure https://github.com/rowoot/book-of-modern-frontend-tooling/tree/file-structure/chapters

The directory structure might something like this

• Chapters
  • {tool-name}
  • section-{*}.md

Pros:

• Easier to maintain and accept PR for specific portions of the content.
• From a dev perspective, we can be creative on how these markdowns can be exported to specific formats (Eg, grep section-* > single html or generate TOC based on section-*)

Cons:

• Some files might have less to no content, while some (like the tool specific content) will have loads of content

[addyosmani]

I like the proposed structure. What about assets like images? Should all chapters share the same image directory or should each chapter have its own? Once we have that down I'm happy with us to move forward with the above.

Thanks again!

[travm]

I'm leaning a bit toward the single image directory. Unless we decide to put each chapter into it's own folder (with the images and sections as subfolders). @rowoot, what are your thoughts?

[ajoslin]

I think one shared assets directory would be best, because we may re-use some images. We can always prefix images by section/chapter if they are collision-risky.

[michealbenedict]

@travm and @ajoslin based on your input, I have an example layout at #9 (comment). Feedback appreciated.

[sindresorhus]

// @contra

[yocontra]

Awesome! Let me know if anyone has questions in terms of content - always happy to help out. One thing I think is crucial before diving into code (maybe this belongs in "Why Gulp") is explaining streams briefly. People who do front-end dev will not have prior experience with them so it may seem foreign.

[travm]

+1 for the streams introduction. @contra, if you have some time, you could probably explain that much better than I could.

I've started on the code examples for each task. We'll start with what I've listed in the outline above and then we can add to it as we identify other common tasks. Also, It may be a valuable to match all the build tool example tasks and keep them as consistent as possible so readers can easily compare and see which tool fits them best.

[yocontra]

@travm Check out https://github.com/substack/stream-handbook for good analogies and stuff

[dashed]

If you need a newbie perspective on streams/gulp, I can give some tips 😄

[travm]

I've almost completed the intial gulp docs. I'll submit a PR in the next couple days.

@dashed would you be comfortable working on the breakdown explanation on streams and how they work? If not, I can put something together this week!

[dashed]

@travm I haven't used streams as much other than in gulp.

I had meant that I could give some info from a newbie perspective -- typically some stuff that usually is passed off as trivial knowledge. But, I'd be happy to provide anything that'd be useful.

Are you going to write some stuff in markdown on GitHub?

[travm]

I see! Sorry I misunderstood. I'll have the task code examples/walkthroughs ready in the next couple days. Then I can put together some information on streams and the introduction material.

[dashed]

Looking forward to it.

[travm]

Submitted a PR #23 for the initial gulp task examples (and some other info). That should get us started!

[addyosmani]

@travm Thanks once again for your awesome start on this back in #24. I was wondering if you might have some time to flesh the chapter out a little more. I'd love to get the current content a little more polished and if time is an issue, we can even just link to existing good content as an interim.

[travm]

@addyosmani I'd be happy to. I'm in San Francisco this week on Vacation, but once I get back to my office next week I'll definitely see what I can do to flesh it out.

[travm]

Sorry about the delay, I'm going to take a look at this chapter this evening and see where and I add more information and possibly improve what is already there.

[gaboesquivel]

hi guys, my little contrib .. gulp-connect is all you need for server/livereload. You may want to talk about The Gulp.js team working on bringing in a new task system to improve efficiency ( even more ) and it might include some API changes, you can follow the progress here gulpjs/gulp#355 ...

I'm working on an intro post, some good refs there https://github.com/gaboesquivel/gaboesquivel.github.io/blob/source/source/_posts/2014-04-20-introduction-to-gulpjs.markdown

This is useful too https://www.npmjs.org/package/lazypipe

[travm]

Thanks! I'll take a look at gulp-connect tonight. I'm not sure if it was around when I initially wrote the live-reload bit. gulp-connect seems much better.

I've been thinking about all the improvements they have been working on - and I've been a bit hesitant to continue writing until they have completed those upgrades (especially if the api will end up changing). I'll do some homework tonight and try to get caught up on what they have planned for the future and keep that in mind as I write new information.

Thanks for the help!

[travm]

Working on some updates and replaced the LiveReload solo section with gulp-connect and LiveReload information. Thanks @gaboesquivel, they work much better together!

I noticed the Grunt chapter was organized a bit differently and I am afraid I've overlooked a change to the chapter organization. What is the consensus on how we separate the information to keep it consistent across chapters? What works best once we compile into HTML? For example, is it better to separate each task into a separate file? Multiple tasks to a single file? Let me know!

@addyosmani @sindresorhus

[yocontra]

@travm I would prefer if blacklisted plugins weren't used anywhere in this. I would blacklist gulp-connect 5 times if I could.

[travm]

@contra Thanks so much for catching that and letting me know. I'll rewrite that bit again using the connect module directly.

[sindresorhus]

I noticed the Grunt chapter was organized a bit differently and I am afraid I've overlooked a change to the chapter organization

I don't think we have a defined standard, but we should, and it should be consistent.

For example, is it better to separate each task into a separate file? Multiple tasks to a single file?

Can you elaborate?

[travm]

For example, in the gulp chapter I currently have multiple tasks in a single file (writing-tasks.md). In the Grunt chapter it is a separate file for each task (linter.md, sass.md).

I wasn't sure which was best for when we compiled the data into html or pdf. What are your thoughts?

[sindresorhus]

I think writing-tasks.md has an ok length. I don't think it makes sense to split up every task there.

[travm]

Sounds good! I have some revisions to finish up this evening, and then I'll just create an additional file for more advanced tasks and submit a PR.