Module: cli-api
Finsemble CLI API reference
Use this API to customize your seed project build process. See the build process tutorial for complete documentation.
Usage:
In Node.js scripts, use require:
const { ruleCSS, launchFEA } = require("@finsemble/finsemble-core/cli-api");
In ts-node scripts, you can use import:
import { ruleCSS, launchFEA } from "@finsemble/finsemble-core/cli-api";
The CLI API is built in commonJS format so that it can be used in Node.js.
Type Aliases
FEAInstance
Ƭ FEAInstance: Object
Type declaration
| Name | Type |
|---|---|
onClose | (handler: (exitCode: null | number) => void) => void |
ServerTuple
Ƭ ServerTuple: Object
Type declaration
| Name | Type |
|---|---|
app | any |
server | http.Server |
StartInstance
Ƭ StartInstance: Object
Type declaration
| Name | Type |
|---|---|
feaInstance | FEAInstance |
serverTuple | ServerTuple |
onClose | (handler: (exitCode: null | number) => void) => void |
Functions
autoGenerateHtmlFiles
▸ autoGenerateHtmlFiles(webpackConfig): void
Adds plugins to the provided webpack configuration to generate index.html and menu.html files for each of the entries. The index.html file is needed for most apps and components. The menu.html file is needed for any app that uses drop down menus (such as the Toolbar). menu.html is ignored if the app does not require it.
Parameters
| Name | Type | Description |
|---|---|---|
webpackConfig | Configuration | A valid Webpack configuration |
Returns
void
build
▸ build(__namedParameters?): Promise<null | string>
Runs the CLI's build process and optionally starts Finsemble. This is the same as running yarn build or yarn build --start
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Command line arguments. This includes pass-through arguments that are accepted by getWebpackConfig() and start(). Plus --prepare and --start. |
__namedParameters.environment? | string | - |
__namedParameters.prepare? | boolean | Set to true to prepare for deployment. |
__namedParameters.resolveDependencyMagic? | boolean | - |
__namedParameters.start? | boolean | Set to true to launch Finsemble when done building. |
__namedParameters.webpackConfig? | string | Configuration | Optionally provide a webpack config or the location of a file that contains a webpack config, otherwise one will be generated using getWebpackConfig(). |
Returns
Promise<null | string>
- Resolves to an error if one occurs, otherwise resolves to null. If run in watch mode then the process will continue in the background. If run with the --start option, the webpack watch process terminates when Finsemble is closed.
clean
▸ clean(): void
Cleans the seed project, deleting all artifacts from prior builds. This function is synchronous and returns when all files have been removed.
Returns
void
createApp
▸ createApp(__namedParameters): Promise<null | string>
Creates an app. This behaves just like installTemplate except that it uses the "Blank" template and renames it to the name that was provided.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.name | null | string | The name of the app to create |
__namedParameters.output? | boolean | Set to false to suppress console.log output |
__namedParameters.projectFolder? | string | The project folder where to install. If not provided then the cwd will be assumed. |
Returns
Promise<null | string>
Resolves to an error string if an error occurs, otherwise to null
createPreload
▸ createPreload(__namedParameters): Promise<null | string>
Creates a preload. This behaves just like createApp except that it uses the "Preload" template instead of the "Blank" template.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.name | null | string | the name of the preload to create. |
__namedParameters.output? | boolean | set to false to suppress console.log output. |
__namedParameters.projectFolder? | string | the project folder where to install. If you don't provide it, Finsemble assumes the cwd. |
Returns
Promise<null | string>
- resolves to an error string if an error occurs, otherwise to null.
displayBuildEnvironmentDetails
▸ displayBuildEnvironmentDetails(): Promise<null | string>
Displays advanced build environment details such as software versions, drive space, OS, etc.
Returns
Promise<null | string>
a Promise which resolves to null
entriesToWebpackEntry
▸ entriesToWebpackEntry(entries): Object
Converts an array of Finsemble's simplified entry points (such as found in a seed project's webpack/entries.json file) into a format usable by Webpack. The output file is specified to be put in the correct place (no ./src) and with the correct extension (.js - generated automatically).
This returns a map of webpack entries and a map of CopyWebpackPlugin configs.
If an entry is already an object then it is passed back without any change other than extracting the optionally specified copyConfig.
Parameters
| Name | Type | Description |
|---|---|---|
entries | string[] | The entries to convert, from webpack/entries.json format |
Returns
Object
| Name | Type |
|---|---|
copyConfigs | Record<string, any> |
entries | Record<string, { filename: string ; import: string }> |
generateDefaultConfig
▸ generateDefaultConfig(__namedParameters): Configuration
Generates a baseline Finsemble compatible webpack configuration with the following behaviors:
- Empty webpack entries
- Caching turned on
- Source maps turned on unless mode is "production"
- Minimal output stats
- All rules enabled
- Resolving typescript, javascript, and css files
- CaseSensitivePaths plugin & EnvironmentPlugin that captures "NODE_ENV"
The returned config can be modified as necessary, including adding entries or overriding plugins.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.dirname | string | Should be __dirname of the calling function. This is used to determine location of webpack cache and output |
__namedParameters.mode? | "none" | "development" | "production" | - |
__namedParameters.name? | string | - |
__namedParameters.tsxOptions? | null | Record<string, any> | - |
Returns
Configuration
A webpack configuration is returned. This can be passed to a webpack process.
getLaunchConfig
▸ getLaunchConfig(__namedParameters?): Record<string, any>
Returns a launch config for the requested environment. This looks in the legacy server-environment-startup.json file before it looks in the standard project.json file, applying environment overrides using json-merge-patch. If no config is found then a default config is returned.
Parameters
| Name | Type |
|---|---|
__namedParameters | Object |
__namedParameters.environment? | string |
Returns
Record<string, any>
Resolves the launch config or null if it doesn't exist and useDefaults was set to false
getWebpackConfig
▸ getWebpackConfig(__namedParameters?): Configuration
Returns a complete webpack configuration that can be used to build Finsemble UI components.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Optionally pass command line arguments, supporting each parameter as --parameter |
__namedParameters.autoGenerateHtml? | boolean | index.html and menu.html files will be generated for each entry unless this is set to false. |
__namedParameters.consoleOutput? | boolean | If set to false then console output, feedback and warnings, will be prevented. |
__namedParameters.copyWebpackPlugin? | boolean | By default, any non build related files such as .html, .css, etc will be copied from the source to the output. Set this field to false to prevent that behavior. |
__namedParameters.entries? | string[] | Optional array of entry points to compile. |
__namedParameters.entriesFile? | string | Optional location of a JSON file containing entry points |
__namedParameters.mode? | "none" | "development" | "production" | Webpack mode is set to "development" by default. Optionally set this to "production" for production builds. |
__namedParameters.outputPath? | string | Optional output path for compiled entries. Defaults to the project's public/build directory |
__namedParameters.resolveDependencyMagic? | boolean | If set to false, dependencies will not be automatically resolved from @finsemble/finsemble-core's own dependencies. You will need to then add all dependencies to your package.json. |
__namedParameters.watch? | boolean | Watch mode is enabled by default. Set this to false to disable watch mode. |
__namedParameters.webpackConfig? | Configuration | Optionally provide a starting webpack config. Any field in this config will not be modified. CopyWebpackPlugins will not be generated for any entries in this object. |
Returns
Configuration
installTemplates
▸ installTemplates(__namedParameters): Promise<null | string>
Installs the requested UI component templates. For each template, a subdirectory will be created in the project's src folder containing the template and a webpack entry will be added to the webpack/entries.json file. Those folders and files will be created if they don't exist. Finally, a component entry will be added to the project's public/configs/application/config.json file to override the default values from core.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.output? | boolean | Set to false to suppress console.log output |
__namedParameters.projectFolder? | string | The project folder location. If not provided then it will assume the current working directory. |
__namedParameters.whichTemplates | string[] | A list of templates to install. Run npx finsemble templates for a full list. |
Returns
Promise<null | string>
Resolves to an error string if an error occurs, otherwise to null
launchFEA
▸ launchFEA(__namedParameters?): Promise<FEAInstance>
Use start() to launch the dev server and Finsemble with a single command.
Launches Finsemble (the Finsemble Electron Adapter (FEA)) using e2oLauncher (in the @finsemble/finsemble-electron-adapter module).
If an entry exists in project.json for either the requested or default
environment then the parameters from that entry are used to determine the server port and manifest
location, otherwise the port will default to 3375 and the manifest location will be public/configs/application/manifest-local.json.
launchFEA() resolves when Finsemble is launched. The resolved promise will be an object with an onClose handler which can be used to determine when Finsemble exits.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Optional array of command line arguments. --smartDesktopMode to launch the SDD. |
__namedParameters.environment? | string | Specify which environment to use. Defaults to "development". |
Returns
Resolves to an FEAInstance which contains an onClose function. Use this function to register a callback for
when Finsemble closes.
Example
const feaInstance = await launchFEA({ environment: "production" });
feaInstance.onClose((exitCode) => {
console.log(`Electron closed with code ${exitCode}`);
});
launchGlue
▸ launchGlue(__namedParameters?): Promise<FEAInstance>
Launches Glue Enterprise. This is equivalent to launchFEA for launching Finsemble.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Unused. |
__namedParameters.environment? | string | Unused. |
__namedParameters.verbose? | boolean | - |
Returns
Resolves to an FEAInstance which contains an onClose function. Use this function to register a callback for
when Finsemble closes.
makeInstaller
▸ makeInstaller(__namedParameters?): Promise<null | string>
Makes an installer from the seed project. See Deploying your smart desktop.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.configPath? | string | Optional path to a config file to be used for installer configuration (overrides default of project.json). |
__namedParameters.environment? | string | Specify which environment to use. Defaults to "development". |
__namedParameters.output? | boolean | - |
Returns
Promise<null | string>
Resolves to null when the installer has been created, or to an error string if there is an error.
migrate
▸ migrate(): Promise<void>
Migrates a seed project to 8.0 format.
Returns
Promise<void>
migrateTo8_3
▸ migrateTo8_3(): Promise<null | string>
Migrate seed config from 8.0-8.2 to 8.3. Must be called from the root directory of the seed repo.
Returns
Promise<null | string>
Resolves to an error string if an error occurs, otherwise to null
migrateToAppD2
▸ migrateToAppD2(__namedParameters): Promise<null | string>
Migrate a config file's FDC3 1.2 finsemble.appd config to FDC2 2.0 finsemble.apps config. The file is modified in place after a copy is made.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.filePath | null | string | The path to the config file to migrate. |
Returns
Promise<null | string>
Resolves to an error string if an error occurs, otherwise to null
preparePlatform
▸ preparePlatform(): void
Prepares a project for deployment by copying @finsemble/finsemble-core/platform into
the seed project's public/build/finsemble directory. This step makes the platform
available when you deploy your project to a server.
It is assumed that the current working directory is the root of the seed project.
Returns
void
ruleCSS
▸ ruleCSS(mode?): RuleSetRule
This returns a rule that will compile all imported CSS files into local <style> tags which are inlined into .js files.
When in development, sourceMap may cause style-loader to convert to <link> tags. This seems to vary from
version to version of style-loader.
Parameters
| Name | Type |
|---|---|
mode? | "none" | "development" | "production" |
Returns
RuleSetRule
ruleImageAndFont
▸ ruleImageAndFont(): RuleSetRule
Returns a rule that will inline all images, svg and font files into base64 local entries. There is no size limit on these files. Small size limits would prevent custom fonts from being displayed in Toolbar menu drop downs.
Returns
RuleSetRule
ruleLazyCSS
▸ ruleLazyCSS(mode?): RuleSetRule
Returns a rule that lazily loads files with the suffice .lazy.css.
WindowTitleBar requires lazy style loading when it is injected because it is preloaded before the DOM exists
and so there is no place for style-loader to put the styles.
Parameters
| Name | Type |
|---|---|
mode? | "none" | "development" | "production" |
Returns
RuleSetRule
ruleSVG
▸ ruleSVG(): RuleSetRule
Returns a rule allows React components to import SVG files and inline them into the DOM.
The "issuer" setting restricts this to run only in .j/tsx files, allowing svg @import in .css files to be supported via the default IMAGE_AND_FONT_RULE. Ideally, our code would always use SVG's from CSS rather than inlining them with React but the latter approach is heavily used in SDD and would require significant refactoring.
url-loader is used so that the images are inlined (as opposed to file-loader which requires very tricky dynamic public_path code).
Returns
RuleSetRule
ruleSourceMaps
▸ ruleSourceMaps(): RuleSetRule
Returns a rule allows webpack to transfer source maps from imported libraries, combining them into the source map for the actual file that it is bundling. This gives developers the ability to debug all the way down into imports from node_modules.
Returns
RuleSetRule
ruleTSX
▸ ruleTSX(options?): RuleSetRule
Returns a rule that will compile all .ts and .tsx files. ts-loader uses tsc. Modify the .tsconfig file to change typescript compilation behavior.
Parameters
| Name | Type |
|---|---|
options? | null | Record<string, any> |
Returns
RuleSetRule
runWebpack
▸ runWebpack(config, output?): StandardPromise<Compiler>
Runs webpack for a given configuration. This function will resolve to null after a successful compilation cycle or a string if an error occurs. When run in watch mode, it will resolve once and only once - either to null or an error - but only on the first compilation cycle. Additional compilation cycles will continue running in the background.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
config | Configuration | undefined | Must be a valid webpack configuration. Use getWebpackConfig() to obtain a default configuration. |
output | boolean | true | Set to false to suppress console.log output |
Returns
StandardPromise<Compiler>
Resolves to a tuple. The first argument contains an error string if an error occurs, otherwise to null. The second argument contains the webpack Compiler instance.
sdd
▸ sdd(__namedParameters?): Promise<undefined | FEAInstance>
Launches Finsemble in Smart Desktop Designer mode.
This will install a copy of Finsemble's platform and then use the current working directory as a project template. Both are installed in @finsemble/finsemble-electron-adapter/deploy.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Optional array of command line arguments to pass to FEA. |
__namedParameters.consoleOutput? | boolean | Set to false to suppress console output. |
__namedParameters.environment? | string | Specify which environment to use. Defaults to "development". |
Returns
Promise<undefined | FEAInstance>
Resolves to an FEAInstance which contains an onClose function. Use this function to register a callback for
when Finsemble closes.
Example
const feaInstance = await sdd();
feaInstance.onClose((exitCode) => {
console.log(`Electron closed with code ${exitCode}`);
});
showWebpackConfig
▸ showWebpackConfig(__namedParameters?): void
Outputs a generated webpack config to stdout. This takes the same parameters as build().
Parameters
| Name | Type |
|---|---|
__namedParameters | Object |
__namedParameters.args? | string[] |
Returns
void
start
▸ start(__namedParameters?): Promise<StartInstance>
Starts Finsemble.
This function follows these steps:
1) Installs the platform. See preparePlatform()
2) Starts FEA's built-in Express dev server. See startFEAServer()
3) Launches FEA. See launchFEA()
This function resolves when the server is started and FEA is launched. When FEA exits, the server will be stopped automatically. The promise resolution contains an object with an onClose handler that can be used to determine when FEA exits.
Example
const instance = await start({ environment: "production" });
instance.onClose((exitCode) => {
console.log(`Electron closed with code ${exitCode}`);
});
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Optional array of command line arguments. --smartDesktopMode to launch the SDD. --prepare=false to prevent prepare phase (copying public/build/finsemble). --glue to launch the Glue Enterprise container instead of FEA. --verbose to for verbose console output (from Glue Enterprise) |
__namedParameters.consoleOutput? | boolean | Set to false to suppress console output. |
__namedParameters.environment? | string | - |
__namedParameters.verbose? | boolean | - |
Returns
Resolves to an object that contains a a ServerTuple (see startFEAServer()) and a FEAInstance (see launchFEA)
startFEAServer
▸ startFEAServer(__namedParameters?): Promise<ServerTuple>
Use start() to launch the dev server and Finsemble with a single command.
Runs the Finsemble Electron Adapter's built in Express dev server. This function is typically run before running launchFEA().
Resolves with a tuple containing an instance of the Express server and an instance of the underlying Node.js http.server. These can be used to listen to events.
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | Object | - |
__namedParameters.args? | string[] | Optional array of command line arguments. --smartDesktopMode to launch the SDD. |
__namedParameters.consoleOutput? | boolean | Set to false to suppress console output. |
__namedParameters.environment? | string | Specify which environment to use. Defaults to "development". |
Returns
Resolves to a tuple that contains an instance of the Express server and corresponding Node.js http.server.