Skip to main content
Version: Previous

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:

CommandArgumentDescription
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:

ParameterArgumentDescription
-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-promptsomit the prompts and applies default values
--insecureomit SSL certificate verification
--remoteremote seed only; any local seed is ignored
-l or --log-levelinfo or verboseinfo (default) or verbose
-h or --helpdisplay 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:

ParameterArgumentDescriptionLocal signature
-b or --builder<builder>override default buildergenx analyze --builder <builder>
-n or --no-opendon't launch browser window (default: true)genx analyze --no-open
-e or --env<VAR1, VAR2>set environment variablesgenx build --env VAR1=VAL1,VAR2=VAL2
-h or --helpdisplay information about the commandgenx 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:

ParameterArgumentDescriptionLocal signature
-b or --builder<builder>override default buildergenx build --builder <builder>
-e or --env<VAR1, VAR2>set environment variablesgenx build --env VAR1=VAL1,VAR2=VAL2
-h or --helpdisplay information about the commandgenx 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:

ParameterArgumentDescriptionLocal signature
-b or --builder<builder>Override default buildergenx dev --builder <builder>
--httpsUse HTTPSgenx dev --https
-n or --no-opendon't launch browser window (default: true)genx dev --no-open
-e or --env<VAR1, VAR2>set environment variablesgenx dev --env VAR1=VAL1,VAR2=VAL2
-h or --helpdisplay information about the commandgenx 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:

ParameterArgumentDescriptionLocal signature
-p or --port<port>set a port number (override the package.json definition)genx serve --port 6060
-h or --helpdisplay information about the commandgenx 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:

ParameterArgumentDescriptionLocal signature
-c or --coverageproduce coverage reportgenx test --coverage
-w or --watchwatch files for changesgenx test --watch
-d or --debugdebug test executiongenx test --debug
--e2erun e2e tests; defaults to unit testgenx test --e2e
-i or --interactiverun e2e tests in interactive UI modegenx test --interactive
-b or --browserexecute unit test in a browser; defaults to Node.jsgenx test --browser
-e or --env<VAR1, VAR2>set environment variablesgenx test --env VAR1=VAL1,VAR2=VAL2
-h or --helpgenx 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:

ParameterArgumentDescriptionLocal signature
-l or --linter<linter>eslint / stylelint / all (default)genx lint -l <linter>
-f or --fixfix issuesgenx lint --fix
-p or --profileoutput profiling informationgenx lint --profile
-b or --builder<builder>override default buildergenx lint --builder <builder>
-h or --helpgenx 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:

ParameterArgumentDescriptionLocal signature
-r or --respect-version-rangesupdate within package.json version ranges (defaults to latest otherwise)genx upgrade --respect-version-ranges
-x or --exclude<list>comma-separated list of packages to excludegenx upgrade --exclude tslib
-h or --helpdisplay information about the commandgenx upgrade --help