tooling / book-of-modern-frontend-tooling Goto Github PK

@jrcryer and I have been writing an in-depth article on getting started with Yeoman and generator-angular that might be a good fit for this.

We walk through the basics and how to scaffold out a complete app that readers build by the end of the article. A few other things that would be useful to cover:

• How Yeoman gets you super-productive with Grunt by recommending tasks relevant to the app workflow you care about
• Grunt best-practices baked in and referencable from our Gruntfiles
• Talk some more about the community, possible how to write your own generator

volo also does scaffolding from templates, so it might be worthwhile to see if it fits here as well.

Would it be possible for us to update the current Gulp setup so that similar to the TOC we have in https://github.com/tooling/book-of-modern-frontend-tooling/blob/master/chapters/toc.md, we're able to include a linked up TOC in the generated HTML?

This would allow readers to skip to sections more easily (rather than scrolling through, which is what we have at present).

Introduction topics:

• Brief explanation
• General advantages
• General disadvantages
• History
  • make
  • Ant
• Segue

I hope that a history of previous build tooling is mentioned. I remember someone talking about Ant 2 years ago. :)
Here is a quick brainstorm for sub-topics. I'd love to hear more ideas!

Chrome doesn't load mixed content and the page breaks.

In order to provide something uniform (it's good for readers), we should decide which tone or style use. Stuff like:

• Informal? Formal? Can we have a sample text with the tone we would like, as reference?
• What style conventions for displaying tips, reserved words, etc?
• Which pronoun are we using to refer to third persons? (regardless of it being he/she/they we should decide one and be consistent).

Maybe the easiest way would be just have a text or book we like and adopt their style / conventions choices.

Github Page

Sprout serves a similar purpose to Yeomen, except that Sprout has a clean and understandable generator API with a public javascript API for integration into other projects. There's a lot of sprout templates out there and Sprout is also used within Roots.

Found that the HMR section is incomplete. I can write for it with examples.
Amazing book though !

JSWeekly #170 had this article on Fez

The project page is at http://fez.github.io/

I'm not sure what qualifies a project to be included in the book. Creating this ticket as a reminder / placeholder.

Ideally we want a setup that:

• Supports authoring in markdown (multi-file)
• Can be converted to multiple formats at build time easily (production-ready HTML, epub, PDF, etc.)
• Can support multiple-languages. Consider a nice to have, but not critical for the initial version of the setup.
• Does not require a large number of third-party binaries in order to work. I've had a lot of experience with these causing build problems on platform-X on other books, avoiding this would be nice if possible.
• For any images, store the original source but builds should use optimized versions.

Currently when you generate a HTML version of the book we have no real styling in place :) It looks like this: http://cl.ly/image/2p411w1r3J1G

It would be great to get some CSS in place to make this look more sexy. I can drop in Bootstrap or if someone would like to spend a little more time integrating this into the build setup maybe we can enable a designer to work on something cleaner.

cc @rowoot

Hi @addyosmani ,

I think it would be good to add an i18ns section to your book. I'm the author of http://l10ns.org it addresses a lot of i18n workflow issues. We live in a very sad world where many font-enders don't know how to solve i18n issues nowadays. They just hardcode their translations and use one language instead. It is good to educate them that i18n is an issue and that their exists tooling for this problem.

Currently in the index we have:

• Introduction
  • Why automate?
  • Command-line
  • Node and npm
• Build systems
  • Modern tools vs. shell scripts
  • Grunt
  • Brunch
  • Gulp
• Scaffolding
  • Yeoman
  • Loom
• Dependency Management
  • Bower
  • npm + Browserify
  • ComponentJS

We'll want to revise this with the structure we've been discussing over in #9 so that it's clear to contributors what we'd love to have covered.

Dependencies is mistyped under https://github.com/tooling/book-of-modern-frontend-tooling#depedencies

Small thing, but perfectionists feel their eyes bleeding. ;-)

Edit:

List of msc tools

fez - JS general purpose build tool based on tup

Static web page builders

roots, docpad, wintersmith, borschik
Mimosa - emphases module loader endgame

Static web server

harp

There are several other tools that should be mentioned, like:

http://roots.cx/

A light, super fast, and intuitive static build system made for front end development and building web apps.
Roots comes in the form of a static site build tool by default, but also includes templates and plugins for express and rails.

On Github: Watch: 42, Star: 784, Closed Issues: 324
Node based, on GitHub for over a year, almost weekly updates, somewhat opinionated it seems. Doesn't seem to have a plug-in system, so the use-cases are narrowed to static sites or SPAs. Enough popularity for a mention IMHO.

https://github.com/component/component is a package manager that focuses on front-end packages only. In addition to providing a CommonJS module system, its packages can also contain assets like templates, CSS, font files and images. It also covers some build tool functionality through the use of build plugins (e.g. process coffeescript, jade, stylus etc. during build)

Updated to reflect Brunch focus as a build tool more than scaffolding

Brunch is an application assembler for organizing and building webapps. If we're covering Grunt and Gulp, it would be nice to balance this out with a detailed write-up on using Brunch too. They're all great tools.

@paulmillr I noticed https://github.com/brunch/brunch/wiki is a few months old. Do you have any recent articles/authors of great tutorials on Brunch you think it would be useful to speak to? Would be great to have it captured here too.

http://tooling.github.io/book-of-modern-frontend-tooling/dependency-management/webpack/3-code-splitting.html

Bower is a package manager for the web. It offers a generic, unopinionated solution to the problem of front-end package management. Chapter ideas:

• Installation
• Discovering packages / search
• Installing packages
• Updating and uninstalling packages
• Using packages
• Publishing packages
• Other Bower pro-tips

The trick with this section is going to be deciding how much of the tooling around Node/npm we include in the introduction section of the book (given that Grunt/Yeoman etc rely on them so heavily) vs. how much of this we capture in this chapter.

Either way we should talk about:

• Compelling reasons to use a single package manager
• Introduction to Browserify - how it works, where it fits in your workflow
• Demonstrate building a simple app perhaps using components that rely on a Browserify layer for their modules/packages so it's clear how you would practically use it.

We can very likely flesh this out better. Ideas welcome.

For the Modern tools vs Shell scripts section, npm run deserves a mention since it gives you many of the benefits of shell scripts without all the up-front configuration that many of the other tools require. Here's the article I wrote about using npm run with the package.json scripts field: task automation with npm run.

Augmented with other narrowly focused tools on npm, you can get a lot done. Here's another example that uses catw and watchify to watch and rebuild less and javascript whenever a file changes.

The biggest benefit to this shell-oriented way of organizing things is that you don't need up-front coordination among the tool authors, so it's much easier to integrate pieces that have already been written that can read and write to stdin and stdout rather than having to write a grunt-* or gulp-* plugin to wrap the functionality manually. You're much more free to recombine the pieces in novel ways and to add components piecemeal. The downside is that there is a learning curve if you don't already know bash and it can take time to discover which tools you really like and fit your mental model and standard approaches well. This is also true of integrated solutions but there is more prescription about which tools are the "best" which I personally dislike because I so often disagree with those prescriptions.

I think "modern tools vs shell scripts" is perhaps not the right way to phrase the dialectic here. It's more about vertically-integrated tools versus more horizontally-oriented tools, or top-down vs bottom-up or centralized vs decentralized or integrated tooling vs unix. It's the same thing as [chaotic vs lawful alignment](http://annex.wikia.com/wiki/Alignment_(Dungeons_%26_Dragons%29).

Looks like a really cool project. Wondering if Harp could be included?

Per the requirements:

• Harp, sintaxi/harp
• Actual users: CascadiaJS, GenomeJS, Harp Hook, a Harp + GitHub Pages deployment system was a winner of Node Knockout, Harp Weekly newsletter features people’s projects
• Good docs
• Actively maintained: 65 Release in 2013 plus one three days ago
• Intention to do so in the future: Milestones, used by the Harp Platform

I know @jorgepedret has been considering a similar project to this book, maybe he’d be interested in helping here?

I can source repurposable content based on the section that you think would be most appropriate. Harp is a web server, so it could possibly fit into scaffolding or build systems in the context of this book.

You'll notice that the initial chapters proposed represent a limited list of the material that could be covered on front-end tooling.

There's a lot out there and I think that for the first version, we should avoid looking at topics like debugging, testing with a specific solution (unless its presented as part of the workflow of using one of the tools already on there).

Does anyone massively disagree with this or should we reconsider scope?

See #64 (comment)

Outline (work in progress)

• Introduction
  • Problem scope and vision
• Architecture
  • Graph model
  • Assets
  • Relations
  • Query language
  • Transform queue
• Assetgraph lifecycle
• Example implementation: Inlining images
• Example implementation: File revisioning
• Comparison with other tools
• Out of the box build tools
• Full workflow example

This is a really awesome project, but what I think would be really cool is if this was ported as a GitBook

Essentially, that would allow you to write everything in Markdown, push via Git, and you'd have a web version that looks similar to what you have now, as well as .epub, .pdf, and .mobi compilation.

A chapter on getting started with the Grunt.js task runner. The common things I see front-enders new to Grunt trying to do include:

• Getting started (Gruntfile, package.json)
• Adding a linter
• Integrating a CSS preprocessor (Sass, Less)
• Starting a local server
• Live reload (maybe)
• Running tests
• Housekeeping (clean, best practices for matchdep etc)
• Deployment

These topics could be useful to cover.

Following error is shown when using gulp generate:epub
I'm using Node 4.3.0 on Windows 10.

Cezary@Cezary-PC MINGW64 ~/Desktop/Downloads/book-of-modern-frontend-tooling (master)
$ gulp generate:epub
[00:23:10] Using gulpfile ~\Desktop\Downloads\book-of-modern-frontend-tooling\gulpfile.js
[00:23:10] Starting 'concat'...
[00:23:10] Finished 'concat' after 127 ms
[00:23:10] Starting 'generate:epub'...
events.js:141
      throw er; // Unhandled 'error' event
      ^

Error: write EPIPE
    at exports._errnoException (util.js:870:11)
    at Socket._writeGeneric (net.js:675:26)
    at Socket._write (net.js:694:8)
    at doWrite (_stream_writable.js:292:12)
    at writeOrBuffer (_stream_writable.js:278:5)
    at Socket.Writable.write (_stream_writable.js:207:11)
    at Socket.write (net.js:618:40)
    at Socket.Writable.end (_stream_writable.js:433:10)
    at Socket.end (net.js:400:31)
    at pdc (C:\Users\Cezary\Desktop\Downloads\book-of-modern-frontend-tooling\node_modules\pdc\pdc.js:69:16)

Generating PDF works OK

When running gulp generate:* the build fails because the file build-systems/gulp/writing-tasks.md referenced in the TOC does note exist.

It appears that e0c15fa broke out the gulp task chapter into basic and advance and the TOC should be updated to point to the newly created chapters.

I am not sure whether this has been discussed yet, but I am looking to put together some introductory content to help set some user expectations regarding the book.

As a reader of this book

• I wish to understand what is frontend tooling?
• Why is frontend tooling important and what does it consist of?

(Please let me know if I am missing any other user use-cases)

Now, #15 briefly calls out some topics and I have expanded on them below. I look forward to hearing thoughts/ideas on how this can be improved.

• Introduction
  • Some history on frontend development (Probably walk through various trends on web app architecture)
  • Pre-Rails era (PHP based web apps, Flash based apps)
  • Rails era - REST based web apps (probably talk about the transition phase where the presentation layer is moved out of Rails apps)
  • Post-Rails era - Single page apps
• Why automate?
  • Briefly talk about the increase in complexity of building frontend apps (perhaps mention how frameworks such as Angular, Ember, Backbone etc have had an impact on this).
  • Use an example app (todomvc) to describe the richness and complexity of frontend apps and how automation helps during development, testing and deployment.
• Command-line
  • Make a case as to why command line should be embraced by frontend engineers
• Node and npm
  • How node and npm is used towards the development of frontend apps?

It would be great if mimosa will be added in the Build systems section
http://mimosa.io/

I found the code splitting part of webpack tutorial section is empty.

It would be great to see webpack included. It is fantastic module bundler that combines the capabilities of many of the other module bundlers. Totally framework and package manager agnostic as well.

I've written about it here: http://dontkry.com/posts/code/single-page-modules-with-webpack.html

They are nearing a 1.0.0 release and I'll be helping out more with their docs. I'd love to help write a chapter about managing deps with webpack here.

Thanks!

https://github.com/atomify
"Atomic web development - Combining the power of npm, Browserify, Rework and more to build small, fully encapsulated client side modules"

I just want to throw it in because I find it an interesting alternative to webpack or component. some see it as an extension of the browserify approach.

Ben Clinkinbeard wrote a good atomify introduction article

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.

I am wondering if I can help you add some Chinese translations to this book.

link to page

browserify app.js --output bundle.js

it should be

browserify app.js --outfile bundle.js

At the moment a reader can't preview what's been written so far without checking out the repo, doing an npm install and running the gulp build setup. I'd like to propose that we either:

1. Add a gulp deploystep to the build process which can push the contents of dist to gh-pages for those with commit access. Possibly the cleanest option.
2. Move master to gh-pages, make it the default branch and have an index.html which lives outside of the dist directory but can be used to view the book.

There are probably lots of other options available to us, but just opening the floor for discussions or PRs to bring something in place :)

Wow. Just wow.

I've been banging my head trying to learn Webpack for a long time until I stumbled upon your tutorial, and everything just makes sense!

Thank you SO MUCH! Your tutorial is probably the best on the internet!!!!

Hey, I think I'm a little fuzzy on if we're going for paperback book or PDF/online "book". If we're not planning on going the printed book route as the target consumption format, I would rather morph this project into "the official website of expert use cases, pro-tips, and getting started instructions on modern day frontend tooling."

Instead of splitting up content into "the Grunt chapter" and "the Bower chapter", I envision those "chapters" being "pages" on the website. From that "Bower page", you would then branch out based on your experience level. Maybe only 2 or 3-tiered, from "I've heard the name, but have no idea what it is" -> "I've used it, but have no idea what I'm doing" -> "I'm an expert. Feed me pro tips and perf optimization!"

This way, we have more room to grow outside of the confines of a one-size-fits-all chapter. Basically, the idea described above is exactly what I had in mind for taptapship almost a year ago! Seeing the growing suite of tools over the last year and the awesome response from the community over this project, it might be worth considering.

Just wanted to throw this out there before it's too late!

I think in order to properly establish standards since the beginning, we should start naming semantically the chapters folder contents and their contents recursively.

This will be useful when automatically generating both pdf and html versions of the book, and will bring us some perks like:

1- Easy generation of TOC's files.
2- Properly structuring the book using simple conventions.

I've created a single file within each chapter named chapter-resume.md thinking on an introduction for each chapter, something like an excerpt.

Any thoughts @addyosmani @PascalPrecht @stephenplusplus?

volo is a great tool and for sure it deserves a spot here (:

Github Page

Roots is a fast, simple, and customizable static site compiler. With Roots we can easily create static sites and if we use all the tools provided we can create a scalable site that are Hybrid-Static sites. Roots also allows us to integrate Wordpress and Contentful and build your site using your prefered languages. Checkout the readme and roots homepage (see previous links).

At the moment, going to http://tooling.github.io/book-of-modern-frontend-tooling/introduction.html gives you the current version of the book based on the gh-pages branch. Links to most of the chapters result in a 404, even if the content exists. I believe this is because of the way the TOC is currently generated.

I wonder if it's worth taking another look at how the TOC is handled and only list the sections that have content written up for them. Perhaps graying out the items that don't have any content yet. Does that sound like a feasible/sensible way of displaying the navigation?

cc @rowoot @sindresorhus

I may have missed it but I'd vote for a mention of coffeescript:

• Grunt/Gulp support CS
• For documentation, docco is great and I believe it works with JS as well as CS
• And Cake is surprisingly effective, even as tiny as it is. I like systems I can read overnight.

http://linemanjs.com/

I think having a chapter or section for "How is Gulp Different" or good to have, but hard to scan. Could there be a table to compare features & gotchas please? I found Wil Moore's Frontend Packagers very handy. This table shouldn't have as much prose as Wil's does (chapters cover this), but since more than 2 possibilities are going to be studied, a single table helps to scan.

I would think the source data should be in .JSON, then a script ran to turn the data into what ever format table.

It could be developed with the book, or near v0.8, to help ensure the book explains the table, & the table can help find topics.
Or maybe released after v1.0 is done, so all has to be done is collate the book's info.

cheers

Project page

Introductory blog post

I'm not sure what qualifies a project to be included in the book. Creating this ticket as a reminder / placeholder.