vite-plugin-deploy-oss 3.4.1 → 3.5.0

package/README.md

@@ -4,26 +4,16 @@
 [![npm downloads](https://img.shields.io/npm/dm/vite-plugin-deploy-oss.svg?style=flat-square)](https://www.npmjs.com/package/vite-plugin-deploy-oss)
 [![npm license](https://img.shields.io/npm/l/vite-plugin-deploy-oss.svg?style=flat-square)](https://www.npmjs.com/package/vite-plugin-deploy-oss)
 
-Upload Vite build artifacts to Aliyun OSS.
-[![npm version](https://img.shields.io/npm/v/vite-plugin-deploy-oss.svg?style=flat-square)](https://www.npmjs.com/package/vite-plugin-deploy-oss)
-[![npm downloads](https://img.shields.io/npm/dm/vite-plugin-deploy-oss.svg?style=flat-square)](https://www.npmjs.com/package/vite-plugin-deploy-oss)
-[![npm license](https://img.shields.io/npm/l/vite-plugin-deploy-oss.svg?style=flat-square)](https://www.npmjs.com/package/vite-plugin-deploy-oss)
-
 Upload Vite build artifacts to Aliyun OSS.
 
 ## Installation
 
-## Installation
-
 ```bash
 pnpm add vite-plugin-deploy-oss -D
 ```
 
 ## Quick Start
 
-## Quick Start
-
-It is recommended to control the deployment using environment variables to avoid accidental uploads during local builds.
 It is recommended to control the deployment using environment variables to avoid accidental uploads during local builds.
 
 ```ts
@@ -51,14 +41,69 @@ export default defineConfig({
 })
 ```
 
-Run build and deploy:
 Run build and deploy:
 
 ```bash
 DEPLOY_OSS=1 pnpm build
 ```
 
-## Configuration
+## Direct Upload
+
+If you only want to upload an existing directory, use the built-in CLI. This does not require Vite.
+
+Create a config file:
+
+```js
+// deploy-oss.config.mjs
+import { defineDeployConfig } from 'vite-plugin-deploy-oss'
+
+export default defineDeployConfig({
+  accessKeyId: process.env.OSS_ACCESS_KEY_ID || '',
+  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET || '',
+  bucket: process.env.OSS_BUCKET || '',
+  region: process.env.OSS_REGION || '',
+
+  outDir: 'dist',
+  uploadDir: 'H5/demo/prod',
+  configBase: 'https://example.com/H5/demo/prod/',
+
+  manifest: true,
+  failOnError: true,
+})
+```
+
+Run it from package scripts:
+
+```json
+{
+  "scripts": {
+    "deploy": "deploy-oss --config deploy-oss.config.mjs"
+  }
+}
+```
+
+Or run it with npx:
+
+```bash
+npx vite-plugin-deploy-oss --config deploy-oss.config.mjs
+```
+
+You can also call the upload API directly:
+
+```ts
+import { deployOss } from 'vite-plugin-deploy-oss/deploy'
+
+await deployOss({
+  accessKeyId: process.env.OSS_ACCESS_KEY_ID || '',
+  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET || '',
+  bucket: process.env.OSS_BUCKET || '',
+  region: process.env.OSS_REGION || '',
+  outDir: 'dist',
+  uploadDir: 'H5/demo/prod',
+})
+```
+
+`configBase` only changes URLs written to the manifest in direct upload mode. If you need Vite output paths to use the same base, keep using the Vite plugin during build.
 
 ## Configuration
 
@@ -69,6 +114,7 @@ DEPLOY_OSS=1 pnpm build
 | `accessKeySecret` | -                 | OSS access key secret.                                                       |
 | `bucket`          | -                 | OSS bucket name.                                                             |
 | `region`          | -                 | OSS region, e.g., `oss-cn-beijing`.                                          |
+| `outDir`          | `'dist'`          | Local directory to upload when using CLI or direct API.                      |
 | `uploadDir`       | -                 | Target directory in OSS to upload files.                                     |
 | `configBase`      | -                 | Modifies Vite's asset base path synchronously.                               |
 | `skip`            | `'**/index.html'` | Glob pattern for files to skip uploading.                                    |
@@ -88,34 +134,21 @@ DEPLOY_OSS=1 pnpm build
 - `configBase` affects both Vite's output asset paths and the URL addresses inside the manifest.
 - `alias` only affects the URLs generated inside the manifest; it does not change the actual upload destination on OSS.
 
-## Important Behaviors
-
-- If `open: true` and any of the required options (`accessKeyId`, `accessKeySecret`, `bucket`, `region`, or `uploadDir`) are missing, the build process will fail and terminate.
-- When `manifest` is enabled, all built files are uploaded automatically, and local build files are retained.
-- When `manifest` is enabled, `skip` defaults to an empty array and `autoDelete` is forced to `false`.
-- `oss-manifest.json` only tracks successfully uploaded files in the current build and does not include the manifest file itself.
-- `configBase` affects both Vite's output asset paths and the URL addresses inside the manifest.
-- `alias` only affects the URLs generated inside the manifest; it does not change the actual upload destination on OSS.
-
 ## Manifest
 
-Enable manifest:
 Enable manifest:
 
 ```ts
 vitePluginDeployOss({
-  // ...other options
   // ...other options
   manifest: true,
 })
 ```
 
-Customize manifest filename:
 Customize manifest filename:
 
 ```ts
 vitePluginDeployOss({
-  // ...other options
   // ...other options
   manifest: {
     fileName: 'meta/oss-manifest.json',
@@ -123,7 +156,6 @@ vitePluginDeployOss({
 })
 ```
 
-Manifest JSON example:
 Manifest JSON example:
 
 ```json
@@ -142,27 +174,47 @@ Manifest JSON example:
 
 ## Debugging
 
-## Debugging
-
-Enable `debug` to log the time taken for each key step during deployment, which helps locate bottlenecks:
 Enable `debug` to log the time taken for each key step during deployment, which helps locate bottlenecks:
 
 ```ts
 vitePluginDeployOss({
-  // ...other options
   // ...other options
   debug: process.env.DEPLOY_OSS_DEBUG === '1',
 })
 ```
 
-You can also run the playground command in the project:
 You can also run the playground command in the project:
 
 ```bash
 pnpm run build:test:debug
 ```
 
-## Notes
+## Local Upload Tests
+
+The playground includes three upload test paths:
+
+```bash
+# Vite plugin upload
+pnpm run build:test:deploy
+
+# Direct API upload
+pnpm run deploy:test:api
+
+# CLI upload
+pnpm run deploy:test:cli
+```
+
+All three commands use the same environment variables as the playground:
+
+```bash
+zAccessKeyId=xxx
+zAccessKeySecret=xxx
+zBucket=xxx
+zBucketAlias=https://example.com
+```
+
+The direct API test uploads `playground/__dist__` to `/test/__direct-api__/`.
+The CLI test uploads `playground/__dist__` to `/test/__direct-cli__/`.
 
 ## Notes
 
@@ -170,7 +222,3 @@ pnpm run build:test:debug
 - Keep `failOnError: true` for production builds to avoid completing the build/deployment pipeline when some files failed to upload.
 - Make sure you do not need the local build directory before enabling `autoDelete`.
 - The current version only supports ESM (`import` syntax). CommonJS (`require`) is not supported.
-- It is highly recommended to use environment variables instead of hardcoding sensitive credentials.
-- Keep `failOnError: true` for production builds to avoid completing the build/deployment pipeline when some files failed to upload.
-- Make sure you do not need the local build directory before enabling `autoDelete`.
-- The current version only supports ESM (`import` syntax). CommonJS (`require`) is not supported.