Introduction

When you create or initialize a new project from the Catalyst CLI, it is created in a specific structure along with the necessary configuration files. This project is stored in the directory that you create it in, which will be considered as the project's home directory. The boiler plate code for the project is generated in the project's home directory during the creation. To learn about initializing a Catalyst project or any of its specific components from the CLI, refer to the Initialize Resources help page. 

Before you host a web client in Catalyst, you must ensure that it contains all the resources in the standard project directory structure as described in this help page. Any discrepancies could cause errors in the production of your application.

When you initialize a Catalyst project from the CLI, you will be asked to choose the components to initialize. The two fundamental components of a Catalyst project that you can initialize are: the client and functions. 

If you initialize both the components, the following resource directories are created in your project directory:

1. Client
2. Functions
3. catalyst.json

Let us take a look at these resources in detail.

Client Directory

The 'client' folder in the projects directory contains all the components of the front-end of your application. These include the HTML files of the webpages, the CSS files, the JavaScript files that enable the actionable elements in your webpage, and other required files.

By default, the client folder is set up with the following files:

1. index.html
   The index.html file is the default file name for your web application's home page. It is created with a sample code structure.
2. main.css
   The main.css file contains the styling of your web application's pages. It is created as an empty file.
3. main.js
   The main.js file defines the functionality of the web application's home page. It is created as an empty file.
4. client-package.json
   The client-package.json is the configuration file of your client resource. It contains the following specifics of your application by default:

   
   			{
   			"name":"shipmentTracking",
   			"version":"0.0.2",
   			"homepage":"index.html",
   			"login_redirect":"home.html",
   			"404":"custom404.html"	
   			}

    
   • name: The name of the web client. Once you set a name for it and host the application, you must not change it. Changing the name of the web application after it has been hosted will result in an error.
   • version: The version of the web application that is hosted, in the decimal format. With every subsequent update of your application, you can modify the version number in an incremental manner. You cannot decrement the version number. 
   • homepage: The URL of the web application's home page. If you modify the name of the index.html file, you must change the value accordingly in this file as well.
   
   Apart from these mandatory specifics, you can include these properties as well:
   • description: The description of the web application. This can be modified during version upgrades.
   • login_redirect: The page where the user has to be redirected after a successful login to the web application.
   • 404: A custom 404 page that you can create for your application. Every time the users of your application try to access a non-existent page resulting in a 404 error, they will be redirected to this custom page.
   Note:

   • If you are providing a path to a custom 404 page using the 404 key, you can name that file anything as you require. If you don't configure a 404 key in the client-package.json file, you can still include a page with the exact name 404.html in the directory.
   • Catalyst will search for the key 404 in the clientpackage.json file. If it exists, Catalyst will render that file in the event of a 404 error occurrence in the application. If no path for a custom 404 page is provided in your app, Catalyst will search for any file named 404.html in the client directory. If neither exists, the users will be redirected to a default 404 page provided by Catalyst.

You can further add more client files of your web application, and create sub-folders inside the client folder as you require. However, the client-package.json file must be mandatorily present only in the root of your client resource and not in any sub-folders.

Functions Directory

As discussed earlier, Zoho Catalyst supports functions written in Java and Node.js programming environments. The 'functions' folder in the project directory contains all the server-side functions of your microservice in individual folders. 

An individual function's folder in the Functions directory contains the main function file (the .java class file or the .js file), and all the other necessary dependencies and configuration files of the function. You can also create additional secondary functions in the function's folder that closely work with the main function. All these files in the function's folder can be collectively called as a function group.

However, you cannot create secondary functions in a function folder from the CLI. You can either manually import the files in the folder from an external development environment, or create them in the Catalyst console and pull them to the directory using the CLI.

When you initialize functions from the CLI in the project directory, a folder named 'functions' will be created inside the project directory, along with the necessary dependencies based on the programming environment that you select. 

A Java function's folder is set up with the following components when it is created:

1. The main .java Class File
2. catalyst-config.json
3. The .jar Library Files

A Node.js function's folder is set up with the following components when it is created:

1. The main function file (index.js)
2. catalyst-config.json
3. Node modules and Node.js function dependencies

Let us first discuss about the main function file and the catalyst-config.json file that are common to both Java and Node.js programming environments.

The Main Function File

The main function file is the file of the type .java or .js, depending on the language that you selected while initializing the function. The main function file is created with a sample code structure for both Java and Node.js. 

For a Java function, you will need to provide the class name of the main function, and the reference name of the function group while initializing it from the CLI. The name of the function folder will be the same as the reference name of the function.

For a Node.js function, you will need to provide the package name of the function. You will also need to provide the name of the entry point file or the main function file, which will be named as 'index.js' by default.

The catalyst.json file will specify the reference or the package names of all the functions.

catalyst-config.json

The catalyst-config.json file specifies the configuration of the function, such as its deployment and execution specifications.

The deployment information includes the following:

• Name: The reference name of the function group that you provided while initializing it.
  If you modify the reference name of the function, ensure that you update the changes in catalyst-config.json and rename the function folder with the same name. You must reflect the changes in catalyst.json as well.
• Stack: Indicates whether it is a Java function or a Node.js function and the version information. Changing this value will result in errors.
• Type: Indicates the type of function. To learn more about function types, refer to the Functions help. Changing this value will result in errors.

The execution information refers to the main function file which is the entry point, i.e., the name of the main .java or .js function file. 

You must ensure that catalyst-config.json file is present in the root of the function folder and contains the right configurations, when you deploy the function.

Let us now look into the Java library files and the Node function dependencies.

The Java Library Folder

The library folder named 'lib' contains the dependent JAR files for the function. The lib folder is added to the function directory automatically when you initialize the function for the Java environment from the CLI. 

These JAR files are part of the Java SDK package. During the runtime, the Java function calls these library files as they contain packages and features that are required by the function to execute.

Node Modules and Node.js Function Dependencies

A Node.js function's folder essentially includes the following:

1. The main function file 
2. catalyst-config.json 
3. package-lock.json 
4. package.json 
5. The node modules folder 

We have previously discussed the main function file and the catalyst-config.json file. The node modules and node function dependencies are installed in your system when you install the Node.js SDK package.

The package.json and package-lock.json files are dependency files that contain the configuration of the function. The package.json files specifies information like the name of the function, main function file, version, author and more, whereas the package-lock.json specifies other dependency information in detail. 

The node modules folder contains the sub-folders of the modules. Each module contains individual library files, license files, configuration files, index files and more, that are essential for the execution of your Node.js functions.  

One of the node modules, zcatalyst-sdk-node, contains the Node.js SDK definitions of all Catalyst components grouped in a folder named 'src', and other dependency files. 

The catalyst.json File

The catalyst.json file contains the configuration of the entire project's directory, i.e., the functions and client directories. 

It contains the following specifications of the client and the function directories:

• Source: The source specifies the target folder names of the functions and the client directories. You must not modify these values.
• Targets: The targets specify the representative names of each individual function of the project. 
• Ignore: The ignore field specifies the files in the component directory, or in one of its sub-directories, that must be ignored while deploying the code to production. You can mention the files to be ignored inside the square brackets. 
  You can list the files directly or use glob patterns to specify the files. For example, if you specify *.css, all CSS files in the particular directory will be ignored during the deployment.

The following points must be noted: 

1. The catalyst.json file is created in the project directory irrespective of which components you initialize during the project creation from the CLI. Even if you do not select any components to initialize, the catalyst.json file will be created. Therefore, when you create a project from the Catalyst UI console, you must initialize it from the CLI for catalyst.json to be created with the configuration information of the project resources. 
2. The catalyst.json file is not mandatory if you host your web application from the Catalyst console i.e., when you host the client resource and deploy the functions individually from the console. However, if you deploy your application as a whole from the CLI, or from an external source like GitHub, the catalyst.json file must be mandatorily present in the root folder of your application.
3. If you rename the functions or the client directory, you must update the changes in catalyst.json.  
4. If you change the representative names of any of the functions, you must update the changes in catalyst.json.
5. If you execute the catalyst functions:setup, catalyst functions:add, catalyst client:setup, catalyst applogic:setup, or catalyst pull commands from the CLI, the configuration information of the function or client is automatically updated in the catalyst.json file.
6. If you manually import any component files from an external development environment, you must create the configuration files in the format mentioned in this help page.