[Docs] gulp handbook guide removes watchify when adding babel

[DanielRosenwasser]

From @marianoguerra on May 14, 2016 15:42

The docs here: http://www.typescriptlang.org/docs/handbook/gulp.html adds features by steps, at some points it adds watchify to the browserify build task, then adds babel, and at doing so removes the watchify features added one step before.

The final setup ends up not supporting watchify which was introduced in the same guide.

Copied from original issue: microsoft/TypeScript#8608

[DanielRosenwasser]

From @marianoguerra on May 14, 2016 15:48

The last step but with watchify included (could be a next step, like "adding back watchify" if only the changed required to have babel are left in the docs)

var gulp = require('gulp');
var browserify = require('browserify');
var source = require('vinyl-source-stream');
var watchify = require("watchify");
var tsify = require('tsify');
var gutil = require("gulp-util");
var sourcemaps = require('gulp-sourcemaps');
var buffer = require('vinyl-buffer');

var paths = {
    pages: ['src/*.html']
};

gulp.task('copyHtml', function () {
    return gulp.src(paths.pages)
    .pipe(gulp.dest('dist'));
});

var watchedBrowserify = watchify(browserify({
    basedir: '.',
    debug: true,
    entries: ['src/main.ts'],
    cache: {},
    packageCache: {}
}).plugin(tsify));

function bundle() {
    return watchedBrowserify
    .transform("babelify")
    .bundle()
    .pipe(source('bundle.js'))
    .pipe(buffer())
    .pipe(sourcemaps.init({loadMaps: true}))
    .pipe(sourcemaps.write('./'))
    .pipe(gulp.dest('dist'));
}

gulp.task('default', ['copyHtml'], bundle);
watchedBrowserify.on("update", bundle);
watchedBrowserify.on("log", gutil.log);

[fairydhwen]

Can you add uglify in this example plz ?

[sandersn]

Sounds like the tutorial should end with a single giant example that chains watchify, bably and uglify all together at once.

[DanielRosenwasser]

Yeah I agree. Let's discuss later today?

[mikelehen]

FWIW- This is still confusing. The entire tutorial is incremental until the final Babel section. When adding babel, it removes watchify, uglify, and the greet.ts file that were all added in earlier steps. It also doesn't provide any explanation for why it's adding babel and the tutorial ends abruptly with "Babel’s ES5 output should be very similar to TypeScript’s output for such a simple script."

It's tempting to just remove this section or move it somewhere else. It doesn't really fit in.

[mikelehen]

Oops. I misspoke. The tutorial isn't entirely incremental. It looks like the Watchify, Uglify, and Babel sections are each independent, which I guess is okay except:

1. The first half of the tutorial is incremental (simple example => add modules to the code => browserify). The docs don't specifically call out that the second half is not.
2. Since the tutorial has you replace the entire gulpfile.js every time, it's hard to tell what's changing, so it's hard to see that it's undoing things from previous sections.
3. The Babel section additionally removes greet.ts which is probably just a mistake?