{"id":20549555,"url":"https://github.com/akullpp/akgulp","last_synced_at":"2026-04-25T05:33:46.640Z","repository":{"id":79173918,"uuid":"45379972","full_name":"akullpp/akGulp","owner":"akullpp","description":"Conservative and basic Gulp module for enterprise Angular 1 projects.","archived":false,"fork":false,"pushed_at":"2017-10-17T09:09:35.000Z","size":497,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-01-16T16:42:54.059Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akullpp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2015-11-02T07:55:54.000Z","updated_at":"2023-09-16T21:22:16.000Z","dependencies_parsed_at":"2023-05-18T16:45:54.309Z","dependency_job_id":null,"html_url":"https://github.com/akullpp/akGulp","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akullpp%2FakGulp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akullpp%2FakGulp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akullpp%2FakGulp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akullpp%2FakGulp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akullpp","download_url":"https://codeload.github.com/akullpp/akGulp/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242153833,"owners_count":20080568,"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-11-16T02:18:28.849Z","updated_at":"2026-04-25T05:33:41.618Z","avatar_url":"https://github.com/akullpp.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# akGulp\n\n## Deprecation Warning\n\nI recommend that you use the CLI tools of Vue, React or even Angular 2 and therefore I won't update this module anymore.\n\nRaise an issue or create a pull request if you want an update.\n\n## Description\n\nConservative and basic [Gulp](http://gulpjs.com/) module for enterprise Angular 1 projects.\n\n* [Motivation](#motivation)\n* [Stack](#stack)\n* [Integration](#integration)\n* [Tasks](#tasks)\n* [Development](#development)\n\n## Motivation\n\nWhy should you use this rather conservative module to power your Angular 1 build process?\n\nYou shouldn't in an ideal world were you could do everything as you please and move on to [webpack](https://webpack.github.io/) and so on. However in enterprise environments there are often restrictions (e.g. downloading binaries on your build server), other requirements (e.g. stability and documentation) or your colleagues are just not up to the churn.\n\nIf you look at other Gulp modules, you will find them often to be convoluted and to be showcases of what you could do if you push the limits.\n\nThis module aims to be different: Basic, conservative and documented.\n\n1. Basic: Only tasks which are necessary to produce a sensible distribution of the application are included.\n2. Conservative: The plugins are known to work and don't do any funky stuff like downloading binaries.\n3. Documented: Task have a concise documentation of what they do, how they should be used and what the requirements are. Further documentation can be found in the code.\n\nThis module is ideally customer-based, i.e. a customer agrees on a default stack for their common projects and the build tooling is adapted accordingly. Of course it could also be used as project-based module for one ore more Angular applications.\n\nI used my initials as prefix in order to emphasize the high probability for you to customize the module based on your customer/company/project. So change it to your customer/project prefix and do the necessary adaptions.\n\nA typical workflow for a fork would be to:\n\n1. Identify the infrastructural situation, what does it (dis-)allow? Adapt.\n2. Define the stack. Adapt.\n3. Fork it [as node module](#as-a-node-module) or integrate it [as a folder](#as-a-folder).\n\n## Stack\n\nThese are the assumptions about the stack if you just want to use the module out-of-the box.\n\n### General\n\n* [AngularJS 1.x](https://www.angularjs.org/)\n* [ECMAScript 5.1](http://www.ecma-international.org/ecma-262/5.1/)\n* [ESLint 3.x](http://eslint.org/)\n* [Gulp 3.x](http://gulpjs.com/)\n* [Less 2.x](http://lesscss.org/)\n* [node 6.x](https://nodejs.org/en/)\n* [npm 3.x](https://www.npmjs.com/)\n\n### Testing\n\n* [Karma 1.x](https://karma-runner.github.io/)\n* [Mocha 3.x](http://mochajs.org/)\n\nThe assumption and best practice is to do consumer-driven API- and E2E-tests in a separate project.\n\n### Dependencies\n\nIn alphabetical order.\n\n* [del](https://github.com/sindresorhus/del): Deleting the build folder as a task\n* [diff](https://github.com/kpdecker/jsdiff): Providing deep object diffs for the test reporter\n* [gulp](http://gulpjs.com/): That's the point of this module\n* [gulp-angular-filesort](https://github.com/klei/gulp-angular-filesort): Sort-order of scripts for Angular's DI\n* [gulp-autoprefixer](https://github.com/sindresorhus/gulp-autoprefixer): Automatic vendor prefixing of CSS rules\n* [gulp-concat](https://github.com/contra/gulp-concat): Concatenating partials\n* [gulp-csso](https://github.com/ben-eb/gulp-csso): Optimizing CSS\n* [gulp-eslint](https://github.com/adametry/gulp-eslint): Linting JS\n* [gulp-filter](https://github.com/sindresorhus/gulp-filter): Filtering filestreams\n* [gulp-flatten](https://github.com/armed/gulp-flatten): Flattening long paths\n* [gulp-htmlmin](https://github.com/jonschlinkert/gulp-htmlmin): Minification of HTML\n* [gulp-if](https://github.com/robrich/gulp-if): Conditionally run tasks\n* [gulp-inject](https://github.com/klei/gulp-inject): Injecting assets into HTML\n* [gulp-less](https://github.com/plus3network/gulp-less): CSS preprocessing\n* [gulp-load-plugins](https://github.com/jackfranklin/gulp-load-plugins): Loading all gulp-prefixed plugins\n* [gulp-ng-annotate](https://github.com/Kagami/gulp-ng-annotate): Annotating functions for Angular's DI\n* [gulp-ng-html2js](https://github.com/marklagendijk/gulp-ng-html2js): Scriptifying HTML files and putting them into the $templateCache\n* [gulp-plumber](https://github.com/floatdrop/gulp-plumber): Error handling without breaking pipes\n* [gulp-replace](https://github.com/lazd/gulp-replace): Replacing strings in HTMLs\n* [gulp-rev](https://github.com/sindresorhus/gulp-rev): Revisioning assets\n* [gulp-rev-replace](https://github.com/jamesknelson/gulp-rev-replace): Replacing references of assets with their revisioned form\n* [gulp-size](https://github.com/sindresorhus/gulp-size): Reporting the size of files in streams\n* [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps): Creating sourcemaps for minified scripts\n* [gulp-uglify](https://github.com/terinjokes/gulp-uglify): Minification of JS\n* [gulp-useref](https://github.com/jonkemp/gulp-useref): Parsing build blocks in HTML to replace references\n* [gulp-util](https://github.com/gulpjs/gulp-util): Logging\n* [gulp-webserver](https://github.com/schickling/gulp-webserver): Serving files for development\n* [karma](http://karma-runner.github.io/): Testrunner\n* [karma-background](https://github.com/callmehiphop/karma-background): Runs karma as separate server in the background\n* [karma-chrome-launcher](https://github.com/karma-runner/karma-chrome-launcher): Chrome as test browser\n* [karma-coverage](https://github.com/karma-runner/karma-coverage): Generating reports for Sonar\n* [karma-firefox-launcher](https://github.com/karma-runner/karma-firefox-launcher): Firefox as test browser\n* [karma-ie-launcher](https://github.com/karma-runner/karma-ie-launcher): IE as test browser\n* [karma-junit-reporter](https://github.com/karma-runner/karma-junit-reporter): Generating test reports for Jenkins to understand\n* [karma-mocha](https://github.com/karma-runner/karma-mocha): Adapter for Karma and Mocha to work together\n* [karma-mocha-reporter](https://github.com/litixsoft/karma-mocha-reporter): Reporter for tests\n* [karma-ng-html2js-preprocessor](https://github.com/karma-runner/karma-ng-html2js-preprocessor): Same as gulp-ng-html2js but for karma tests\n* [lodash](https://lodash.com/): The missing stdlib\n* [mocha](https://mochajs.org/): Testing framework\n* [require-dir](https://github.com/aseemk/requireDir): Importing all tasks at once\n* [run-sequence](https://github.com/OverZealous/run-sequence): Sequentially running tasks\n* [uglify](https://github.com/mishoo/UglifyJS): Minifying JS\n* [uglify-save-license](https://github.com/shinnn/uglify-save-license): Saving the license during minification.\n* [yargs](https://github.com/yargs/yargs): Commandline-arguments for skipping tests during build\n\n#### Why I didn't you use...\n\n* ... Sass instead of Less. Unfortunately, Less is more predominant in the enterprise world. Mainly, because of Bootstrap. I hope that this will change with Bootstrap 4.\n* ... Browsersync instead of gulp-webserver. At the time of writing this library somewhere down the dependency chain of browsersync (socket.io, engine.io, and so on) there was a hardcoded URL which basically meant timeouts with a enterprise firewall. It might be fixed now, so if there's good reason, I might re-evaluate it.\n* ... gulp-imagemin or another image optimization plugin. Downloads binaries for compression which is often prohibited.\n* ... PhantomJS as a test browser. The popular headless browser has many pecularities but nevertheless it is complicated to use it without downloading the binaries. There are workarounds, you will need to choose one if you want to use it.\n* Jasmine instead of Mocha. Mocha allows for your own assertion and mocking library, handles asynchronous tests better, allows to show deep diffs in reports and is more fluent for BDD.\n\n## Integration\n\n### As a node module\n\nThis has rather huge advantages and should be preferred to the integrated folder. There are three possibilities here:\n\n1. In the very unlikely case you didn't need to make any adaptions and never plan to make any (beside basic ones via pull requests) you could have installed it via `npm i -D akGulp` which isn't recommended.\n2. You've forked `akGulp` and now have an adapted version in own repository. In this case you will probably need to use the repository URL in the `devDependencies` of your `package.json`. This is not recommended since installations will take time, there will be no caching and no semver. Also you would probably need an SSH connection to the repository (and therefore the server) which is often an issue for the ops.\n3. You've forked it and have a private npm registry (e.g. [Nexus](https://books.sonatype.com/nexus-book/reference/npm.html) in which you've published your fork. Now you have everything: caching, security and semver. Good job.\n\n#### config.js\n\nHere you can overwrite the paths if your folder structure differs or specify additional and different options for the gulp plugins.\n\nThe only required entry is the `moduleName` which is used for the partials as Angular module name and is the same as the root module in your `app.js`:\n\n```js\nmodule.exports = {\n    moduleName: 'my'\n};\n```\n\nThe `paths` properties overwrite the properties in `path.js` and the `consts` properties overwrite the properties in `consts.js`.\n\n#### gulpfile.js\n\nYou can define you own tasks or overwrite existing ones but it must at least have the following:\n\n```js\n'use strict';\n\nvar akGulp = require('ak-gulp');\nvar gulp = require('gulp');\n\nvar config = require('./config');\nvar karma = require('./karma');\n\nconfig.karma = karma;\n\nakGulp(gulp, config);\n```\n\nTo overwrite or create a task you define it in this file on the gulp object before you pass it.\n\n#### karma.js\n\nThis is the configuration for Karma and is required to be a valid module that exports an object. There are two major differences between this custom karma configuration and the default `kamra.conf.js` you might know. Dependencies and browsers have to specified with a special syntax. Everything else is like the default Karma configuration.\n\n**Dependencies** which would normally just be the `files` property in Karma must be specified with the `deps` property since\n\n* `config.paths.tests`\n* `config.paths.app.scripts`\n* `config.paths.app.partials`\n\nare added automatically. Here's an example:\n\n```js\n'use strict';\n\nmodule.exports = {\n    deps: [\n        'node_modules/angular/angular.js',\n        'node_modules/angular-mocks/angular-mocks.js',\n        'test/setup.js'\n    ]\n};\n```\n\n**Browsers** which would normally just be an array of strings are separated into `production` for your CI and `development` for your local environment. Here an example:\n\n```js\nbrowsers: {\n    production: ['IE'],\n    development: ['Chrome']\n}\n```\n\nPossible values are `Chrome`, `Firefox` and `IE`.\n\n#### Structure\n\nThe default minimal folder structure of the project is:\n\n```\n    src/\n        app/\n            index.html\n        assets/\n            images/\n            fonts/\n            ...\n        styles/\n            main.less\n    test/\n        **/*.spec.js\n```\n\nHave a look at `paths.js` if you want to overwrite it.\n\n### As a folder\n\nThis is the preferred approach if you don't plan on heavily modularizing your applications.\n\nYou will need to structure your project according to the [previous section](#as-a-node-module) and make following adaptions.\n\n1. Clone this repository and move the `lib`-folder to your project folder and rename it to `gulp`.\n2. Reference the main file in your `gulpfile.js`: `var akGulp = require('./lib/index');`\n3. Add all `dependencies` from this module to the `package.json`'s `devDependencies` and remove duplicates.\n\nFor an example see [akSkeleton](https://github.com/akullpp/akSkeleton).\n\n## Tasks\n\nThis is a description of commonly used tasks during development. An extensive list and documentation can be found [at the respective website](http://akullpp.github.io/akGulp). The same documentation can also be generated by `npm run doc`.\n\n* `gulp` (defaults to `gulp dev`): Launches a server hosting and watching the development files. The server reacts on changes on the development files and automatically does script injection if a new file is found or runs the preprocessor, tests and linter on changes.\n\n* `gulp build`: After successfully running the tests it builds the distribution which produces following folder structure:\n\n    ```\n    build/\n        dist/\n            assets/\n                fonts/\n                images/\n                ...\n            scripts/\n                main-{rev}.js\n                main-{rev}.js.map\n                vendor-{rev}.js\n                vendor-{rev}.js.map\n            styles/\n                main-{rev}.css\n                vendor-{rev}.css\n            index.html\n            VERSION\n        reports/\n            coverage/\n                ...\n            unit.xml\n    ```\n\nThere's also the temporary folder which is used for development and intermediary files:\n\n```\n    build/\n        .tmp/\n            assets/\n                fonts/\n                images/\n                ...\n            styles/\n                main.css\n            index.html\n            partials.min.js\n```\n\n### Production flag\n\nThe production flag is a environment variable which name is defined in `consts.productionFlag` (default: `PRODUCTION`) that makes pipes break on lint and plugin errors. It also enables the usage of different test browsers.\n\n## Development\n\nLocal development is done with `npm link` in this projects folder and then linking it via `npm link ak-gulp` into the implementer's project folder.\n\n### Scripts\n\nThere are three npm scripts:\n\n1. `npm run clean`: Deletes `doc/`, `node_modules/` and `npm-debug.log`\n2. `npm run lint`: Lints `lib/` with ESlint\n3. `npm run doc`: Generates the documentation to `doc/`\n\n### Structure\n\n#### consts.js\n\nHere are several constants like plugin options or the production flag.\n\n#### index.js\n\nThis is the entry point of the module, everything gets set up here.\n\n#### paths.js\n\nThe default path structure as shown above. Also there is an array which allows to specify unhandled assets via negative glob.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakullpp%2Fakgulp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakullpp%2Fakgulp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakullpp%2Fakgulp/lists"}