biotope-build

Build Package for biotope-boilerplate.

Features

• Typescript + Babel
• ES6 unglify
• SCSS
• Autoprefixer
• Icon Font
• SVG Sprite generation
• HBS for templating
• ESLint
• Dev Servers

Options & Settings

All biotope-build options can be set in local /projectConfig.js (<5.x /projectConfig.json)

See default config: https://github.com/biotope/biotope-build/blob/master/config.js

framework internals

global settings

{
   <String> src: src, //base folder for all the project files, defaults to 'src'
   <String> dev: dev, //temporary folder for all files that get created in the serve/build process, defaults to '.tmp'
   <String> dist: dist, //build folder for the finalized files when running a build process, defaults to 'dist'
   <String> node: node, //node_modules base folder, defaults to 'node_modules'
   <String> cwd: cwd, //process.cwd(), current working dir of node project ###TODO should maybe be private###
   <boolean> isWin: isWin, //checks the os and sets the variable to true if running on a windows system
   <boolean> debug: false, //toggle debbuging prompts from the tasks (static:hb, browserConfig, partialHelper), default is false
   <String> dataObject: 'data' //name of the global data object, which can be used in static handlebars templates via {{data.key}}
   <String> resources: '/resources', //resource folder inside the src folder, needed to run multiple tasks
   <String> components: '/components' //component folder corresponding to the resource folder
   <String> handlebarsHelper: '/js/handlebars.helper.js', //path to dynamic handlebar helpers relative to the resources folder
   <Object> tasks: {}, //see tasks
   <Object> externalResources: {} //see external resources
   <Object> bowerResources: {} //see bower resources
}

tasks settings

You can toggle certain task in biotope-build. Every Task can be configurated with a boolean.

This list shows the configurable tasks as well as a brief description about what they do.

{
	browserSupport: true, //creates an overview of the support browser from a *.json file
	cleanCss: true, //minify CSS files for build
	cssStats: true, //checks the maximum selectors in each css file, fails if there are more than 4096 (IE 9 issue)
	favicons: true, //creates and embeds the favicons as well as the mobile icons from an image, default image root is '/resources/'
	handlebars: true, //creates dynamic handlebar templates from hbs files, static page generation is handled in a seperate task
	iconfont: true, //creates the iconfont from svg images, default icon path is '/resources/icons'
	image: true, //compress images stores in '/resources/img'
	linting: true, //linting of js/ts/scss files
	sass: true, //disables the sass compiler, disabled if you use vanilla css
	uglify: true, //uglifies js files in the build
	webpack: true //compiles typescript and transpiles ES6 Code in *.ts files
}

externalResources

If you use external resources for the final build you can add those with this object. The module name references the module inside the node_modules folder. The file name needs to be relative to the module.

JS files then get copied to '.tmp/resources/js/vendor/', CSS files to '.tmp/resources/css/vendor/'. When using scss files, reference the node_modules folder directly from there.

{
	'moduleName': 'singleFile.ext',
	'otherModuleName': ['firstFile.ext', 'folder/secondFile.ext2'],
}

plugin defaults

autoprefixer

Autoprefixer uses the .browserlistrc file from your projects root, or otherwise default options Repo: https://github.com/postcss/autoprefixer#options

browserSupport

Set the file path to the corresponding *.json file to create a browser support overview.

browserSupport: {
	file: cwd + '/browserSupport.json'
},

checkDependencies

Check dependencies only uses default options. Repo: https://github.com/mgol/check-dependencies

cleanCss

Clean CSS uses default options with rebase set to false to prevent rewriting file paths. Repo: https://www.npmjs.com/package/gulp-clean-css Repo: https://github.com/jakubpawlowicz/clean-css

cleanCss: {
	rebase: false
},

cssStats

cssStats exits on error in order to break the build process. Repo: https://github.com/cssstats/gulp-cssstats

cssstats: {
	exit: true
},

connect

Set the port and the folders being watch for connect/livereload. Repo: https://github.com/avevlad/gulp-connect

connect: {
		port: 9000,
		globs: [
			dev + '/**/*.*',
			src + '/resources/js/**/*.js',
			src + '/resources/bower_components/**/*',
			src + '/_mock/**/*',
			src + '/_config/**/*',
			'!' + dev + '/_mock/**/*',
			'!' + dev + '/_config/**/*',
			'!' + dev + '/_assets/**/*',
			'!' + dev + '/resources/js/vendor/**/*.js',
			'!' + dev + '/resources/css/**/*.map',
			'!' + dev + '/resources/bower_components/**/*',
			'!' + dev + '/resources/js/handlebars.templates.js'
		]
	},

favicons

This creates all the favicons and a manifest.json from an image file. Repo: https://github.com/evilebottnawi/favicons

favicons: {
	appName: "gulp-frontend-boilerplate",
	background: "#020307",
	path: "favicons/",
	display: "standalone",
	orientation: "portrait",
	version: 1.0,
	logging: false,
	online: false,
	html: "htmlhead.favicons.html",
	pipeHTML: true,
	replace: true,
	icons: {
		appleStartup: false
	}
},

handlebars

Dynamic handlebar templates and partials get created and added to a namespace. Repo: https://github.com/lazd/gulp-handlebars

handlebars: {
	templateWrap: 'Handlebars.template(<%= contents %>)',
	partialWrap: 'Handlebars.registerPartial(<%= processPartialName(file.relative) %>, Handlebars.template(<%= contents %>));',
	namespace: 'ffglobal.configuration.data.tpl',
	noRedeclare: true
},

iconfont

Icon font settings are split into gulp-svgicons2svgfont settings and the path settings. Repo: https://github.com/nfroidure/gulp-svgicons2svgfont

iconfont: {
	fontName: 'Icons',
	prependUnicode: true,
	timestamp: Math.round(Date.now() / 1000),
	normalize: true
},

iconfontCss: [
	{
		fontName: 'Icons',
		path: src + '/resources/scss/fonts/iconfont/_icons.scss',
		targetPath: '../../../../.iconfont/_icons.scss',
		fontPath: '../fonts/icons/',
		cssClass: 'icon'
	}, {
		fontName: 'Icons',
		path: src + '/resources/scss/fonts/iconfont/_iconStyles.scss',
		targetPath: '../../../../.iconfont/_iconStyles.scss',
		fontPath: '../fonts/icons/',
		cssClass: 'icon'
	}
],

image

Minifiy the images inside "/resources/img". Repo: https://github.com/sindresorhus/gulp-imagemin

image: {
	verbose: true
},

lec

Force line-endings to 'LF' formatting to create unification across platform. Repo: https://github.com/iShafayet/gulp-line-ending-corrector

lec: {
	verbose: false,
	eolc: 'LF',
	encoding: 'utf8'
},

livereload

Specifies the port for using livereload. Runs with connect. See connect settings.

livereload: {
	port: 35729
},

modernizr

Runs modernizr tests and creates polyfills. Repo: https://github.com/doctyper/gulp-modernizr Options: https://github.com/Modernizr/customizr#config-file

modernizr: {
	options: [
		"setClasses",
		"addTest"
	],
	excludeTests: [
		'hidden'
	]
},

sass

Sass compiler based on node-sass (can be changed to dart-sass via projectConfig.js). Repo: https://github.com/dlmanning/gulp-sass Options: https://github.com/sass/node-sass#options

sass: {
	includePaths: [],
	compiler: null // default behaviour. utilizes `node-sass`
	compiler: require('sass') // overwrite to use `dart-sass` (`sass` package uses `dart-sass` by default nowadays)
},

sassLint

Linting of sass files. Default options. Rules need to be defined. Repo: https://github.com/sasstools/gulp-sass-lint

sassLint: {},

ugflify

Javascript uglification settings. Repo: https://github.com/terinjokes/gulp-uglify

uglify: {
	preserveComments: 'license',
	sourcemaps: false,
	folders: ['js', 'ts'],
	ignoreList: []
},

watch

Watch task uses polling on windows system, therefore the interval is increased to reduce cpu usage. Repo: https://github.com/floatdrop/gulp-watch

watch: {
	usePolling: isWin,
	interval: (isWin ? 250 : 100)
},

webpack

Add files to an ignoreList, set path relative to src path. Webpack settings are set via webpack.config.js Repo: https://github.com/webpack/webpack

webpack: {
	ignoreList: []
}

others

There are other tasks in use, but they can not be modified via a projectConfig.js file. If this is needed please open an issue or send a pull request.

Local development

1. Clone biotope-boilerplate repository
2. Install locally with npm
3. Clone biotope-build repository
4. Install dependencies in biotope-buid with npm
5. Run npm link in @biotope/build repo
6. Run npm link @biotope/build in biotope-boilerplate repo
7. Happy developing 👋

Undo local dev changes

1. Run npm unlink in @biotope/build repo
2. Run npm unlink @biotope/build in biotope-boilerplate repo
3. Run npm in biotope-boilerplate repo

Troubleshooting, Bugs & Issues

Knows issues

• Missing documentation (on the roadmap)
• Poor performance (on the roadmap)

If you encounter errors, please submit an issue.