A simple template for using NPM tasks to build and compile TypeScript, JavaScript, CSS, and image files. Based on Chris Ferdinandi's Build Tool Boilerplate More info on Chris' build filosophies.
Install
Quick Start
Each task has just one or two dependencies (except for image optimization), so I recommend deleting the ones you don't need before running npm install. Learn more in the documentation below.
- In bash/terminal/command line,
cdinto your project directory. - Run
npm install. - Run
npm run build. - Run
npm startto start local development
This is a template that you can use as a starting point for your projects.
Running Tasks · JavaScript · Sass => CSS · SVG Optimization · Image Optimization · Copy Files · Clean · Complete Build · Watch for Changes · Server
The template uses the npm run command to run tasks. These work on macOS, Linux, and Windows systems.
# Main Tasks
npm start # run a localhost server that reloads when files change]
npm run test # run tests
npm run ts # compile ts
npm run js # compile and minify
npm run css # compile and minify Sass into CSS
npm run svg # optimize SVGs with SVGO
npm run img # optimize image files
npm run copy # copy files from the src/copy directory as-is into /dist
npm run clean # delete the /dist directory
npm run build # run all tasks
npm run watch # watch for changes and rebuild
# Modular Tasks
npm run watch-ts # watch for changes to the /ts directory
npm run watch-js # watch for changes to the /js directory
npm run watch-css # watch for changes to the /css directory
npm run watch-svg # watch for changes to the /svg directory
npm run watch-img # watch for changes to the /img directory
npm run watch-copy # watch for changes to the /copy directory
npm run build-dirty # run a new build without deleting the /dist directory
npm run server-start # start a server without watching for changesuse npm run start to build the project and start a server that reloads when file changes are detected.
Before any minification and bundling is done, all .ts files are first compiled and moved to the ./compiledjs folder.
TypeScript files should be in the src/ts directory.
The template uses rollup.js with the terser plugin to parse, compile, and minify JavaScript files.
{
"devDependencies": {
"rollup": "^2.6.1",
"rollup-plugin-terser": "^7.0.2"
}
}In the rollup.config.js file, there's a configs object that you can use to control what rollup.js does.
// Configs
var configs = {
name: 'MyProject', // Global namespace to use for IIFEs [optional]
files: ['main.js', 'detects.js'], // The files to process
formats: ['iife', 'es'], // The formats to output - will be added as a suffix to the filename (ex. main.es.js)
default: 'iife', // Files with this format will not have a format suffix [optional]
pathIn: 'src/js', // The source directory for your JS files
pathOut: 'dist/js', // The directory to compile JS files into
minify: true, // If true, a minified version will also be created with the .min suffix
sourceMap: false // If true, sourcemaps are created for each processed file †
};A banner is automatically generated from your package.json data.
It includes the project name and version, a copyright notice with the current year and the package author name, the license type, and a link to the project repository.
If a configs.name property is included, that will be used. If not, the banner defaults to the name property in your package.json file.
// Banner
var banner = `/*! ${configs.name ? configs.name : pkg.name} v${pkg.version} | (c) ${new Date().getFullYear()} ${pkg.author.name} | ${pkg.license} License | ${pkg.repository.url} */`;To concatentate multiple files into one, use the ES modules import feature.
// myplugin.js
// This will compile into /dist/js/myplugin.js, and will include helpers.js, app.js, and event-listeners.js
import * as Helpers from './helpers.js';
import app from './app.js';
import './event-listeners.js';Note for FireFox users: ensure that 'Use Source Maps', and 'Show original sources' options are enabled in Developer Tools.
The template uses the Node implementation of dart-sass to parse .scss files into CSS.
{
"devDependencies": {
"sass": "^1.26.5"
}
}In the sass.js file, there's a configs object that you can use to control what dart-sass does.
// Configs
var configs = {
name: 'MyProject', // The name to use in the file banner
files: ['main.scss'], // The files to process
pathIn: 'src/scss', // The source directory for your Sass files
pathOut: 'dist/css', // The directory to compile CSS files into
indentType: 'tab', // The type of indenting to use ['tab'|'spaces']
indentWidth: 1, // How many tabs or spaces to indent
minify: true, // If true, a minified version will also be created with the .min suffix
sourceMap: false, // If true, sourcemaps are created for each processed file †
};A banner is automatically generated from your package.json data.
It includes the project name and version, a copyright notice with the current year and the package author name, the license type, and a link to the project repository.
If a configs.name property is included, that will be used. If not, the banner defaults to the name property in your package.json file.
// Banner
var banner = `/*! ${configs.name ? configs.name : pkg.name} v${pkg.version} | (c) ${new Date().getFullYear()} ${pkg.author.name} | ${pkg.license} License | ${pkg.repository.url} */`;Sass files should be in the src/scss directory. Use this task to run the build.
npm run cssNote for FireFox users: ensure that 'Use Source Maps', and 'Show original sources' options are enabled in Developer Tools.
The template uses svgo to remove the cruft that gets added to SVG files by many editors.
{
"devDependencies": {
"svgo": "^1.3.2"
}
}For accessibility reasons, the boilerplate disables the settings that remove the title element and viewBox attribute.
You can make additional command line configurations under the svg tasks in the scripts property of the package.json file.
svgo -f src/svg dist/svg -r --disable=removeViewBox,removeTitleSVGs should be in the src/svg directory. Use this task to run the build.
npm run svgThe template uses imagemin, with the MozJPEG, pngcrush, pngquant, and zopfli plugins.
(Yea, that's kind of lot, isn't it?)
{
"devDependencies": {
"imagemin-cli": "^6.0.0",
"imagemin-mozjpeg": "^8.0.0",
"imagemin-pngcrush": "^6.0.0",
"imagemin-pngquant": "^8.0.0",
"imagemin-zopfli": "^6.0.0"
}
}Image files should be in the src/img directory. Use this task to run the build.
npm run imgThe template uses recursive-fs to provide a cross-OS copying solution. This package is also used for the clean task, so only remove it if you're deleting both tasks.
{
"devDependencies": {
"recursive-fs": "^2.1.0"
}
}If you have files you want copied as-is, place them in the src/copy directory.
Use this task to run the build.
npm run copyThe template uses recursive-fs to provide a cross-OS recursive directory deleting solution. This package is also used for the copy task, so only remove it if you're deleting both tasks.
{
"devDependencies": {
"recursive-fs": "^2.1.0"
}
}You can delete the /dist directory before running a build to clean up any junk that might have ended up there. The build task runs this task before doing anything else.
npm run cleanYou can run all of your build tasks in a single command.
Use this task to run the build.
npm run buildIf you want to run your build without first deleting the /dist directory, run this task instead.
npm run build-dirtyRegardless of which task you use, be sure to delete any tasks you're not using from the build-dirty task under scripts in your package.json file first. The npm-run-all -p command is used to run all tasks in parallel (see below for more details).
# default build-dirty task
npm-run-all -p js css svg img copy- uglify all JS
- bundle all JS into a single file. Instead, it bundles based on the input files you assign in the rollup config. So it is more modular.
The template uses Chokidar CLI to watch for changes to the /src directory and run tasks in response.
{
"devDependencies": {
"chokidar-cli": "^2.1.0"
}
}Use this task to watch for changes and run a build. It will also run a fresh build when it starts.
npm run watchIf you only want to watch for changes to a specific directory in /src, you can use a task-specific watcher task.
npm run watch-js # watch for changes to the /js directory
npm run watch-css # watch for changes to the /css directory
npm run watch-svg # watch for changes to the /svg directory
npm run watch-img # watch for changes to the /img directory
npm run watch-copy # watch for changes to the /copy directoryThe template uses Browsersync to run a local server and automatically update it whenever your files change.
{
"devDependencies": {
"browser-sync": "^2.26.14"
}
}Use this task to watch for changes. It will also run the watch task, and automatically rebuild whenever a file in /src changes.
npm run serverIf you want to run the server without the watch task, run this task instead.
npm run server-startThe template uses npm-run-all to run tasks consistently across different operating systems, and in parallel.
{
"devDependencies": {
"npm-run-all": "^4.1.5"
}
}The npm-run-all package removes the need for Windows-specific tasks.
It also allows you to run tasks in parallel. By running all of the tasks in the build tasks at the same time, you dramatically reduce the build time. This is also what makes it possible to run a localhost server and watch for file changes in one task.
In other words, don't remove this dependency.
I have been working with Webpack until now and I was never quite pleased with the way webpack worked. Too much magic for my taste. I wanted something simple and lean. I found Chris Ferdinandi's Boilerplate project and it was exactly what I was looking for. I added TypeScript and a test-framework.