Builders

Most repetitive tasks are automated thanks to a bundler using Gulp.

Builder kit

BBC's builder mainly used for websites and web applications packed with features to assist and accelerate development as much as possible.

SCSS compilation with added postcss magic
JS compilation
Handlebars compilation
Vue compilation with HMR support
Image compression (jpg, png and svg)
Icon font generation from svgs
Webfont conversion from using .otf, .ttf and svg files
Browsersync enabled for development and provides in page style replacement when new compilations are run
Showpad version management & bundling

Getting started (development)

Project is provided with .nvmrc file to quickly set up the right node environment before anything is installed (check the nvm website for more information)

nvm use
npm install

Gulp commands will be accessible after all the packages are installed. To start developing run:

gulp serve

This will run all the tasks and open the project in a new browser window with browsersync enabled.

When ready to build for production, run:

gulp build

Both commands will compile everything and move the results to from the source paths to the destination paths, ready for upload

It's also possible to zip the root destination folder after the build complets on the one condition that all the destination paths point to a sub folder of that root destination path. To build and zip, run:

gulp buildZip

The zip will be created and put in what gulp considers the root of the project (the same folder as the gulp file)

Run showpad development

Development in Showpad requires some extra tools. To run these too, use the following command:

gulp serveShowpad

This will launch 2 tabs

Local development server using a combination of Browsersync and Vite
The proxy app in showpad.

Once both are ready, logs about showpad will be sent to the proxy app and showpad related functions will become available in the app on the local development server.

Deploy to showpad automatically

Since v3.1.0 of experience-app-cli it is possible to upload through terminal. There are two ways.

gulp showpadPush to push the already build package (with gulp buildShowpad) to Showpad
gulp uploadShowpad to upload to Showpad by first building and bundling a new package.

The updated version of the package should be visible in the apps portal of Showpad.

Project setup

This builder provides support for both BBC's web-app and website development (using Showpad and Wordpress). When ready to start, make sure to set the right environment your set in to develop in /dev-tools/config.js

const config = {
	...
	environment:  'showpad';  // showpad || wordpress || ...
	...
}

In case we start supporting other environments, pleas add the path definitions to the property that corresponds with the environment name in /dev-tools/config.js .

const config =  {
	...
	[environment]:  {
		paths:  {
			src:  { ... },
			dest: { ... }
		}
	}
	...
}

Browsersync settings

Browsersync wil host the html files by setting up a server on port 3000. Even though this is very fast and handy, this has some drawbacks like no support for PHP and it ignores apache settings in .htaccess files. To get around this, it is possible to set Browsersync in proxy mode. Browsersync will act as a proxy server and channel all calls to another domain or ip address. It won't server the files in the destination folder anymore, for this another service will need to be set up like a vhost with Mamp for example. 2 settings need to be edited in Config.js:

Set the mode of config.browsersync.mode to 'proxy'
Add the domain it needs to proxy to in config.browsersync.proxy.target

Example:

// before
const config = {
	...
	browsersync:  {
		mode:  'server',  // server || proxy
		port:  3000,
		proxy:  {
			target:  ''  // no http required
		}
	}
	...
}

// after
const config = {
	...
	browsersync:  {
		mode:  'proxy',  // server || proxy
		port:  3000,
		proxy:  {
			target:  'loc.your-special-domain.com'  // no http required
		}
	}
	...
}

Showpad project setup

The setup needs some extra files and uses slightly different commands to work.
Make sure dev-tools/environment-files/showpad/.showpadconfig.json and dev-tools/environment-files/showpad/src/manifest.json contain the necessary api keys and app info.

1. Prep the project

When that is provided, run the prep script.

gulp prepShowpad

This copies the files from dev-tools/environment-files/showpad/ to their required locations and builds the project a first time.

Then create the app on the showpad platform and upload the create package as a first version

When done, this will remove the environment-files folder to avoid conflicts during compilation.

2. Showpad app and proxy app setup

There are a few extra settings to set in dev-tools/config.mjs before Showpad development can start:

Provide the profile the experience-app-cli will use to authenticate with Showpad as documented here to authProfile. Make sure to provide a profile with the --profile parameter. Test with gulp showpadAuth to see if everything has been set up well.
Set the appKey using the channel id in Showpad. This can easily be retrieved from the url in the experience builder, make sure to have the experience app open in either edit mode or preview mode.
Set the proxyAppKey using the channel id in Showpad. This can easily be retrieved from the url in the experience builder, make sure to have the experience app open in either edit mode or preview mode. Make sure to use your personal proxy app by uploading it into a new channel in the experience builder. The app can be downloaded here.

const config = {
	...
	showpad:  {
		authProfile: '',
		appKey:  '',
		proxyAppKey:  '', 
		...
	}
	...
}

Other commands

Every task can be run separately to help with debugging.

gulp htmlProd
gulp htmlDev
gulp hbsProd
gulp hbsDev
gulp jsProd
gulp csslint
gulp scssProd
gulp scssDev
gulp iconsProd
gulp iconsDev
gulp fontsProd
gulp fontsDev
gulp imagesProd
gulp imagesDev
gulp showpadAuth
gulp showpadPush

Note that there is no jsDev task. This is because all js compilation is provided by Vite which provides the source files directly in the browser while developing. No javascript is put in the js destination folder during the development (gulp serve) process.

Not that the HBS task has no jsprod task. This is because HBS templates are compiled to javascript and are added to the javascript source folder. The js task will pick up the change in the javascript codebase (if imported) and compile it with the other javascript files.

Builder update

Make sure that everything works before pushing the updates to the repository!

When further developing the builder, it's allowed to commit in multiple steps. But make sure everything works before you commit. When you're ready with the change, commit one last time before you perform a version update with npm. Version updates with npm add tags to the repository history that make clear distinctions between what are incremental commits and which are considered full version commits.

Steps to increase the version:

Make sure everything is committed so the repository is considered 'clean' by npm
Run npm version [minor/patch] -m [git message] to update the version following the npm's semantic versioning.
Commit one more time with your preferred git client.

Node js & Npm upgrades

When updating the node.js requirement, make sure to keep .nvmrc and package.json up to date and in sync.

Run following commands (in order) before commiting to the repository

node -v > .nvmrc
npm run sync-package-nvm

Run the steps to increase the version and commit as a minor release to the repository!

To Do

Https support for browsersync & vite HMR (with toggle in config.mjs)

NVM (Node Version Manager)

Modern projects should come with a .nvmrc file, which contains the actual node version the project is supposed to run on. Before you start up your project in the terminal, run ‘nvm use’ to set the correct node version automatically. It may happen that the version still needs to be installed first. In that case run

nvm install [version]

Version numbers don’t need to be written in full. Patching can be ignored (minor updates too most of the time), it is ok to write

nvm install 18

And this will install the latest 18th version.

Then follow it up with npm install

npm install

Legacy

Older projects still use node scripts to run webpack and sass. The main commands to start with are

For development:

npm run watch

For Production builds:

npm run build

Without NVM

Legacy projects may not have package.lock files or any information about which node version to use. For this it is helpful to look at the version of a package like node-sass:

Check the node-sass version required by package.json
Go to npm and find out when that package was released
Go to wikipedia and find out what node version was released around that time
Use that version or older with NVM to test if the build works (chances are the installation needs to be redone, make sure to remove package.lock file as well)

To remove the hassle for other developers in the future, we advise to add the node version in an .nvmrc file and push both the version file and the package.lock file to the repository.

node -v > .nvmrc