Initialize Resources

Initialize Resources

 

Introduction

The first step in working with the Catalyst CLI is initializing a Catalyst project in a directory in your local system and associating that directory with that project. You cannot perform any project-related operations in the CLI until you have initialized a Catalyst project.  

The directory that you initialize a project in is referred to as the project directory (CATALYST_PROJECT_HOME). The required configuration files for your project are created automatically when the project is initialized.

You can initialize the two basic components of a Catalyst project: Functions and Client. The directories of the components that you initialize are created automatically, along with required configuration files and dependencies. You can also pull a JSON file that contains the API definitions of API Gateway from the remote console, into your project directory.

For detailed information on the project directory structure and the code structures of the configuration files, refer to the Project Directory Structure help page.

Note: You can also pull a JSON file that contains the API definitions of API Gateway from the remote console, into your project directory. Refer to the Working with API Gateway help page to learn more.

After the initialization process is complete, this directory will be permanently bound to that project. Although you can use the directory to work with other projects using the catalyst project:use command, this association will only be temporary. The project that you originally initialize in a directory will be considered to be the base project of that directory.

Note:
  • You will not be able to initialize a project in a directory whose root is already bound to another project. This is because when a project is initialized in a directory, the CLI performs a check for Catalyst components beginning with the directory's root. If any components are found in the root, the CLI will not initialize a new project in it. 
  • The best way to initialize a new project is to create an individual folder for it in your local system, navigate to it, and execute the initialize command from that directory.
 

Initialize a New Project

You can initialize a project, and then the functions and the client as explained in these sections.

To initialize a new project from the CLI:

  1. Create a folder for the project on your local machine and navigate to it from the terminal. Initialize a project by executing the following command from that directory:
    $ catalyst init
  2. You can associate the current project directory with an existing Catalyst project. You can also create your own new project directly from the CLI or import an existing project.  
    • To select an existing Catalyst project, select from the list of your projects using the arrows. Press Enter to confirm.  
      Note: You can run the command catalyst project:use to associate an existing project, that has previously been initialized in the CLI, with the working directory.
    • To create a new project, navigate to the Create a new project option and press Enter. Enter a name for your new project and press Enter to confirm.
    • To import an existing project, you must select Import an existing project, then select the project source ZIP file. You can learn more about these steps from the Export and Import Project help page.
      Note:
      • You cannot create your first ever Catalyst project from the CLI. You can create the first project only using the Catalyst web console. You can create subsequent projects from the CLI.
      • You can create upto 50 projects in your account in the development environment. You can request Catalyst for an increase in this limit by contacting our support at support@zohocatalyst.com. We will address each request on a case-by-case basis. There are no upper limits for project creation in the production environment.
  3. Now, select the components that you need to set up for your Catalyst application by pressing Space to select the features. Press Enter to confirm your choices.
    You can initialize both Functions and Client, or any one of them.
    Note:
    • You can also initialize a project without selecting any components. Since the main purpose of a project initialization is to bind the directory to a particular project, it is not mandatory to initialize any of its components. In this case, a project folder will be created with just the catalyst.json and .catalystrc files in it.
    • If you do not initialize a particular component while initializing the project, you can always set it up later at any time after the project is initialized. To learn more, refer to the client setup and the functions setup help sections.
The project will be created along with a unique project ID. The catalyst.json file and the .catalystrc hidden file containing your project details will be created in the project directory.
Note:
  • If you're initializing resources in an existing project directory, the CLI will skip the steps to associate a project with the directory. 
  • If you are initializing a component that is already present in the project directory, the CLI will display a message asking if the folder should be overwritten. You can press Y to overwrite the existing directory or N to skip the creation of the directory and then press Enter
  • You can auto-fill queries with the default values if you press Enter.
 

Initialize Functions

If you choose to initialize the Functions directory for your project, Catalyst will initiate its setup process. 

  1. Select the type of function you would like to develop. Make your selection and press Enter.

    The five types of functions that you can develop in Catalyst are: Basic I/O, Advanced I/O, Event, Cron, and Integration functions. To learn more about the function types and their purposes, refer to the Functions help page.

    Integration Functions:

    The CLI initialization process is the same for all the other function types, except the Integration functions. If you select Integration from the list, you have to perform these two extra steps before moving on to the next step:
     
    1. Select the service that you want to integrate with. You can currently only select Cliq integration.
    2. Select the handlers that you require. You can learn more about this from the Integration Functions help page.

      The rest of the setup process is the same for all function types. The process only varies with the function stack.
  2. Select a stack to develop the server side functions in and press Enter. The list displays all supported runtimes. You can select the latest supported version of either Java or Node.js from the list. 
    Note: You can include both Java and Node.js functions in a single function directory using the catalyst functions:add command.
     

    Initialize a Java Function of Any Type


     
    1. If you initialize a Java function, enter the reference name of the Java function when prompted and press Enter. This will also be the name of the function's folder.
    2. Provide the main class name of the Java function and press Enter. The CLI will then download the Java SDK package and complete the function setup process.
    The Java function's folder will be created with the main .java class file, the library JAR files, catalyst-config.json, and other configuration files. These values will be updated in the catalyst.json configuration file.

    You can learn about the Java function directory structure in detail from the Project Directory Structure help page.
     

    Initialize a Node.js Function of Any Type

    1. If you initialize a Node.js function, provide a package name for your Node function when prompted and press Enter.
    2. Provide the name of the entry point file and press Enter.
    3. Provide a name for the function author and press Enter.
    4. The CLI will then prompt you to allow installation of node dependencies. Press Y to confirm the installation, and press Enter to confirm your choice. If you don't install all the required dependencies, it could cause errors during the function's execution.

      The CLI will then download the Node.js SDK package and complete the function setup process.
       
      Note: Catalyst enables you to create an Advanced I/O function in the Express template, which installs the Express.js modules. However, you will not be able to create the Express template from the CLI. But you can install Express on your system independently by executing npm install express --save from a particular function's directory to use the Express modules in it. You can learn more the Express template from the Advanced I/O Function help page.
    The Node function's directory is now set up with the .js main function file, catalyst-config.json, and the necessary node modules and configuration files if you installed the dependencies. These values will be updated in the catalyst.json configuration file.

    You can learn about the Node.js function directory structure in detail from the Project Directory Structure help page.
Note:
  • You can add any number of sub-folders and files in a Java or a Node.js function's directory. Besides the main function file, a function's folder can contain other sub-functions. However, the configuration files and dependencies need to be in the function directory's root.
  • You can create sub-functions through the Catalyst console, or using external editors. You can also pull an existing function directory from the console to your local system using the catalyst pull command.
  • If you need to initialize more than one function, you can do so by using the catalyst functions:add command. 
 

Initialize Client

Catalyst enables you to develop three types of client applications:

  • Angular Applications
  • React Applications
  • Basic Client Applications

Catalyst provides ready-to-use templates for Angular and React client apps. When you initialize these apps, Catalyst will handle the entire setup procedure and prompt you to install the required dependencies. The Angular and React applications will be created in your project directory in their boilerplate structure.

The basic client app is a simple version of the Catalyst client that will be created in its own standard structure. The installation procedures will differ for all three types of client apps.

Note:
  • You can add any number of sub-folders and files in the client's directory like HTML files, JavaScript files, logo images, and more. However, the configuration files and dependencies need to be in the client directory's root.
  • You can also pull a hosted web client from the console to your local system using the catalyst pull command.

If you initialize the client directory for your project, Catalyst will initiate its setup process after the functions initialization.

Select one of the client types to initialize for your project from the options, then press Enter.

Angular Applications

Angular is a front-end application design framework and development platform for creating efficient and sophisticated single-page apps. Angular follows a component-based architecture where the app is decoupled into individual, reusable functional and logical entities. The building blocks of Angular such as the components, templates, directives, dependency injections are combined into modules, that together form an Angular application. You can learn more from the official Angular documentation.

It is recommended that you have Angular CLI installed in your local machine for developing Angular client applications. This CLI handles the installation and configuration of the required dependencies automatically, and enables easy development and testing of client applications. Catalyst will automatically initiate its installation during the client initialization process.

Catalyst also provides a plugin for the Angular app, zcatalyst-cli-plugin-angular, which is installed when the Angular app is initialized. This plugin, compatible with the latest LTS version of Angular, handles several operations involved in the development and testing of the Angular app internally. This eases and quickens your application building task, and enables you to focus on the app's functionality instead of its setup and maintenance.

Note: The Catalyst plugin must be installed in the specific application's directory. The catalyst.json configuration file will specify the plugin's path. Catalyst has deprecated support for the global installation of the Angular plugin. Please update the code of your existing Angular apps accordingly.

If you select Angular Web App from the options while initializing the client, Catalyst will initiate the standard setup procedure for Angular applications. The app will be created in the latest LTS version.

Note: The current Angular LTS version supported by Catalyst is v12.
  1. The CLI will prompt you to provide a name for the client component of your project. Provide a name for the client and press Enter.
  2. If Angular CLI is not already installed in your system, Catalyst will automatically initiate a temporary installation of its LTS version. It will also install a Catalyst-specific schematics package that is required to generate an Angular app.

    Enter "Y" to confirm the installation of the required packages when prompted, then press Enter.

    If the required packages already exist in your local system, the setup will skip to the next step.
    Note: If you have an older or unsupported version of Angular installed in your system, Catalyst will prompt you to update the version to the latest supported version.
  3. You can enable Angular routing to handle navigation between the different views you create. Enter "Y", then press Enter when prompted.
  4. You can style Angular components with any of the supported stylesheet formats as shown below. Select a stylesheet format for your app, then press Enter.

    The routing and stylesheet prompts fall under the default set up procedures of Angular applications.

    Catalyst will then initiate the installation of the Angular application files, configuration files, and dependencies in their boilerplate structures. The node modules required for the development of the app are also installed through NPM.

The Angular client's directory is now set up with the standard application files, environment files, the plugin file, stylesheets, index.html, and TypeScript classes as shown below. The required node modules, JSON configuration files, and dependencies, including client-package.json specific to Catalyst, will also be present in the directory.

After these packages are installed, the catalyst.json configuration file will be updated with the client package details, including the path to the plugin file specified earlier. You can learn more about the Catalyst configuration files and the client directory from the Project Directory Structure help page.

You can learn about testing and deploying an Angular app from the Catalyst CLI from the Serve Resources and Deploy Resources help pages.

 

React Applications

React is a front-end JavaScript library that enables you to build interactive applications and user interfaces. Its component-based architecture efficiently manages and renders the states in your application upon build. React provides ease and flexibility in developing single page client applications, and offers reusability of its components. You can learn more from the official React documentation.

Catalyst provides a plugin for the React app, zcatalyst-cli-plugin-react, which is installed when the React app is initialized. This plugin contains certain node modules and library files that handle several operations involved in the development and testing of the React app internally. This allows for a faster and efficient application building process.

Note: The Catalyst plugin must be installed in the specific application's directory. The catalyst.json configuration file will specify the plugin's path. Catalyst has deprecated support for the global installation of the React plugin. Please update the code of your existing React apps accordingly.

When you initialize a React app, Catalyst will automatically facilitate its creation and configuration through the Yarn package manager by default. If you don't have Yarn installed in your local machine, the React app will be set up using NPM. Catalyst enables the handling of all configuration tasks such as linking and resolving packages, and installing dependencies, through the package manager automatically.

If you select React Web App from the options while initializing the client, Catalyst will initiate the standard setup procedure for React applications.

  1. You can create the React app with the standard JavaScript template or a TypeScript template. TypeScript is a typed superset of JavaScript that gets transpiled to plain JavaScript during compilation. Catalyst provides you with these options during the initialization to make the set up procedure easier and quicker.

    Select JavaScript or TypeScript from the options.
  2. The CLI will prompt you to provide a name for the client component of your project. Provide a name for the client and press Enter.
    Note: The client directory in your project is named client in the case of Angular and basic web client applications. However, for React applications, the name of the client directory is the same name you assign to the web client here during its initialization or set up. For example, if you name your web client as "vendorApp", the client directory will also be named vendorApp. This value will be updated accordingly in the catalyst.json configuration file.

    This will initiate the installation of the necessary React packages such as react, react-dom, and react-scripts through a Catalyst-specific CRA template. This base template will execute the create-react-app command.

    The package manager will then initialize a git repository for the React app, and install template dependencies.

    After the initialization is complete, you can find the React application files created in their boilerplate structures in your project directory.

The React app directory structure will contain the application source files, public files, configuration files, node modules, and other dependencies including client-package.json specific to Catalyst as shown below.

After these packages are installed, the catalyst.json configuration file will be updated with the client package details, including the path to the plugin file specified earlier. You can learn more about the Catalyst configuration files and the client directory from the Project Directory Structure help page.

When you serve or deploy the React app, a build folder will be created in this directory which will contain all the compiled files as per the standards of React.js.

 

Basic Client Applications

The basic client application is a simple version of the Catalyst client that is created without any external frameworks or libraries. You can create simple, functional web client applications by choosing the Basic Web App option during the client initialization.

The CLI will then prompt you to provide a name for the client component of your project. Provide a name for the client and press Enter.

The client directory will now be created in the project's directory and the catalyst.json file will be updated with its information.

The basic client's directory is now set up with the main index.html file, main.css, main.js, and the client-package.json configuration. You can learn about the client directory structure in detail from the Project Directory Structure help page.

The project initialization is now complete. The image below shows the project directory of a Java function and a basic client component in the project directory.

You can now work on the components that you initialized. You can code the function by uploading the package to the Catalyst console, and working on it using the online editor in the console or by another editor of your choice. You can also use the functions shell to test and execute the function's code.

Similarly, you can work on the client code, serve the functions and client locally to test them, and then deploy the resources to the remote console, or host them from the console directly.

 

Initialize A Specific Resource

You can initialize a specific resource in the following way:

$ catalyst init [feature]
 

You must enter the keyword client or functions. For example, to initialize the functions directory alone for your project, execute the following command from your project directory:

$ catalyst init functions
 

Initialize Options

--force

Catalyst enables you to force initialize a project or its resources in a directory. If you encounter any issues with initializing a project, you can use this option.

To perform a force initialization of a project, execute the following command:

$ catalyst init --force
 

You can follow the same steps to initialize resources, as mentioned earlier.

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocatalyst.com