Zanix Server Library for Node.js

Table of Contents

• Introduction
• Installation
• Configuration
• Getting Started
• Support and Contributions
• License
• Authors

Introduction

The Zanix Server Library is a powerful tool designed to simplify the process of running apps and microservices in Node.js. It provides a command-line interface (CLI) called Zanix Framework, which allows you to generate new APIs using customizable templates. These templates leverage the full range of features provided by the Zanix Server Library, enabling you to quickly build robust and scalable applications.

Installation

To use the Zanix Server Library, you have two installation options:

Option 1: Install Only the Library

To install only the Zanix Server Library without using a base template, follow these steps:

1. Open your project's root directory in the terminal.
2. Run the following command to install the library:

npm install @zanix/server

Option 2: Install the Library template and Zanix Framework CLI

If you want to use a base template with the server library, you'll need to install the Zanix Framework CLI globally on your system. Follow these steps:

1. Open your terminal.
2. Execute the following command (use sudo if necessary) to install the Zanix Framework CLI:

npm install -g @zanix/cli

Once you have installed the Zanix Framework CLI, you can proceed to generate a new API project.

Generating a New API (with Option 2)

After installing the Zanix Framework CLI, you can easily generate a new API project. Follow these steps:

1. Open your terminal.
2. Navigate to the desired location where you want to create the API project.
3. Run the following command:

zjs new api [path] [options]

Replace [path] with the desired project path. You can also specify additional options, such as the API name and description, during the generation process.

After generating the API, navigate to the project directory and start developing your application or microservice using the Zanix Server Library. The generated project will have a pre-configured setup that maximizes the potential of the library and facilitates efficient development. For more information, review Zanix Templates.

By choosing either Option 1 or Option 2, you can install the Zanix Server Library and start building powerful APIs with ease.

Configuration

The Zanix Server Library provides a configuration file called zanix.ts in the src/config directory of your project (if you choose installation Option 2). This file allows you to customize various aspects of your API setup. Below are the available configuration options:

| Option | Description | | -------- | ----------------------------------------------------------------------------------------------------------- | | PORT | Optional definition of PORT if not set in environment variables | | global | Define global settings for your API, such as Cross-Origin Resource Sharing (CORS) options. | | config | Provide configuration options for your API, including environment variables, custom variables, and secrets. |

Global Configuration

The global object in the configuration file allows you to define global settings for your API. Currently, it supports the following options:

| Option | Description | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cors | Cross-Origin Resource Sharing (CORS) options. Define allowed origins, methods, and headers. | | pipes | Global middleware functions that are executed for every API call, allowing for validation, etc. You can also add useGlobalPipe at the beginning of your pipe file to avoid assigning it in this section. |

API Configuration

The config object in the configuration file provides additional configuration options for your API:

| Option | Description | | ----------- | -------------------------------------------------------------------------------------- | | envars | Define environment variables specific to different environments. | | variables | Set custom variables for your API, which can be used globally across all environments. | | secrets | Specify an array of secret names that your API requires. |

Setting Environment Variables

To define environment variables for your API, use the envars property in the config object. This property allows you to specify environment-specific variables based on the defined environment names in your application.

For example, consider the following configuration:

config: {
  envars: {
    development: {
      VAR1: 'Value 1',
      VAR2: 'Value 2'
    },
    production: {
      VAR3: 'Value 3',
      VAR4: 'Value 4'
    }
  }
}

In this configuration, the envars property defines environment variables for the development and production environments. You can add or modify these variables based on your specific requirements.

Setting Custom Variables

The variables property in the config object allows you to define custom variables that can be used globally across all environments. You can set these variables using a combination of key-value pairs and references to environment variables.

Here's an example:

config: {
  variables: [
    { VAR1: 'Variable 1' },
    'VAR2=Variable 2',
    { VAR3: 'Variable 3 => ${VAR1}' }
  ]
}

In this configuration, three custom variables (VAR1, VAR2, and VAR3) are defined. The values can be assigned directly or referenced from other variables or environment variables.

Setting Secrets

To specify secrets for your API, use the secrets property in the config object. This property expects an array of secret names that your API requires.

For example:

config: {
  secrets: ['secret1', 'secret2']
}

In this configuration, the array contains the names of the secrets required by your API. The actual secret values should be stored securely and can be accessed at runtime.

Please refer to the zanix.ts file for more details on how to customize your API's configuration.

Default Environments

The Zanix Server Library comes with the following default environments:

• PORT: 8080

To start the server, set the NODE_ENV environment variable to one of the above values.

Getting Started

To start your server, you can run the zjs start [options] command (if you choose installation Option 2) or add the following lines of code to your project file (in the other case):

import ZanixServer from '@zanix/server'

ZanixServer.appSetup = {
  general: {
    ssr: {
      /*...*/
    },
    api: {
      /*...*/
    }
    global: {
      pipes: []
    }
  },
  config: {
    /*...*/
  }
}

ZanixServer.start(/*you can also specify the PORT here*/)

This will initialize and start your server using the specified configuration.

We hope you enjoy using the Zanix Server Library and find it a valuable tool for building your Node.js applications and microservices!

Support and Contributions

To ensure compatibility between this library and the Zanix Framework CLI, please refer to the changelog section for detailed information on versioning and compatibility. It is recommended to review the changelog to understand any specific requirements or changes associated with different versions of the library and the CLI.

If you have any questions, suggestions, or feedback, you can reach out to the author via email at [email protected]. You can also connect with the author on Linkedin for updates and announcements about software.

Next Steps

• Consult the comprehensive documentation of the Zanix Server Library (currently under construction) to gain a deeper understanding of its extensive features and learn how to take advantage of them effectively.
• Explore the project structure of the generated API, familiarizing yourself with the various files and directories that empower your development process.
• Customize and extend your API as per your unique requirements, utilizing the full spectrum of capabilities provided by the Zanix Server Library.

License

The Zanix Server Library is an open-source project released under the MIT License. You are free to use, modify, and distribute it as per the terms of the license.

Authors ✨

• Ismael Calle Marulanda @iscam2216