Serve Resources

Serve Resources

 

Introduction

Catalyst CLI allows you the convenience of testing your project resources locally before deploying them to production. You can serve the resources through a localhost in your system for testing without affecting the live version of your application.

You can serve these components of your project through the local server: Basic I/O functions, Advanced I/O functions, Angular web apps, React web apps, and Basic web apps.

Catalyst will not be able to serve functions of the other types, i.e., Cron, Event, and Integration functions, as their endpoints are not directly accessible through URLs. You can learn about the various function types from the Functions help page.

The serve command also enables you to start a local server from any port, or start the server in a debug mode to analyze the execution of your code in detail. You can test specific targets of your project, proxy unknown requests to the local host URL, or ignore lifecycle scripts. All these actions can be performed using the various options available for the serve command.

Note:
  • You can also launch a node shell exclusively to test and debug functions of all types except the Advanced I/O functions. To learn more about this, refer to the Working with Functions help page.
  • The functions and the client packages can be served successfully only if their directories are in the standard structures. The directories must contain the required configuration files in the standard format. For more information, refer to the Project Directory Structure help page.
 

Serve All Resources

You can host the Basic I/O and Advanced I/O functions, as well as Angular, React, or the Basic client component, of your Catalyst project locally by navigating to your project directory and executing the following command:

$ catalyst serve
 

This will start a local server in the default port 3000 and deploy your resources to the endpoint.

The CLI will display the URLs of the local endpoints of your client and the functions that are served.

As mentioned earlier, Catalyst can only serve Basic I/O and Advanced I/O functions. Therefore, if there are any Cron, Event, or Integration functions in your project directory, they will be skipped from being served. Similarly, the API Gateway Rules JSON file will also be skipped from being served.

 

Serve Functions and Basic Web Applications

You can test the Basic I/O and Advanced I/O functions that are hosted through the local server by accessing their URL endpoints. These endpoints can be accessed from an IDE environment or in your browser.

The web client will open in your default browser automatically, after it is hosted through the local server.

Note: You can disable the automatic opening of the web client URL in your browser using the --no-open option.

When you access the home page or any of the sub-pages of your client, or your function endpoints after they are served, the CLI will display a live log of the endpoints accessed along with the request methods that are used to access them. The function invocation information also includes log levels and other log entries as shown below.


 

Serve Angular Applications

Angular applications in your project will be served similarly. The Catalyst plugin for your Angular app, zcatalyst-cli-plugin-angular, which is installed when the Angular app is initialized, will handle the serve session.

Angular implements Hot Module Replacement (HMR). The HMR is a Webpack feature that updates and reloads specific modules, without recompiling and reloading the entire project, when changes are made during a serve session. HMR is enabled when you serve the application through the Catalyst CLI by default.

Note: You can disable the live watch using the --no-watch option while serving a component.

When the Angular app is served, the modules in the app, such as /router, /common etc are all compiled initially. The CLI displays the details of the compilation and the build generation. You can also see the details of the individual files in the application, like the initial chunk files and their sizes. These fall under the default norms of the build and serve processes of Angular apps.

The CLI will redirect to the default browser to open the web client automatically after the compilation is done. You can disable this using the --no-open option, similar to the basic web apps. You can see the live log of the endpoints accessed along with the request methods, in an Angular app's serve session as well.

If the HMR has not been disabled, the changes you make in your Angular app will be reflected live in the serve session without a recompilation and reload of the entire component. The CLI will display the live logs of the updated modules, such as the details of the changed chunk files.

 

Serve React Applications

A Catalyst React app will be served similar to an Angular app. The Catalyst plugin for your React app, zcatalyst-cli-plugin-react, which is installed when the React app is initialized, will handle the serve session.

React applications implement Hot Module Replacement (HMR) similar to Angular applications. The HMR is a Webpack feature that updates and reloads specific modules, without recompiling and reloading the entire project, when changes are made during a serve session. HMR is enabled when you serve the application through the Catalyst CLI by default.

Note: You can disable the live watch using the --no-watch option while serving a component.

When the React app is served, the plugin compiles into a development build. The CLI displays the details of the compilation and the local endpoint to access the app.

The CLI will redirect to the default browser to open the web client automatically after the compilation is done. You can disable this using the --no-open option, similar to the basic web apps. You can see the live log of the endpoints accessed along with the request methods, in a React app's serve session as well.

If the HMR has not been disabled, the changes you make in your React app will be reflected live in the serve session without a recompilation and reload of the entire component. The CLI will display the live logs of the updated modules.

 

After you test the client and functions, you can quit the serve session in your terminal by killing the running command based on your local environment. This will shut the local server down.

 

Catalyst Serve Options

Catalyst CLI enables a variety of options that you can use with the catalyst serve command.

--http <port>

You can serve the resources locally in any port you require, other than the default port 3000. You can do this by using the --http option and including the port number where you need the resources to be served from.

For example, to serve your resources from port 2000, execute the following command from your project directory:

$ catalyst serve --http 2000


 

--debug <type:port>

Catalyst enables you to start the local server in the debug mode and attach a debugger to the live server. You can debug the code of your Basic I/O and Advanced I/O functions of your project. You can associate the server to a debugger instance of your IDE that you use to develop the code with. This allows you to debug the execution of your functions, and identify the errors and issues in the code.  

You can also choose to start the server at a port of your choice similar to the --http<port> option. The default port where Basic I/O functions are attached to the debugger is 8010 and Advanced I/O functions is 8000.

You can start the local server in the debug mode by executing the following command from the project directory:

$ catalyst serve --debug <advancedio:name:port,basicio:port>
 

You have to specify the name of the Advanced I/O functions while using this option. You need not specify the names of the Basic I/O functions For example:

$ catalyst serve --debug advancedio:InvoiceFetch:2000,basicio:4000
 

This will start the local server at the default port 3000. The resources will be served and the local endpoints will be displayed. You can then attach the debugger at port 2000 for the Advanced I/O function, and port 4000 for the Basic I/O functions. The server will be listening at these ports for the debugger.

After you see this message, open your IDE and attach the debugger to the ports you specified for the functions. The CLI will display a confirmation message after it is attached. You can now test your resources and debug them. The CLI will display the errors caught by the debugger, along with their details.

 

--proxy<url>

Catalyst enables you to proxy an unknown request to the localhost URL generated by the server in the CLI. This allows you to proxy the requests that are encountered during the serve of functions. Such requests will be proxied to the Catalyst console by default.

You can specify the URL to proxy the unknown requests to, while executing the serve command as follows:

$ catalyst serve --proxy <url>
 

--only<targets>

You can serve specific targets instead of all the resources using this option. For example, you can serve specific functions, or the client package alone.

To serve specific targets, execute the catalyst serve command with the --only option followed by the targets to be served as shown below:

$ catalyst serve --only client


 

--no-watch

Catalyst CLI provides a live watch mode by default, which allows you to perform hot reload of the resources that are being served. This enables you to view the updates of the changes you make instantly, without having to re-compile or re-serve the code.

However, if you require the live watch mode to be disabled, you can do so using this option. You can use this option if you don't have to make changes in the code, such as while serving a production-ready build, or if don't require the updates to be reflected live.

You can serve resources with the default live watch disabled as shown below:

$ catalyst serve --no-watch
 

This will make the server compile the code only when the code is served initially. The server will not watch for changes after the code is served. The updates will not be reflected live when you test the resources.

If you require the default live watch mode to be enabled again, you must exit the serve session, and re-serve the code without using this option.

 

--except<targets>

You can choose to exclude specific resources from being served using this option. For example, you can exclude specific functions or the client package.

To exclude a specific function, execute the catalyst serve command with the --except option followed by the target name as shown below:

$ catalyst serve -- except functions:InvoiceGeneration


 

--ignore-scripts

Catalyst enables you to automate the CLI and terminal command executions by defining scripts in the catalyst.json file in your project directory. You can define two lifecycle scripts to execute before and after the catalyst serve command respectively: preserve, postserve. You can learn more about the lifecycle and custom scripts from the Scripts help page.

If you use the --ignore-scripts option while executing the catalyst serve command, the CLI will ignore the actions configured for the preserve and postserve scripts in the catalyst.json file of your project directory. The deployment process will proceed without the execution of these lifecycle scripts.

You can use the --ignore-scripts option as follows:

$ catalyst serve --ignore-scripts
 

The serving process will be the same as discussed earlier.

 

--no-open

When you execute the serve command and the server hosts the code, the CLI will redirect you to your default browser automatically to open the client component in your project. If you require this automatic redirection to be disabled, you can execute the serve command with this option as shown below:

$ catalyst serve --no-open
 

The CLI will display the localhost URL of all the served components as usual. You can still open the web client manually by accessing the URL, if you require.

You can use this option when you don't require the client component to be tested, or while performing a test run of a production-ready build.

Share this post : FacebookTwitter

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

Write to us: support@zohocatalyst.com