Operations - Genx CLI

Genx CLI is a tool that simplifies and speeds up local development. Among other useful functions, it enables you to:

• scaffold Genesis applications from scratch based on existing seeds
• start local development server
• build artifacts for production
• execute unit and end-to-end tests and collect coverage data
• perform code linting

The genx command has several options available to create, configure or modify a project. These are the available parameters:

Command	Argument	Description
init	<app_Name>	create a new project
analyze	[folder]	analyse the production bundle
clean	[...paths]	delete specified paths (defaults to dist folder)
build	[folder]	build a production bundle
dev	[folder]	start a development server
run	<task> [module]	run monorepo task
serve	[folder]	start a static file server (defaults to dist folder)
test	[folder]	run tests
lint	[folder]	Lint TypesScript and style files
upgrade	[folder]	upgrade Foundation UI dependencies

How to use genx

There are two main ways to run the Genx CLI:

• standalone - outside of an existing project, such as when scaffolding a new project
• local - within an existing project, such as when executing builds within a project

Standalone

npx -y @genesislcap/genx@latest <command> [args]

For example, to scaffold a new project:

npx -y @genesislcap/genx@latest init myApp

This uses the latest available version of the CLI and creates a new application called myApp, using the default seed blank-app-seed.

Local

Once you have a project, you can add Genx CLI as a local dependency to your package.json:

"devDependencies": {
    ...
    "@genesislcap/genx": "...",
    ...
},

You can check for the latest available version by running npm info @genesislcap/genx at any point.

Once you have bootstrapped NPM dependencies, you can call the Genx CLI in the package.json scripts section in this way:

"scripts":{
    ...
    "build": "genx <command> [args]"
    ...
}

For example:

"scripts":{
    ...
    "build": "genx build -e ENABLE_SSO",
    "dev": "genx dev -e API_HOST,ENABLE_SSO"
    "serve": "genx serve",
    "test": "genx test"
    ...
}

Once this is in place, you can execute npm run build or npm run devto launch the Genx CLI installed in your project locally.

Init

The init command creates a new project in the selected directory. The basic structure of this command is:

npx -y @genesislcap/genx@latest init <app_Name>

The init command creates a new project called <app_Name>. When the command runs, the user is prompted to answer a set of questions to cover the basic configuration of the project.

This command can be used with the following parameters:

Parameter	Argument	Description
-s or --seed	<location>	provide a seed where the project will be created
--ref	[ref]	provide a branch, tag or commit for creating the project
-x or --skip-optional-prompts		omit the prompts and applies default values
--insecure	omit SSL certificate verification
--remote		remote seed only; any local seed is ignored
-l or --log-level	info or verbose	info (default) or verbose
-h or --help		display help information

--seed

To use the -s or --seed parameter to specify the local seed directory, a remote seed or one of the pre-defined seeds provided by genesis.

The pre-defined seeds available are:

• blank-app-seed: a seed with a basic structure of a genesis project
• positions-app-seed: a seed with a positions app created
• devtraining-seed: a seed with the starting dev training project
• servertraining-seed: a seed with the starting server training project
• webtraining-seed: a seed with the starting web training project

Here is an example of creating a new project named myApp based on the pre-defined positions-app-seed:

npx -y @genesislcap/genx@latest init myApp -s positions-app-seed

You can use a local seed, to do that follow the example below:

npx -y @genesislcap/genx@latest init myApp -s ./path/to/local-seed

Or you can use a custom remote seed for your app:

npx -y @genesislcap/genx@latest init myApp -s githubuser/repo

--ref

If you do not want to use the master branch, use the --ref parameter to specify the branch, tag or commit within the seed.

Here is an example of creating a new project named myApp based on positions-app-seed on the develop branch:

npx -y @genesislcap/genx@latest init myApp -s positions-app-seed --ref develop

--skip-optional-prompts

Use the -x or --skip-optional-prompts parameter to skip all the optional questions when creating a new project.

Here is an example of creating a new project named myApp skipping all questions.

npx -y @genesislcap/genx@latest init myApp -x

or

npx -y @genesislcap/genx@latest init myApp --skip-optional-prompts

caution

Creating a project using -x creates a project using only using the default configuration.

--insecure

Use the --insecure parameter to skip all the SSL certification validation when creating a new project.

Here is an example of creating a new project named myApp skipping the SSL certification validation.

npx -y @genesislcap/genx@latest init myApp --insecure

--remote

Use the --remote parameter to use a remote-only seed. It will ignore any local seed.

Here is an example of creating a new project named myApp with a seed called blank-app-seed. Any local blank-app-seed is ignored.

npx -y @genesislcap/genx@latest init myApp -s blank-app-seed --remote

--log-level

Use the log-level to choose between info (default) or verbose log level.

Here is an example of creating a new project named myApp changing the log level to verbose:

npx -y @genesislcap/genx@latest init myApp --log-level verbose

Analyze

The analyze command helps to optimise the size of the production bundle - it identifies the modules contributing to the overall filesize the most.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-b or --builder	<builder>	override default builder	genx analyze --builder <builder>
-n or --no-open		don't launch browser window (default: true)	genx analyze --no-open
-e or --env	<VAR1, VAR2>	set environment variables	genx build --env VAR1=VAL1,VAR2=VAL2
-h or --help		display information about the command	genx serve --help

Clean

The clean command clears out the dist folder as well as temporary TypeScript compilation files. You can customise the exact files and folders to delete.

This command is more useful locally in your project. To do that, simply add the following to the list of scripts in your package.json

package.json

"clean": "genx clean <Path>",

Below is an example of creating a clean script to clear the dist folder (containing previously built artifact) and the node_modules folder.

Client/package.json

"clean": "genx clean dist node_modules"

Now you can run npm run clear in the client folder.

Build

The build command produces a production bundle for deployment.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-b or --builder	<builder>	override default builder	genx build --builder <builder>
-e or --env	<VAR1, VAR2>	set environment variables	genx build --env VAR1=VAL1,VAR2=VAL2
-h or --help		display information about the command	genx serve --help

Dev

The dev command starts an incremental development build server. It will watch for source file changes on disk and refresh the application.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-b or --builder	<builder>	Override default builder	genx dev --builder <builder>
--https		Use HTTPS	genx dev --https
-n or --no-open		don't launch browser window (default: true)	genx dev --no-open
-e or --env	<VAR1, VAR2>	set environment variables	genx dev --env VAR1=VAL1,VAR2=VAL2
-h or --help		display information about the command	genx serve --help

Run

The run command provides a short cut for executing NPM tasks in a monorepo managed by Nx / Lerna.

npx -y @genesislcap/genx@latest run <task>

or locally:

genx run <task>

for example:

"scripts": {
  "dev:app1": "genx run dev app1-name"
}

Serve

The serve command enables you to preview a production bundle locally. It starts a static HTTP server in dist folder.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-p or --port	<port>	set a port number (override the package.json definition)	genx serve --port 6060
-h or --help		display information about the command	genx serve --help

If there is no -p defined, then it will use the port defined in the package.json.

Test

The test command executes unit and end-to-end tests. Node.js and browsers (Chrome, Firefox etc.) are supported as execution targets. Test coverage reports can be produced in a number of formats, such as LCOV.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-c or --coverage		produce coverage report	genx test --coverage
-w or --watch		watch files for changes	genx test --watch
-d or --debug		debug test execution	genx test --debug
--e2e		run e2e tests; defaults to unit test	genx test --e2e
-i or --interactive		run e2e tests in interactive UI mode	genx test --interactive
-b or --browser		execute unit test in a browser; defaults to Node.js	genx test --browser
-e or --env	<VAR1, VAR2>	set environment variables	genx test --env VAR1=VAL1,VAR2=VAL2
-h or --help			genx test --help

Lint

The lint command verifies compliance with ESLint/Prettier/Stylelint rules and formatting conventions. Default configurations are provided, which can be tailored for a specific project.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-l or --linter	<linter>	eslint / stylelint / all (default)	genx lint -l <linter>
-f or --fix		fix issues	genx lint --fix
-p or --profile		output profiling information	genx lint --profile
-b or --builder	<builder>	override default builder	genx lint --builder <builder>
-h or --help			genx lint -h

Upgrade

The upgrade command updates Foundation UI NPM module dependency versions, regardless of the range defined in your package.json. It can be plugged into CI jobs for automated upgrade workflows.

This command can be used with the following parameters:

Parameter	Argument	Description	Local signature
-r or --respect-version-ranges		update within package.json version ranges (defaults to latest otherwise)	genx upgrade --respect-version-ranges
-x or --exclude	<list>	comma-separated list of packages to exclude	genx upgrade --exclude tslib
-h or --help		display information about the command	genx upgrade --help