@ziuchen/tencent-scf-utils/README.md

A simple tool for deploying Tencent SCF

# @ziuchen/tencent-scf-utils

A simple tool for deploying Tencent SCF

## Install

```sh
npm i @ziuchen/tencent-scf-utils -D
```

## Usage

```sh
tscf -h
```

### Deploy Command

Deploy a directory to Tencent SCF:

```sh
tscf deploy ./dist -n my-function --region ap-shanghai --namespace default
```

`deploy` publishes a function version but never updates an alias.

### Release Command

Upload a prebuilt Layer ZIP to COS, publish its new version, bind it to `$LATEST`, deploy function code, and publish a function version:

```sh
tscf release ./dist \
  --layer-zip artifacts/dependencies.zip \
  --layer-name my-dependencies \
  --replace-layer-name old-dependencies \
  --layer-bucket my-layer-bucket-1234567890 \
  --layer-region ap-shanghai \
  --layer-prefix layers/my-function \
  --layer-runtime Nodejs24.11 \
  --layer-use-accelerate
```

The Layer object key is derived from the ZIP SHA-256 digest. The command preserves other Layer bindings and replaces `--replace-layer-name` in place; without that option, it replaces the matching new Layer name. `--layer-runtime` is always sent to SCF as the new Layer's compatible runtime. It does not update an alias.

For archives larger than 5 MiB, `release` uses COS high-level multipart upload with progress logging, retries, and per-request timeouts. The deployment identity needs `PutObject`, `InitiateMultipartUpload`, `ListMultipartUploads`, `ListParts`, `UploadPart`, `CompleteMultipartUpload`, and `AbortMultipartUpload` on the selected Layer object prefix.

### Layer Command

Build and upload a layer.zip with production dependencies:

```sh
tscf layer -p package.json
```

You can pass additional npm install arguments using the `--npm-args` option:

```sh
# Pass --ignore-scripts to npm install
tscf layer --npm-args "--ignore-scripts"

# Pass multiple npm arguments
tscf layer --npm-args "--ignore-scripts --no-audit --no-fund"

# Combine with layer-specific options
tscf layer -p custom-package.json --npm-args "--ignore-scripts --verbose"
```

The `--npm-args` option accepts a space-separated string of arguments that will be passed directly to the `npm install` command.

## Best Practice

tscf will load config from enviroment variables below:

```bash
TENCENTCLOUD_SCF_FUNCTION_NAME=xxxxxxxxxxxxxxxxxxxx
TENCENTCLOUD_SCF_REGION=ap-shanghai
TENCENTCLOUD_SCF_NAMESPACE=default
TENCENTCLOUD_SCF_SECRET_ID=xxxxxxxxxxxxxxxxxxxx
TENCENTCLOUD_SCF_SECRET_KEY=xxxxxxxxxxxxxxxxxxxx

TENCENTCLOUD_SCF_LAYER_NAME=my-dependencies
TENCENTCLOUD_SCF_REPLACE_LAYER_NAME=old-dependencies
TENCENTCLOUD_SCF_LAYER_BUCKET=my-layer-bucket-1234567890
TENCENTCLOUD_SCF_LAYER_BUCKET_REGION=ap-shanghai
TENCENTCLOUD_SCF_LAYER_PREFIX=layers/my-function
TENCENTCLOUD_SCF_LAYER_RUNTIME=Nodejs24.11
TENCENTCLOUD_SCF_LAYER_USE_ACCELERATE=true
```

`TENCENTCLOUD_SCF_LAYER_BUCKET` is the full COS bucket name. SCF's API receives the bucket name without the AppId suffix automatically.
Set `TENCENTCLOUD_SCF_LAYER_USE_ACCELERATE=true` to upload through COS global acceleration; it passes `UseAccelerate` to the SDK and uses the bucket's `cos.accelerate.myqcloud.com` endpoint.

Using with `@dotenvx/dotenvx`:

```json
{
  "scripts": {
    "deploy:scf": "dotenvx run -- tscf deploy ./dist"
  }
}
```

dotenvx will load enviroment variables from `.env` file for `tencent-scf-utils`.

## Development

This link `tencent-scf-utils` to global.

```sh
pnpm link -g
```

In other package, run this to link `tencent-scf-utils` locally.

```sh
pnpm link -g tencent-scf-utils
```

After modified code, you should rerun these command to make changes apply.

## Publish

Run the `Publish npm package` GitHub Actions workflow with `workflow_dispatch`.
It uses npm Trusted Publishing through GitHub OIDC and does not require an npm token in the repository.