This quick start guide will teach you how to build TypeScript with gulp and then add Browserify, uglify, or Watchify to the gulp pipeline.\nThis guide also shows how to add Babel functionality using Babelify.
\nWe assume that you’re already using Node.js with npm.
\nLet’s start out with a new directory.\nWe’ll name it proj for now, but you can change it to whatever you want.
\nshellmkdir proj\ncd proj
To start, we’re going to structure our project in the following way:
\nproj/\n ├─ src/\n └─ dist/\nTypeScript files will start out in your src folder, run through the TypeScript compiler and end up in dist.
Let’s scaffold this out:
\n\nshellmkdir src\nmkdir dist
Now we’ll turn this folder into an npm package.
\n\nshellnpm init
You’ll be given a series of prompts.\nYou can use the defaults except for your entry point.\nFor your entry point, use ./dist/main.js.\nYou can always go back and change these in the package.json file that’s been generated for you.
Now we can use npm install to install packages.\nFirst install gulp-cli globally (if you use a Unix system, you may need to prefix the npm install commands in this guide with sudo).
\nshellnpm install -g gulp-cli
Then install typescript, gulp and gulp-typescript in your project’s dev dependencies.\nGulp-typescript is a gulp plugin for Typescript.
\nshellnpm install --save-dev typescript gulp@4.0.0 gulp-typescript
Let’s write a Hello World program.\nIn src, create the file main.ts:
\ntsfunction hello(compiler: string) {\n console.log(`Hello from ${compiler}`);\n}\nhello('TypeScript');
In the project root, proj, create the file tsconfig.json:
\njson{\n \"files\": [\n \"src/main.ts\"\n ],\n \"compilerOptions\": {\n \"noImplicitAny\": true,\n \"target\": \"es5\"\n }\n}
gulpfile.jsIn the project root, create the file gulpfile.js:
\njsvar gulp = require('gulp');\nvar ts = require('gulp-typescript');\nvar tsProject = ts.createProject('tsconfig.json');\n\ngulp.task('default', function () {\n return tsProject.src()\n .pipe(tsProject())\n .js.pipe(gulp.dest('dist'));\n});
\nshellgulp\nnode dist/main.js
The program should print “Hello from TypeScript!“.
\nBefore we get to Browserify, let’s build our code out and add modules to the mix.\nThis is the structure you’re more likely to use for a real app.
\nCreate a file called src/greet.ts:
\ntsexport function sayHello(name: string) {\n return `Hello from ${name}`;\n}
Now change the code in src/main.ts to import sayHello from greet.ts:
\ntsimport { sayHello } from './greet';\n\nconsole.log(sayHello('TypeScript'));
Finally, add src/greet.ts to tsconfig.json:
\njson{\n \"files\": [\n \"src/main.ts\",\n \"src/greet.ts\"\n ],\n \"compilerOptions\": {\n \"noImplicitAny\": true,\n \"target\": \"es5\"\n }\n}
Make sure that the modules work by running gulp and then testing in Node:
\nshellgulp\nnode dist/main.js
Notice that even though we used ES2015 module syntax, TypeScript emitted CommonJS modules that Node uses.\nWe’ll stick with CommonJS for this tutorial, but you could set module in the options object to change this.
Now let’s move this project from Node to the browser.\nTo do this, we’d like to bundle all our modules into one JavaScript file.\nFortunately, that’s exactly what Browserify does.\nEven better, it lets us use the CommonJS module system used by Node, which is the default TypeScript emit.\nThat means our TypeScript and Node setup will transfer to the browser basically unchanged.
\nFirst, install browserify, tsify, and vinyl-source-stream.\ntsify is a Browserify plugin that, like gulp-typescript, gives access to the TypeScript compiler.\nvinyl-source-stream lets us adapt the file output of Browserify back into a format that gulp understands called vinyl.
\n\nshellnpm install --save-dev browserify tsify vinyl-source-stream
Create a file in src named index.html:
\nhtml<!DOCTYPE html>\n<html>\n <head>\n <meta charset=\"UTF-8\" />\n <title>Hello World!</title>\n </head>\n <body>\n <p id=\"greeting\">Loading ...</p>\n <script src=\"bundle.js\"></script>\n </body>\n</html>
Now change main.ts to update the page:
\ntsimport { sayHello } from './greet';\n\nfunction showHello(divName: string, name: string) {\n const elt = document.getElementById(divName);\n elt.innerText = sayHello(name);\n}\n\nshowHello('greeting', 'TypeScript');
Calling showHello calls sayHello to change the paragraph’s text.\nNow change your gulpfile to the following:
\njsvar gulp = require('gulp');\nvar browserify = require('browserify');\nvar source = require('vinyl-source-stream');\nvar tsify = require('tsify');\nvar paths = {\n pages: ['src/*.html']\n};\n\ngulp.task('copy-html', function () {\n return gulp.src(paths.pages)\n .pipe(gulp.dest('dist'));\n});\n\ngulp.task('default', gulp.series(gulp.parallel('copy-html'), function () {\n return browserify({\n basedir: '.',\n debug: true,\n entries: ['src/main.ts'],\n cache: {},\n packageCache: {}\n })\n .plugin(tsify)\n .bundle()\n .pipe(source('bundle.js'))\n .pipe(gulp.dest('dist'));\n}));
This adds the copy-html task and adds it as a dependency of default.\nThat means any time default is run, copy-html has to run first.\nWe’ve also changed default to call Browserify with the tsify plugin instead of gulp-typescript.\nConveniently, they both allow us to pass the same options object to the TypeScript compiler.
After calling bundle we use source (our alias for vinyl-source-stream) to name our output bundle bundle.js.
Test the page by running gulp and then opening dist/index.html in a browser.\nYou should see “Hello from TypeScript” on the page.
Notice that we specified debug: true to Browserify.\nThis causes tsify to emit source maps inside the bundled JavaScript file.\nSource maps let you debug your original TypeScript code in the browser instead of the bundled JavaScript.\nYou can test that source maps are working by opening the debugger for your browser and putting a breakpoint inside main.ts.\nWhen you refresh the page the breakpoint should pause the page and let you debug greet.ts.
Now that we are bundling our code with Browserify and tsify, we can add various features to our build with browserify plugins.
\nWe’ll start with Watchify to provide background compilation:
\n\nshellnpm install --save-dev watchify fancy-log
Now change your gulpfile to the following:
\n\njsvar gulp = require('gulp');\nvar browserify = require('browserify');\nvar source = require('vinyl-source-stream');\nvar watchify = require('watchify');\nvar tsify = require('tsify');\nvar fancy_log = require('fancy-log');\nvar paths = {\n pages: ['src/*.html']\n};\n\nvar watchedBrowserify = watchify(browserify({\n basedir: '.',\n debug: true,\n entries: ['src/main.ts'],\n cache: {},\n packageCache: {}\n}).plugin(tsify));\n\ngulp.task('copy-html', function () {\n return gulp.src(paths.pages)\n .pipe(gulp.dest('dist'));\n});\n\nfunction bundle() {\n return watchedBrowserify\n .bundle()\n .on('error', fancy_log)\n .pipe(source('bundle.js'))\n .pipe(gulp.dest('dist'));\n}\n\ngulp.task('default', gulp.series(gulp.parallel('copy-html'), bundle));\nwatchedBrowserify.on('update', bundle);\nwatchedBrowserify.on('log', fancy_log);
There are basically three changes here, but they require you to refactor your code a bit.
\nbrowserify instance in a call to watchify, and then held on to the result.watchedBrowserify.on('update', bundle); so that Browserify will run the bundle function every time one of your TypeScript files changes.watchedBrowserify.on('log', fancy_log); to log to the console.Together (1) and (2) mean that we have to move our call to browserify out of the default task.\nAnd we have to give the function for default a name since both Watchify and Gulp need to call it.\nAdding logging with (3) is optional but very useful for debugging your setup.
Now when you run Gulp, it should start and stay running.\nTry changing the code for showHello in main.ts and saving it.\nYou should see output that looks like this:
\nshellproj$ gulp\n[10:34:20] Using gulpfile ~/src/proj/gulpfile.js\n[10:34:20] Starting 'copy-html'...\n[10:34:20] Finished 'copy-html' after 26 ms\n[10:34:20] Starting 'default'...\n[10:34:21] 2824 bytes written (0.13 seconds)\n[10:34:21] Finished 'default' after 1.36 s\n[10:35:22] 2261 bytes written (0.02 seconds)\n[10:35:24] 2808 bytes written (0.05 seconds)
First install Uglify.\nSince the point of Uglify is to mangle your code, we also need to install vinyl-buffer and gulp-sourcemaps to keep sourcemaps working.
\n\nshellnpm install --save-dev gulp-uglify vinyl-buffer gulp-sourcemaps
Now change your gulpfile to the following:
\n\njsvar gulp = require('gulp');\nvar browserify = require('browserify');\nvar source = require('vinyl-source-stream');\nvar tsify = require('tsify');\nvar uglify = require('gulp-uglify');\nvar sourcemaps = require('gulp-sourcemaps');\nvar buffer = require('vinyl-buffer');\nvar paths = {\n pages: ['src/*.html']\n};\n\ngulp.task('copy-html', function () {\n return gulp.src(paths.pages)\n .pipe(gulp.dest('dist'));\n});\n\ngulp.task('default', gulp.series(gulp.parallel('copy-html'), function () {\n return browserify({\n basedir: '.',\n debug: true,\n entries: ['src/main.ts'],\n cache: {},\n packageCache: {}\n })\n .plugin(tsify)\n .bundle()\n .pipe(source('bundle.js'))\n .pipe(buffer())\n .pipe(sourcemaps.init({loadMaps: true}))\n .pipe(uglify())\n .pipe(sourcemaps.write('./'))\n .pipe(gulp.dest('dist'));\n}));
Notice that uglify itself has just one call — the calls to buffer and sourcemaps exist to make sure sourcemaps keep working.\nThese calls give us a separate sourcemap file instead of using inline sourcemaps like before.\nNow you can run Gulp and check that bundle.js does get minified into an unreadable mess:
\nshellgulp\ncat dist/bundle.js
First install Babelify and the Babel preset for ES2015.\nLike Uglify, Babelify mangles code, so we’ll need vinyl-buffer and gulp-sourcemaps.\nBy default Babelify will only process files with extensions of .js, .es, .es6 and .jsx so we need to add the .ts extension as an option to Babelify.
\nshellnpm install --save-dev babelify@8 babel-core babel-preset-es2015 vinyl-buffer gulp-sourcemaps
Now change your gulpfile to the following:
\n\njsvar gulp = require('gulp');\nvar browserify = require('browserify');\nvar source = require('vinyl-source-stream');\nvar tsify = require('tsify');\nvar sourcemaps = require('gulp-sourcemaps');\nvar buffer = require('vinyl-buffer');\nvar paths = {\n pages: ['src/*.html']\n};\n\ngulp.task('copy-html', function () {\n return gulp.src(paths.pages)\n .pipe(gulp.dest('dist'));\n});\n\ngulp.task('default', gulp.series(gulp.parallel('copy-html'), function () {\n return browserify({\n basedir: '.',\n debug: true,\n entries: ['src/main.ts'],\n cache: {},\n packageCache: {}\n })\n .plugin(tsify)\n .transform('babelify', {\n presets: ['es2015'],\n extensions: ['.ts']\n })\n .bundle()\n .pipe(source('bundle.js'))\n .pipe(buffer())\n .pipe(sourcemaps.init({loadMaps: true}))\n .pipe(sourcemaps.write('./'))\n .pipe(gulp.dest('dist'));\n}));
We also need to have TypeScript target ES2015.\nBabel will then produce ES5 from the ES2015 code that TypeScript emits.\nLet’s modify tsconfig.json:
\njson{\n \"files\": [\n \"src/main.ts\"\n ],\n \"compilerOptions\": {\n \"noImplicitAny\": true,\n \"target\": \"es2015\"\n }\n}
Babel’s ES5 output should be very similar to TypeScript’s output for such a simple script.
","headings":[{"value":"Minimal project","depth":1},{"value":"Initialize the project","depth":2},{"value":"Install our dependencies","depth":2},{"value":"Write a simple example","depth":2},{"value":"Create a gulpfile.js","depth":2},{"value":"Test the resulting app","depth":2},{"value":"Add modules to the code","depth":1},{"value":"Browserify","depth":1},{"value":"Create a page","depth":2},{"value":"Watchify, Babel, and Uglify","depth":1},{"value":"Watchify","depth":2},{"value":"Uglify","depth":2},{"value":"Babel","depth":2}],"frontmatter":{"permalink":"/docs/handbook/gulp.html","title":"Gulp"}}},"pageContext":{"slug":"/docs/handbook/gulp.html","isOldHandbook":true}}}