edgeone/README.md

Command-line interface for TencentCloud Pages Functions

<br/>
<div align="center">
  <img src="https://cloudcache.tencent-cloud.com/qcloud/ui/static/static_source_business/8f2d5c70-8f06-4366-ae29-1a3eb9c7f602.svg" height="96">
  <h3 align="center">EdgeOne CLI</h3>
</div>

<br/>

## Overview

EdgeOne Pages is a front-end development and deployment platform built on Tencent EdgeOne infrastructure, designed for modern web development. It enables developers to quickly build and deploy static sites and serverless applications. By integrating edge function capabilities, it ensures efficient content delivery and dynamic functionality expansion, supporting fast access for users worldwide.

EdgeOne CLI can help you manage and debug Pages Functions in the project more efficiently.

<br/>

## 1. Preparations

- Quickly register and log in to the [Tencent Cloud Console](https://edgeone.ai/pages/new?s_url=https://console.tencentcloud.com/) using a Gmail account.

- Create a [Pages project](https://edgeone.ai/pages/new?s_url=https://console.tencentcloud.com/edgeone/pages) in the Console, and clone the repository to Local.

_If you are a China site user, please go to the corresponding [Pages](https://console.cloud.tencent.com/edgeone/pages) console._

<br />

## 2. Quick Start

### 1. Install

In the cloned project during the preparation stage, you can use npm to install the CLI:

```plaintext
npm install -g edgeone
```

Use the `edgeone -v` command to check if the installation is successful. Use the `edgeone -h` command to view all relevant commands.

###

### 2. Log in

Execute the login command, follow the prompts to select `Global` (International) or `China`, then complete the login in the pop-up browser window.

```plaintext
edgeone login
```

After completing the login, you can use the `edgeone whoami` command to view the current login account information.

### 3. Initialize

After successful login, execute the initialization command to initialize the basic environment required by Edgeone Pages in the project:

```plaintext
edgeone pages init
```

After initialization, a `functions` folder and sample functions will be generated in the root directory of the project. You can continue to add and develop functions in this folder.

### 4. Local Development

After completing initialization, enter the local development stage:

```plaintext
edgeone pages dev
```

Executing the command will start a service on the local port 8088 by default. You can access the sample function via `http://localhost:8088/helloworld`. Here, the access path is the address path of the function file in the `functions` folder.

During local development, the service for Pages Functions and the service for the Pages project may run on different ports. In order to allow the Pages project to call functions, you can use a proxy server or reverse proxy to forward requests to the correct port. Here is an example configuration of webpack-dev-server:

```javascript
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:8088', // Local Development Service Address for Pages Function
        chagneOrigin: true,
        pathRewrite: {
          '^/api': '',
        },
      },
    },
  },
};
```

In this way, use the Fetch API in the Pages project:

```javascript
fetch('/api/my-functions', {
  method: 'POST',
  body: JSON.stringify({ data: 'example' }),
});
```

### 5. Associated Project

If you need to use the Key-Value Storage capability or synchronize the environment variables set in the console to local debugging, you can execute the Associated Project commands, enter the project name as required. The project name here is the one created in the Preparation Work of the Pages project.

```plaintext
edgeone pages link
```

### 6. Deploy

After local development and debugging are completed, you can deploy your project directly using the deploy command:

```plaintext
edgeone pages deploy <directoryOrZip> -n <projectName>
```

#### Parameters

- `<directoryOrZip>`: Path of folder or ZIP package to deploy (required)
- `-n, --name`: Project name for deployment (creates new or updates existing project) (required)
- `-e, --env`: Environment to deploy to, choices: 'production' or 'preview' (default: 'production')

#### Usage Examples

```plaintext
# Deploy build folder to production
edgeone pages deploy ./dist -n edgeone-pages-project

# Deploy ZIP package to preview environment
edgeone pages deploy ./build.zip -n edgeone-pages-project -e preview
```

**Alternative: Git-based Deployment**

You can also push the project code to the Git remote to trigger the CI build and deployment in the Pages backend, completing the entire development process.

### 7. Switching Accounts

If you need to switch to another Tencent Cloud account, you can execute the following command and then log in again:

```plaintext
edgeone switch
```

### 8. Combine with front end

EdgeOne Pages CLI supports local development and debugging of EdgeOne Pages functions. If your project contains frontend code, you need to manually start the corresponding development service.

For frontend applications that need to access local functions, currently you need to distinguish function access paths through environment variables in your frontend code:

```
// when start dev server
ENV=dev npm run build

//In your code
const REQUEST_API = process.env.ENV === 'dev' ? 'https://localhost:8088/' : '/'
```

For functions involving cross-origin validation scenarios like login and authentication, you can specify the `--fePort` parameter when starting the development server.

```
edgeone pages dev --fePort=8000 // your front dev server port
```

<br/>

## 3. CI/CD Integration

This section provides guidance on integrating EdgeOne CLI into your CI/CD pipelines for automated deployments.

### Automated Deploy Command

For CI/CD pipelines, you can use the same deploy command with an API Token for authentication:

```plaintext
edgeone pages deploy <directoryOrZip> -n <projectName> -t <token>
```

#### Parameters

- `<directoryOrZip>`: Path of folder or ZIP package to deploy (required)
- `-n, --name`: Project name for deployment (creates new or updates existing project) (required)
- `-e, --env`: Environment to deploy to, choices: 'production' or 'preview' (default: 'production')
- `-t, --token`: API Token for CI/CD pipelines (required for automated deployments)

#### CI/CD Pipeline Examples

```plaintext
# Basic CI deployment to production with API token
edgeone pages deploy ./dist -n edgeone-pages-project -t $EDGEONE_API_TOKEN

# CI deployment to preview environment with API token
edgeone pages deploy ./build.zip -n edgeone-pages-project -e preview -t $EDGEONE_API_TOKEN
```

#### Obtaining an API Token

How to create an API Token

1. Access the Pages console and switch to the "API Token" Tab.
2. Click "Create API Token".
3. Enter "Token description" to help you remember the purpose of the API Token.
4. Select "expiration time" to ensure your information security.
5. Click Submit.

For more information, please refer to https://edgeone.ai/document/177158578324279296

<br/>

## References

[Pages Introduction](https://edgeone.ai/document/160427672992178176) ｜ [Pages Functions](https://edgeone.ai/document/162227908259442688)

_To access the China site documentation, please click [here](https://edgeone.cloud.tencent.com/pages/document/162936635171454976)._

<br/>

## Contact

If you need technical support, please [contact us](https://edgeone.ai/contact?source=edgeone-cli).