{"id":13697521,"url":"https://github.com/cferdinandi/build-tool-boilerplate","last_synced_at":"2025-04-05T08:05:34.139Z","repository":{"id":37673683,"uuid":"258334478","full_name":"cferdinandi/build-tool-boilerplate","owner":"cferdinandi","description":"A simple boilerplate for using NPM tasks to build and compile JavaScript, CSS, and image files.","archived":false,"fork":false,"pushed_at":"2023-04-27T15:37:21.000Z","size":683,"stargazers_count":496,"open_issues_count":23,"forks_count":62,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-29T07:04:43.608Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cferdinandi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-23T21:25:55.000Z","updated_at":"2025-03-06T20:22:47.000Z","dependencies_parsed_at":"2025-02-23T18:13:43.961Z","dependency_job_id":"f2131787-2d54-45cd-9189-1c050a69510d","html_url":"https://github.com/cferdinandi/build-tool-boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbuild-tool-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbuild-tool-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbuild-tool-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbuild-tool-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cferdinandi","download_url":"https://codeload.github.com/cferdinandi/build-tool-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305933,"owners_count":20917208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T18:00:59.684Z","updated_at":"2025-04-05T08:05:34.119Z","avatar_url":"https://github.com/cferdinandi.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Build Tool Boilerplate\nA simple boilerplate for using NPM tasks to build and compile JavaScript, CSS, and image files.\n\n_Version 2 adds `watch` and `server` tasks, and removes the need for Windows-specific tasks._\n\n**Install**\n\n- [Install Node.js.](http://nodejs.org/)\n- [Download the NPM Build Tool Boilerplate.](https://github.com/cferdinandi/build-tool-boilerplate/archive/master.zip)\n\n**Quick Start**\n\nEach 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](#documentation) below.\n\n1. In bash/terminal/command line, `cd` into your project directory.\n2. Run `npm install`.\n3. Run `npm run build`.\n\n\n\n## Documentation\n\nThis is a boilerplate that you can use as a starting point for your projects.\n\n[Running Tasks](#running-tasks) · [JavaScript](#javascript) · [Sass =\u003e CSS](#sass--css) · [SVG Optimization](#svg-optimization) · [Image Optimization](#image-optimization) · [Copy Files](#copy-files) · [Clean](#clean) · [Complete Build](#complete-build) · [Watch for Changes](#watch-for-changes) · [Server](#server)\n\n\n### Running Tasks\n\nThe boilerplate uses the `npm run` command to run tasks. These work on macOS, Linux, and Windows systems.\n\n```bash\n# Main Tasks\nnpm run js     # compile and minify\nnpm run css    # compile and minify Sass into CSS\nnpm run svg    # optimize SVGs with SVGO\nnpm run img    # optimize image files\nnpm run copy   # copy files from the src/copy directory as-is into /dist\nnpm run clean  # delete the /dist directory\nnpm run build  # run all tasks\nnpm run watch  # watch for changes and rebuild\nnpm run server # run a localhost server that reloads when files change\n\n# Modular Tasks\nnpm run watch-js     # watch for changes to the /js directory\nnpm run watch-css    # watch for changes to the /css directory\nnpm run watch-svg    # watch for changes to the /svg directory\nnpm run watch-img    # watch for changes to the /img directory\nnpm run watch-copy   # watch for changes to the /copy directory\nnpm run build-dirty  # run a new build without deleting the /dist directory\nnpm run server-start # start a server without watching for changes\n```\n\n\n### JavaScript\n\nThe boilerplate uses [rollup.js](https://rollupjs.org) with the [terser](https://terser.org/) plugin to parse, compile, and minify JavaScript files.\n\n```json\n{\n    \"devDependencies\": {\n        \"rollup\": \"^2.6.1\",\n        \"rollup-plugin-terser\": \"^7.0.2\"\n    }\n}\n```\n\nIn the `rollup.config.js` file, there's a `configs` object that you can use to control what rollup.js does.\n\n```js\n// Configs\nvar configs = {\n    name: 'MyProject',                // Global namespace to use for IIFEs [optional]\n    files: ['main.js', 'detects.js'], // The files to process\n    formats: ['iife', 'es'],          // The formats to output - will be added as a suffix to the filename (ex. main.es.js)\n    default: 'iife',                  // Files with this format will not have a format suffix [optional]\n    pathIn: 'src/js',                 // The source directory for your JS files\n    pathOut: 'dist/js',               // The directory to compile JS files into\n    minify: true,                     // If true, a minified version will also be created with the .min suffix\n    sourceMap: false                  // If true, sourcemaps are created for each processed file †\n};\n```\n\nA banner is automatically generated from your `package.json` data.\n\nIt 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.\n\n_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._\n\n```js\n// Banner\nvar banner = `/*! ${configs.name ? configs.name : pkg.name} v${pkg.version} | (c) ${new Date().getFullYear()} ${pkg.author.name} | ${pkg.license} License | ${pkg.repository.url} */`;\n```\n\nTo concatentate multiple files into one, use the ES modules `import` feature.\n\n```js\n// myplugin.js\n// This will compile into /dist/js/myplugin.js, and will include helpers.js, app.js, and event-listeners.js\n\nimport * as Helpers from './helpers.js';\nimport app from './app.js';\nimport './event-listeners.js';\n```\n\nJavaScript files should be in the `src/js` directory. Use this task to run the build.\n\n```bash\nnpm run js\n```\n\n_**Note for FireFox users:** ensure that ['Use Source Maps'](https://github.com/cferdinandi/build-tool-boilerplate/issues/7#issuecomment-811432626), and ['Show original sources'](https://github.com/cferdinandi/build-tool-boilerplate/issues/7#issuecomment-811855711) options are enabled in Developer Tools._\n\n### Sass =\u003e CSS\n\nThe boilerplate uses the Node implementation of [dart-sass](https://sass-lang.com/dart-sass) to parse `.scss` files into CSS.\n\n```json\n{\n    \"devDependencies\": {\n        \"sass\": \"^1.26.5\"\n    }\n}\n```\n\nIn the `sass.js` file, there's a `configs` object that you can use to control what `dart-sass` does.\n\n```js\n// Configs\nvar configs = {\n    name: 'MyProject',    // The name to use in the file banner\n    files: ['main.scss'], // The files to process\n    pathIn: 'src/scss',   // The source directory for your Sass files\n    pathOut: 'dist/css',  // The directory to compile CSS files into\n    indentType: 'tab',    // The type of indenting to use ['tab'|'spaces']\n    indentWidth: 1,       // How many tabs or spaces to indent\n    minify: true,         // If true, a minified version will also be created with the .min suffix\n    sourceMap: false,     // If true, sourcemaps are created for each processed file †\n};\n```\n\nA banner is automatically generated from your `package.json` data.\n\nIt 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.\n\n_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._\n\n```js\n// Banner\nvar banner = `/*! ${configs.name ? configs.name : pkg.name} v${pkg.version} | (c) ${new Date().getFullYear()} ${pkg.author.name} | ${pkg.license} License | ${pkg.repository.url} */`;\n```\n\nSass files should be in the `src/scss` directory. Use this task to run the build.\n\n```bash\nnpm run css\n```\n\n_**Note for FireFox users:** ensure that ['Use Source Maps'](https://github.com/cferdinandi/build-tool-boilerplate/issues/7#issuecomment-811432626), and ['Show original sources'](https://github.com/cferdinandi/build-tool-boilerplate/issues/7#issuecomment-811855711) options are enabled in Developer Tools._\n\n### SVG Optimization\n\nThe boilerplate uses [svgo](https://github.com/svg/svgo) to remove the cruft that gets added to SVG files by many editors.\n\n```json\n{\n    \"devDependencies\": {\n        \"svgo\": \"^1.3.2\"\n    }\n}\n```\n\nFor accessibility reasons, the boilerplate disables the settings that remove the `title` element and `viewBox` attribute.\n\nYou can make additional command line configurations under the `svg` tasks in the `scripts` property of the `package.json` file.\n\n```bash\nsvgo -f src/svg dist/svg -r --disable=removeViewBox,removeTitle\n```\n\nSVGs should be in the `src/svg` directory. Use this task to run the build.\n\n```bash\nnpm run svg\n```\n\n\n### Image Optimization\n\nThe boilerplate uses [imagemin](https://www.npmjs.com/package/imagemin), with the [MozJPEG](https://github.com/imagemin/imagemin-mozjpeg), [pngcrush](https://github.com/imagemin/imagemin-pngcrush), [pngquant](https://github.com/imagemin/imagemin-pngquant), and [zopfli](https://github.com/imagemin/imagemin-zopfli) plugins.\n\n(*Yea, that's kind of lot, isn't it?*)\n\n```json\n{\n    \"devDependencies\": {\n        \"imagemin-cli\": \"^6.0.0\",\n        \"imagemin-mozjpeg\": \"^8.0.0\",\n        \"imagemin-pngcrush\": \"^6.0.0\",\n        \"imagemin-pngquant\": \"^8.0.0\",\n        \"imagemin-zopfli\": \"^6.0.0\"\n    }\n}\n```\n\nImage files should be in the `src/img` directory. Use this task to run the build.\n\n```bash\nnpm run img\n```\n\n### Copy Files\n\nThe boilerplate uses [recursive-fs](https://github.com/simov/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.\n\n```json\n{\n    \"devDependencies\": {\n        \"recursive-fs\": \"^2.1.0\"\n    }\n}\n```\n\nIf you have files you want copied as-is, place them in the `src/copy` directory.\n\nUse this task to run the build.\n\n```bash\nnpm run copy\n```\n\n### Clean\n\nThe boilerplate uses [recursive-fs](https://www.npmjs.com/package/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.\n\n```json\n{\n    \"devDependencies\": {\n        \"recursive-fs\": \"^2.1.0\"\n    }\n}\n```\n\nYou 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.\n\n```bash\nnpm run clean\n```\n\n\n### Complete Build\n\nYou can run all of your build tasks in a single command.\n\nUse this task to run the build.\n\n```bash\nnpm run build\n```\n\nIf you want to run your build _without_ first deleting the `/dist` directory, run this task instead.\n\n```bash\nnpm run build-dirty\n```\n\nRegardless 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](#core-dependencies)).\n\n```bash\n# default build-dirty task\nnpm-run-all -p js css svg img copy\n```\n\n\n### Watch for Changes\n\nThe boilerplate uses [Chokidar CLI](https://www.npmjs.com/package/chokidar-cli) to watch for changes to the `/src` directory and run tasks in response.\n\n```json\n{\n    \"devDependencies\": {\n        \"chokidar-cli\": \"^2.1.0\"\n    }\n}\n```\n\nUse this task to watch for changes and run a build. It will also run a fresh build when it starts.\n\n```bash\nnpm run watch\n```\n\nIf you only want to watch for changes to a specific directory in `/src`, you can use a task-specific watcher task.\n\n```bash\nnpm run watch-js   # watch for changes to the /js directory\nnpm run watch-css  # watch for changes to the /css directory\nnpm run watch-svg  # watch for changes to the /svg directory\nnpm run watch-img  # watch for changes to the /img directory\nnpm run watch-copy # watch for changes to the /copy directory\n```\n\n\n## Server\n\nThe boilerplate uses [Browsersync](https://www.browsersync.io/) to run a local server and automatically update it whenever your files change.\n\n```json\n{\n    \"devDependencies\": {\n        \"browser-sync\": \"^2.26.14\"\n    }\n}\n```\n\nUse this task to watch for changes. It will also run the `watch` task, and automatically rebuild whenever a file in `/src` changes.\n\n```bash\nnpm run server\n```\n\nIf you want to run the server _without_ the `watch` task, run this task instead.\n\n```bash\nnpm run server-start\n```\n\n\n\n## Core Dependencies\n\nThe boilerplate uses [npm-run-all](https://www.npmjs.com/package/npm-run-all) to run tasks consistently across different operating systems, and in parallel.\n\n```json\n{\n    \"devDependencies\": {\n        \"npm-run-all\": \"^4.1.5\"\n    }\n}\n```\n\nThe `npm-run-all` package removes the need for Windows-specific tasks.\n\nIt 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.\n\n**In other words, don't remove this dependency.**\n\n\n\n## Why does this exist?\n\nFor years, I've been an avid [Gulp](https://gulpjs.com/) user. Gulp is great. But it's also *a lot*.\n\n**I wanted a simpler, more resilient, leaner set of build tools.**\n\nI'm tired of having to repair my build anytime I don't use it for a few months. I'm tired of installing 270mb of `node_modules` dependencies to build a simple website or web app.\n\nWith NPM, you can build a simplish build tool that does just what you want (*and nothing more*) with a fraction of the footprint.\n\n❤️ *Major kudos to Keith Cirkel for [teaching me about this years ago](https://www.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/), before I was ready to hear it.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcferdinandi%2Fbuild-tool-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcferdinandi%2Fbuild-tool-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcferdinandi%2Fbuild-tool-boilerplate/lists"}