NodeJS Front-end Language

This document is suitable for nodejs front-end projects, such as vue and react.

NodeJS Front-end Project Identification Method

Kato will recognize it as a NodeJS front-end project based on whether there are package.json and nodestatic.json files in the source code root directory. In addition, one of the following two files must exist in the source code root directory (not Can exist at the same time):

  • When the file package-lock.json exists, Kato is built using the npm package manager by default.

  • When the file yarn.lock exists, Kato is built using the yarn package manager.

Verification Preparation

Before deploying the project to Kato, please follow the steps below for local verification. After the local build is successful, you can start to try to deploy the project on Kato.

  • The source code is hosted on Git or SVN server.

  • Check the local build environment and operating environment to determine the version of npm, node, and yarn.

  • Clear the local build cache. Normally, there is a node_modules directory in the local project path. Please change the path of this folder temporarily after confirming.

mv node_modules node_modules.bak

Execute the following build command, which is also the default command for Kato nodejs front-end project construction:

# When building with npm
npm run build

# When building with yarn
yarn run build

Compile and Run Environment Configuration

During the environment preparation stage, Kato needs to build and run the environment to be as unified as possible with the commonly used local build and run environment. Such as Node version, build command, etc.

Graphical Settings

Kato supports graphical definition of the compilation and runtime environment, and the configuration is located on the build source page of the service component.

Modifications to these configurations need to be implemented through Build

  • Disable caching. Before the first successful build is completed, the switch should always be on and off by default.

  • Select the Node version used for compiling and running. Be sure to use the version verified during verification preparation.

  • BUILD_NODE_ENV, used to specify whether to clean up dependencies during the build process, by default.

  • NPM MIRROR_URL, used to specify the construction of a private server, and the Taobao npm source address is specified by default.

  • The build command is used to specify the command to build the project. The default is npm run build or yarn run build, depending on whether the source code root directory has package-lock.json or yarn.lock.

The compilation and runtime environment of the Nodejs front-end language project can be set by code.

package.json

This file is very important, and the platform builds the project according to the build command defined in the scripts section. Configure the environment based on the node, npm or yarn version defined in the engines section. The version definition can be defaulted. The default is node=10.9.0 yarn=1.9.4 npm=6.2.0 If you need a customized version, please configure it in the following format:

"engines": {
    "node": "12.8.1",
    "npm": "6.4.1"
}

Currently Kato supports the following Node versions:

OptionsVersion
Node0.12.18, 4.9.1, 5.12.0, 6.14.4, 7.10.1, 8.12.0, 9.11.2, 10.13.0, 11.1.0, 12.8.1
Yarn1.9.4

The default version of the platform uses 8.12.0.

The scripts in the package.json file has CI features, and the Kato source code construction process inherits these features, such as:

"scripts": {
	"preinstall": "bash preinstall.sh", # Automatically execute the script preinstall.sh before executing npm install
    "postinstall": "bash postinstall.sh", # After executing npm install, the script postinstall.sh is automatically executed
	"build": "vue-cli-service build --mode test" 
}

For more features of npm-scripts, please refer to How npm handles the “scripts” field

nodestatic.json

This file specifies the output directory of the compiled static file. Generally, the path is dist.

{
   "path": "dist"
}

web.conf

After the project is compiled, Kato will use Nginx (1.14.2) by default to run the front-end project. The user can add the web.conf file in the root directory of the source code to specify the Nginx configuration. The function of this file is to define runtime parameters, especially the proxy for the background API. Without this file, Kato will use the default configuration. The reference configuration example is as follows:

upstream upstream-server {
    server 127.0.0.1:8080;
}

server {
    listen 5000;
    
    location /api {
        proxy_http_version 1.1;
        proxy_set_header Host manage-server;
        proxy_pass http://upstream-server;
    }

    location /index.html {
        add_header Cache-Control "private, no-store, no-cache, must-revalidate, proxy-revalidate";
        try_files $uri $uri/ /index.html;
        root /app/www;
        index index.html index.htm;
    }
    location / {
        try_files $uri $uri/ /index.html;
        root /app/www;
        index index.html index.htm;
    }
}

The format of the configuration file is the same as that of the nginx configuration file. In the example, /manage-server is the access path of the back-end API, proxying to 127.0.0.1:8080, and then the front-end components need to rely on the back-end API components.

katofile

Add katofile in the root directory of the source code to define environment variables for the service components. More configuration during the build process can be defined by environment variables.

In the process of building the Kato source code, the variables starting with BUILD_ defined for the service component can be passed into the build environment for use. Some commonly used environment variables are as follows:

Environment VariablesDefault ValueDescription
BUILD_NPM_REGISTRYhttps://registry.npm.taobao.orgPrivate server address specified when executing npm install
BUILD_YARN_REGISTRYhttps://registry.npm.taobao.orgPrivate server address specified when executing yarn install
BUILD_NODE_ENVproductionis used to specify whether to clean up dependencies during the build process, the default cleanup
BUILD_NODE_MODULES_CACHEtrueSpecify whether to turn on the build cache, when the Kato server disk performance is low, specify it as false
BUILD_NODE_VERBOSEfalseSpecify whether to reflect the dependency list in the build log (npm ls or yarn list)

Start Command Configuration

After the Nodejs front-end project source code construction process is completed, Kato will automatically run the service component, which requires us to specify the startup command of the service component in advance.

Procfile Specification

Kato uses the Procfile file in the root directory of the source code to define the project startup command. For the specification of the Procfile file definition, please refer to Procfile.

If Procfile is not defined, the following default Procfile will be generated

web: sh boot.sh

The above is the default Procfile, if you need to expand more startup parameters, you can customize the Procfile.

  • There is a space between web: and sh
  • The end of the file cannot contain special characters

The content of boot.sh executed by default is:

sed -i -r "s/(listen ).*/\1\$PORT;/" /app/nginx/conf.d/web.conf #Use the specified port to configure Nginx listening
touch /app/nginx/logs/access.log
touch /app/nginx/logs/error.log
ln -sf /dev/stdout /app/nginx/logs/error.log
ln -sf /dev/stderr /app/nginx/logs/access.log
echo "Launching nginx"
exec /app/nginx/sbin/nginx -g'daemon off;'

Sample Demo Program

Example https://github.com/gridworkz/kato-ui

Common Problems

An error was reported when packaging using the git-revision-webpack-plugin plugin.

Part of the project packaging configuration is set to obtain the version number based on git, which requires the existence of a .git file in the source directory. The source code used in the source code compilation process in Kato will not have a .git file. Therefore, you cannot use the git plugin to get the version. There is version management on the Kato platform, so if you encounter this problem, please remove the git-related plugins in the webpack configuration file.

Visit 404 after compiling

Please confirm whether the compiled file publishing directory configured in nodestatic.json is the project configured publishing directory. For example, the real directory is build, but dist is configured in nodestatic.json, and the compiled file cannot be found in the end.

What should I do if the source code compilation fails on the platform?

Check the build log. In most cases, the source code does not conform to the specification or the compilation fails. Logs can help you find and solve problems.

  • Scenario 1, the build log prompts Two different lockfiles found: package-lock.json and yarn.lock, this message indicates that both package-lock.json and yarn.json exist in the root directory of the current source code Two lock files, please delete the other lock file according to the package manager you want to use, submit the code and rebuild.

  • Scenario 2, build log prompt: Outdated Yarn lockfile, this message indicates that the current build used yarn.lock conflicts with the version dependency specified in package.json, according to the follow-up prompt of the build log, You can update yarn.lock locally and rebuild after submitting the code.

  • Scenario 3, the build log prompts No matching version found for Node: XXX or No matching version found for Yarn: XXX, the message prompts the Node defined by scripts.engines in package.json, Yarn version is temporarily not supported, please refer to the above document package.json configuration version section. If the version provided by Kato does not meet the needs of the project, please contact the engineer of Gridworkz Technology to add it.

  • Scenario 4, the build log prompts Invalid semver requirement, which indicates that the method of defining the version of scripts.engines in package.json does not conform to semver format . Please refer to the above document package.json configuration version section.

The source code compiles through but runs abnormally.

  • Scenario 1, because there is no nodestatic.json file defined, the platform considers this to be a nodejs backend project. It runs in the same way as the back-end project. The solution is to add the nodestatic.json file to the source code, and then recreate the component or re-identify the source code type. Then rebuild.

  • Scenario 2, the configured web.conf format is incorrect and it is not a legal nginx configuration. The wrong line will be displayed in the component running log.