@pxblue/cli

PX Blue CLI

This Command Line Interface is a utility for creating new PX Blue applications with automatic integration of themes, components, etc.

Prerequisites

In order to use this utility you must have the following installed:

• NodeJS 12+
• npm or yarn
• Git

Additional requirements for creating React Native projects:

• Cocoapods 1.8+ (for ios)
• Expo CLI - only if you want to scaffold your project with Expo

Usage

The PX Blue CLI can be utilized via npx without having to install any global packages (recommended):

npx -p @pxblue/cli pxb <command>

If you would prefer to have a global install of the CLI you may do so via:

$ yarn global add @pxblue/cli

or

$ npm install -g @pxblue/cli

NOTE: If you are using NPM v7, the CLI will not work via npx — you must install it globally. Check periodically to make sure you have the latest version.

Available Commands

command	description
pxb help	lists all available commands and descriptions
pxb version	displays the version of the currently installed CLI
pxb new <framework>	Creates a new skeleton project with PX Blue integration. You'll be prompted to give your project a name and select various options depending on your selected framework.

Available options

The following table list out some options for the pxb new command. All these options can be configured

Option	Description
--framework=<angular|react|ionic|react-native>	The framework in which the project will be generated.
--name=<name>	Project name
--cli=<rnc|expo>	(React Native projects only) which CLI to use to generate the project. We support rnc (React-Native Community CLI) or expo (Expo CLI)
--template=<blank|routing|authentication>	Template to use to start the project
--lint	(TypeScript projects only) Install and configure PX Blue lint package (omit or --lint=false to disable)
--prettier	Install and configure PX Blue prettier package (omit or --prettier=false to disable)
--language=<typescript|javascript>	(React & React Native Only) The language in which the project will be generated

Detailed Usage

To start a new project with PX Blue integration follow the steps below. We recommend using npx (instead of installing it globally) to run the CLI as it will ensure you are always using the most up-to-date version.

• npx -p @pxblue/cli pxb new
• Choose your desired framework from the list
  • Alternatively, you can pre-select a framework by running npx -p @pxblue/cli pxb new <framework>

    Note for Ionic: If you are creating an Ionic project and you are behind a proxy, ensure that you have set an environment variable for IONIC_HTTP_PROXY. Depending on your firewall settings, you may also need to temporarily add an environment variable for NODE_TLS_REJECT_UNAUTHORIZED=0 (remove this promptly after your project is created).

• You will be prompted to enter a name for your project. Make sure the name you select meets the requirements of the CLI for your chosen framework.
• For React Native projects, you'll be asked which CLI to use to scaffold your project. You can choose between the React Native Community CLI (recommended) or Expo (better for smaller demo or proof-of-concept projects).

  Note for Expo projects: If you are creating an Expo project and you are behind a proxy, you will need to ensure that you have environment variables set for HTTP_PROXY and HTTPS_PROXY. Depending on your firewall settings, you may also need to temporarily add an environment variable for NODE_TLS_REJECT_UNAUTHORIZED=0 (remove this promptly after your project is created).

• You will be prompted to choose a template from our list of angular, react, or react native templates (RNC CLI only) to scaffold your project:
  • Blank: a basic application with a simple placeholder homepage
  • Routing: integrates React Router with a simple drawer navigation and several placeholder routes
  • Authentication: integrates the react, angular, or react native auth-workflow login and registration screens plus everything from the routing template
• If you are creating a React or React Native project, you will be prompted to choose JavaScript or Typescript for your project language.
• You will be asked if you want to use the PX Blue Linting configuration and code formatting packages (recommended).
• The CLI will install all of the necessary dependencies for your project and integrate the PX Blue components, themes, and fonts. When complete, the CLI should present you instructions for running your project.

  Note for React Native projects: If you are using the React Native Community CLI for your react native project, there are additional steps you must run for your project to run on iOS. Follow the on-screen instructions for running pod install to link the react-native-vector-icons package. If you are using xCode 11+, you will also need to update the Build Phases in xCode to avoid duplicated resources errors (refer to this issue).

Testing / Debugging Templates (For Maintainers)

You should always use the latest version of the templates when starting a new project to make sure you have the latest features and bug fixes.

If you are a library maintainer and you need to test out different versions of the templates during development, there are several ways to do this:

• Use --alpha or --beta flags on the command line. This will install the latest alpha or beta version of the template package from NPM, respectively.
• Use --template=templateName@x.x.x to specify a specific version of the template package to install from NPM.
• Use a local template file via --template=file:./path/to/folder. When using this syntax, the directory that you point to should contain all of the necessary files for a template. This is usually the "template name" folder (e.g., ./myTemplates/authentication, not ./myTemplates/authentication/template).
  • If you are working in a local copy of a PX Blue CLI templates repository, assuming that folder is in your current working directory, the paths would be:
    • --template=file:./angular-cli-templates/src/app/<name>
    • --template=file:./react-cli-templates/<name>
    • --template=file:./react-native-cli-templates/<name>