Project Directory Structure
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 (CATALYST_PROJECT_HOME). 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 all of the components, the following resource directories are created in your project directory:
- Client (CATALYST_CLIENT_HOME)
- Functions (CATALYST_FUNCTIONS_HOME)
Let us take a look at these resources in detail.
By default, the client folder is set up with the following files:
The index.html file is the default file name for your web application's home page. It is created with a sample code structure.
The main.css file contains the styling of your web application's pages. It is created as an empty file.
The main.js file defines the functionality of the web application's home page. It is created as an empty file.
The client-package.json is the configuration file of your client resource. It contains the following specifics of your application by default:
- 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.
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.
- A home page for your web application and the client-package.json file are required to be present mandatorily in the client directory. The CSS and JS files are optional, based on your application's functionality. You can delete the main.css and the main.js files if you don't need them.
- When hosting a web application, you must ensure that the specifics mentioned in the client-package.json file are accurate, and you have followed all the guidelines mentioned above. To learn more about hosting a web application, refer to the Web Client Hosting page.
- You can setup the client component at any time using the CLI while working with the project. To learn more, refer to the Working with the Client help page.
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:
- The main .java Class File
- The .jar Library Files
A Node.js function's folder is set up with the following components when it is created:
- The main function file (index.js)
- 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.
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:
- The main function file
- 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.
- When you create a function from the console, the function group will not contain all the required dependencies. For example, the node modules will not be added to a Node.js function group, although a folder will be created for it. In such cases, you can pull the functions from the console to the project directory using the CLI.
This will create a directory for those functions in the required structure. If the function group created in the console contains secondary functions, they will be included in the function's folder when you pull it from the console.
- When you create a function from an external editor and import it into Catalyst, you must ensure that all the dependencies are included, and all the configuration files are created in the specified format. If there are any discrepancies, it could result in errors when the function is executed.
An app logic is used to handle native HTTP functions. The structure of the app logic directory is similar to that of a Node.js function directory, since an app logic is essentially a node function in behavior.
When you initialize app logic from the CLI, the app logic home directory is created along with the node modules and other Node.js dependencies as discussed above. You can create only one app logic for each project.
The main function file or the entry point file of an app logic is handler.js by default which is created with a sample code structure. You can rename this file if you require, but you must update the changes in the catalyst-config.json file and the catalyst.json file. The catalyst-config.json file of the app logic is similar to that of a node function, except it specifies the function type as "app logic".
The catalyst.json file contains the configuration of the entire project's directory, i.e., the functions, app logic, and client directories.
It contains the following specifications of the client, app logic, and the function directories:
- Source: The source specifies the target folder names of the functions, the client, and app logic directories. You must not modify these values.
- Targets: The targets specify the representative names of the app logic and 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:
- 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.
- 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.
- If you rename the functions, client or the app logic directory, you must update the changes in catalyst.json.
- If you change the representative names of any of the functions or app logic, you must update the changes in catalyst.json.
- If you execute the catalyst functions:setup, catalyst functions:add, catalyst client:setup, or catalyst pull commands from the CLI, the configuration information of the function, client, or app logic is automatically updated in the catalyst.json file.
- 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.