Extending the Seed Project

This tutorial outlines ways that the Finsemble seed project's functionality can be extended.

Extending gulpfile

You can modify and extend the gulpfile's functionality by creating a gulpfile-extensions.js file at the same level as the gulpfile.js. This method avoids complications introduced from modifying the gulpfile directly and needing to merge upgrades into the updated gulpfile. The gulpfile-extensions.js file should define a function that takes in the object containing all of the methods called by the gulpfile, including pre and post methods that can be used to redefine variables and add additional tasks.

These are the methods defined in the taskMethods object:

• buildSass - Builds the SASS for the application.
• buildWebpack - Performs the webpack build for the application.
• clean - Cleans the project folder (deletes dist).
• copyStaticFiles - Copies static files to the dist folder.
• launchApplication - Launches the Finsemble application.
• post - Called after all of the tasks have been defined.
• pre - Called before all of the tasks have been defined.
• startServer - Starts the server based on NODE_ENV environment variable ("dev" or "prod").
• watchFiles - Watches files for changes to kick off buildSASS or buildWebpack.

These are the tasks defined in gulpfile.js:

• npm run dev - This is used most commonly while developing. Fast build, runs a local node-server, launches Finsemble.
• npm run dev:fresh - Same as npm run dev except that it cleans out any cached files. This is similar to a rebuild all.
• npm run build:dev - This is a fast build. Doesn't launch the server. Doesn't launch Finsemble.
• npm run dev:nolaunch - This is a fast build that runs the server. Doesn't launch Finsemble.
• npm run server:dev - This runs the server. Doesn't launch Finsemble. Doesn't build.
• npm run prod - Build for production. This is a full rebuild with minification. It will take a while. Then, this runs the server and launches Finsemble. This is the production equivalent of npm run dev. Use this to test production mode on your local machine.
• npm run build:prod - Build for production but don't run anything. Use this to create a production build for deployment.
• npm run prod:nolaunch - Build for production and run the node-server.
• npm run server:prod - This runs the server in production mode. Doesn't build. Doesn't launch Finsemble.

Extending server functionality

Sometimes during development, it is necessary to create new Web API (e.g., REST API) for your application to use. The Finsemble seed project already includes a server to host files locally for development, so it makes sense to use this server to design the new Web API. To allow for the extension of the server provided in the Finsemble seed project without breaking the upgrade path, the server attempts to import the server-extensions.js file from the server directory of the project. If server-extensions.js exists, it's methods are called by the server to provide additional functionality. The server-extensions.js file should return an object that contains the following functions:

• pre - Called before server.js starts defining the default server functionality
• post - Called after the server is up and running
• updateServer - Called after the default server functionality has been defined, but before the server is started

The pre and post functions do not take any arguments. The updateServer function takes two arguments: the first is an instance of the Express server that can be used to add functionality, and the second is a callback that takes no arguments, but must be called when the server is ready to be started. Please see the sample server-extensions.js below:

((module) => {
	"use strict";

	module.exports = {
		/**
		 * Method called before starting the server.
		 *
		 * @param done Function used to signal when pre function has finished. Can optionally pass an error message if
		 * one occurs.
		 */
		pre(done) {
			console.log("pre server startup");
			done();
		},

		/**
		 * Method called after the server has started.
		 *
		 * @param done Function used to signal when pre function has finished. Can optionally pass an error message if
		 * one occurs.
		 */
		post(done) {
			console.log("post server startup");
			done();
		},

		/**
		 * Method called to update the server.
		 *
		 * @param {express} app The express server.
		 * @param {function} cb The function to call once you're finished adding functionality to the server. Can optionally
		 * pass an error message if one occurs.
		 */
		updateServer(app, cb) {
			// Hosts the dist directory at the root of the server.
			app.use("/", express.static(path.join(__dirname, "dist"), options));

			cb();
		},
	};
})(module);

---

 

---

Further reading

If you extend the gulpfile, it's important to understand how the Build Process works.