This tutorial outlines ways that the Finsemble seed project's functionality can be extended.
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.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 functionalitypost
- Called after the server is up and runningupdateServer
- Called after the default server functionality has been defined, but before the server is startedThe 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);
If you extend the gulpfile, it's important to understand how the Build Process works.