doytsujin/finsemble-seed

If you are moving from an older version of the finsemble-seed project to the latest (2.3), please see the instructions here.

For everything you need to know about Finsemble, including a step-by-step process for setting up the seed project, check out the documentation on our website.

Finsemble Seed Project

This article lists the contents of the Finsemble seed project, how the seed project can be extended, and information about upgrading from the previous seed project structure.

• Project structure
• Extending gulpfile
• Extending server functionality

Project structure

The Finsemble seed project provides a basic structure to help developers get up and running as quickly as possible. The seed project provides the skeleton of a Finsemble application that can be extended to suit your organization's needs. It also includes some functionality to make development faster and easier, like a basic build process.

• gulpfile.js - The main gulpfile for the project which includes the basic tasks used to build and run a Finsemble application for development.
• gulpfile-extension.js (optional) - File that can be used to add/modify the functionality of the gulpfile. This file is included to prevent conflicts when upgrading your base project. See Extending Gulpfile for more information.
• build/webpack - Includes all of the files used by the seed project to build the application.
  • webpack.finsemble-built-in.entries.json - This specifies the entry and output files for the files built for a default Finsemble application.
  • webpack.components.entries.json - This file is where developer-added files should be listed. This file is empty in the base Finsemble seed project to prevent merge conflicts when updating the seed project.
  • webpack.adapters.entries.json - This file is for any storage adapters that need to be built. They are no longer housed in the same webpack configuration as components, as they cannot use the same plugins as components use.
• configs/application - This folder contains all of the base configuration for the Finsemble application. component.json, config.json and services.json are empty and developer-added configuration should go here. The files in this folder are merged together to build the application configuration. This configuration can be changed at run time using Dynamic Configuration.
• configs/openfin - Contains the OpenFin application config (also known as the application manifest) used to start up the Finsemble application. The default manifest for development is included, and additional configurations can be placed in this folder.
• configs/other/server-environment-startup.json - Used to define the development and production server configurations used by the Finsemble application.
• server - Contains the server that hosts the built dist folder for development purposes.
  • server/server-extensions.js - Optional file that can be used to add functionality to the development server. See (Extending Server Functionality)[#extending-server-functionality].
• src - The folder where your Finsemble components should be placed for the Finsemble build process.
• src-built-in - Includes the source for the default presentation components included with the Finsemble seed project. These files can be extended as desired, but, if you do extend these components, we recommend you copy the folder to the src directory to prevent merge conflicts when upgrading the seed project.
  • src-built-in/adapters - Contains an example Storage Adapter that saves data to local storage.
  • src-built-in/components/assets - Contains the SASS, CSS and images used to create Finsemble's look and feel.
• tutorials - Contains the source for the components used by our seed project tutorial.

Project structure:

FINSEMBLE-SEED
│   .gitignore
│   gulpfile-extensions.md
│   gulpfile.js
│   package.json
│   README.md
│
├───build
│   └───webpack
│           defaultWebpackConfig.js
│           webpack.finsemble-built-in.entries.json
│           webpack.components.entries.json
│           webpack.components.js
│           webpack.services.js
│
├───configs
│   ├───application
│   │   │   components.json
│   │   │   config.json
│   │   │   services.json
│   │   │
│   │   └───default
│   │           components.json
│   │           config.json
│   │           presentationComponents.json
│   │           workspaces.json
│   │           workspaceTemplates.json
│   │
│   ├───openfin
│   │       manifest-local.json
│   │
│   └───other
│           server-environment-startup.json
│
├───server
│   │   server.js
│   │
│   ├───dev
│   │       hotreload.js
│   │
│   └───hotreloadmiddleware
│           client-overlay.js
│           client.js
│           helpers.js
│           middleware.js
│           package.json
│           process-update.js
│           README.md
│
├───src
│   ├───adapters
│   │       .gitignore
│   │
│   ├───clients
│   │       .gitignore
│   │
│   ├───components
│   │       .gitignore
│   │
│   ├───services
│   │       .gitignore
│   │
│   └───thirdParty
│           .gitignore
│
├───src-built-in
│   ├───adapters
│   │       localStorageAdapter.js
│   │
│   └───components
│       │
│       ├───assets
│
└───tutorials

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 what you should use the most when developing. Fast build, runs a local node-server, launches Finsemble.
• npm run dev:fresh - Same as above except that it cleans out any cached files. This is like a rebuild all.
• npm run build:dev - Just fast build. No server, no launch.
• npm run dev:nolaunch - Fast build, run the server. Don't launch.
• npm run server:dev - Just run the server. No build. No launch.
• npm run prod - Build for production. This is a full rebuild with minification. It will take a while. Then run server and launch Finsemble. This is the prod 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 depoyment.
• npm run prod:nolaunch - Build for production and run the node-server.
• npm run server:prod - Just run the server in production mode. No build or launch.

If you wish to extend the build process (gulp) you can do so by adding a file gulpfile-extensions.js to the root of your seed (alongside gulpfile.js). An example is available in gulpfile-extensions-sample.js . Inside you will find complete instructions on how to modify gulp. See gulp task function for more information about gulp tasks.

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);