vite-plugin-deploy-ftp 3.4.0 → 3.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +99 -95
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,16 +1,20 @@
|
|
|
1
1
|
# vite-plugin-deploy-ftp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Uploads the directory bundled by Vite to an FTP server. It is ideal for projects where you don't want to open FTP tools manually and repeatedly drag files to publish.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/vite-plugin-deploy-ftp)
|
|
6
|
+
[](https://www.npmjs.com/package/vite-plugin-deploy-ftp)
|
|
7
|
+
[](https://github.com/yulin96/vite-plugin-deploy-ftp)
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
6
10
|
|
|
7
11
|
```bash
|
|
8
12
|
pnpm add vite-plugin-deploy-ftp -D
|
|
9
13
|
```
|
|
10
14
|
|
|
11
|
-
##
|
|
15
|
+
## Quick Start
|
|
12
16
|
|
|
13
|
-
|
|
17
|
+
It is recommended to control whether to upload using environment variables. By default, local builds will not trigger uploading, and publishing will only happen when explicitly enabled.
|
|
14
18
|
|
|
15
19
|
```bash
|
|
16
20
|
# .env
|
|
@@ -52,7 +56,7 @@ export default defineConfig(({ mode }) => {
|
|
|
52
56
|
})
|
|
53
57
|
```
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
Enable upload when building:
|
|
56
60
|
|
|
57
61
|
```bash
|
|
58
62
|
# macOS / Linux
|
|
@@ -62,56 +66,56 @@ DEPLOY_FTP=1 pnpm build
|
|
|
62
66
|
$env:DEPLOY_FTP='1'; pnpm build
|
|
63
67
|
```
|
|
64
68
|
|
|
65
|
-
`FTP_PATH`
|
|
69
|
+
`FTP_PATH` can be a single directory:
|
|
66
70
|
|
|
67
|
-
```
|
|
71
|
+
```env
|
|
68
72
|
FTP_PATH=/public_html
|
|
69
73
|
```
|
|
70
74
|
|
|
71
|
-
|
|
75
|
+
Or multiple directories separated by commas:
|
|
72
76
|
|
|
73
|
-
```
|
|
77
|
+
```env
|
|
74
78
|
FTP_PATH=/public_html,/backup_html
|
|
75
79
|
```
|
|
76
80
|
|
|
77
|
-
##
|
|
78
|
-
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
| `open` |
|
|
82
|
-
| `autoUpload` |
|
|
83
|
-
| `failOnError` |
|
|
84
|
-
| `uploadPath` |
|
|
85
|
-
| `alias` |
|
|
86
|
-
| `singleBack` |
|
|
87
|
-
| `singleBackFiles` |
|
|
88
|
-
| `ftps` |
|
|
89
|
-
| `defaultFtp` |
|
|
90
|
-
| `concurrency` |
|
|
91
|
-
|
|
92
|
-
##
|
|
93
|
-
|
|
94
|
-
-
|
|
95
|
-
- `open: false
|
|
96
|
-
- `uploadPath`
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
- `singleBack: true`
|
|
100
|
-
- `autoUpload: false
|
|
101
|
-
-
|
|
102
|
-
-
|
|
103
|
-
|
|
104
|
-
##
|
|
105
|
-
|
|
106
|
-
-
|
|
107
|
-
-
|
|
108
|
-
- `uploadPath`
|
|
109
|
-
-
|
|
110
|
-
-
|
|
111
|
-
|
|
112
|
-
##
|
|
113
|
-
|
|
114
|
-
###
|
|
81
|
+
## Configuration Guide
|
|
82
|
+
|
|
83
|
+
| Options | Description |
|
|
84
|
+
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
|
|
85
|
+
| `open` | Whether to enable upload. It is recommended to control this via environment variables to avoid accidental uploads during routine builds. |
|
|
86
|
+
| `autoUpload` | Skip the "confirm upload" prompt. Recommended to set to `true` for automated deployments. |
|
|
87
|
+
| `failOnError` | Whether to make the build command fail if the upload fails. Recommended to set to `true` in CI/CD pipelines. |
|
|
88
|
+
| `uploadPath` | Upload directory paths. Supports string or array of strings (files will be uploaded to all specified directories). |
|
|
89
|
+
| `alias` | Public URL / domain. If provided, the accessible URL will be printed after uploading. |
|
|
90
|
+
| `singleBack` | Whether to back up only specific files instead of the entire directory. Usually backing up `index.html` is enough and much faster. |
|
|
91
|
+
| `singleBackFiles` | List of files to back up in single-backup mode, supporting sub-directories, e.g., `assets/app.js`. |
|
|
92
|
+
| `ftps` | Multiple FTP configurations. Used when you need to publish to multiple servers. |
|
|
93
|
+
| `defaultFtp` | The default server name when configuring multiple FTPs to reduce manual selection. |
|
|
94
|
+
| `concurrency` | Number of simultaneous file uploads. Keep default if the server connection is unstable. |
|
|
95
|
+
|
|
96
|
+
## Key Behaviors
|
|
97
|
+
|
|
98
|
+
- **Upload timing**: Uploads only after Vite finishes the build process.
|
|
99
|
+
- **Lazy evaluation**: When `open: false`, the plugin will not upload and will not validate FTP connection parameters.
|
|
100
|
+
- **Multiple paths**: When `uploadPath` is an array, the same build output will be uploaded sequentially to all specified paths.
|
|
101
|
+
- **Cross-product upload**: When combining multiple FTP servers and multiple paths, files are uploaded sequentially for every "Server × Directory" combination.
|
|
102
|
+
- **Backup before upload**: If the remote directory already contains files, the plugin will ask for confirmation or execute backups based on your configuration.
|
|
103
|
+
- **Selective backup**: When `singleBack: true` is configured, only files specified in `singleBackFiles` are backed up.
|
|
104
|
+
- **Manual confirmation**: When `autoUpload: false`, the plugin asks for manual confirmation in the CLI before proceeding.
|
|
105
|
+
- **Pipeline integration**: When `failOnError: true` and upload fails, the build command will exit with a non-zero code to block subsequent pipeline steps.
|
|
106
|
+
- **Module format**: This version only supports ESM (`import` syntax); `require` is not supported.
|
|
107
|
+
|
|
108
|
+
## Risks & Best Practices
|
|
109
|
+
|
|
110
|
+
- **Security**: Do not hardcode FTP usernames and passwords in `vite.config.ts`. Always use environment variables.
|
|
111
|
+
- **Safety**: Ensure you control the production deployments via environment variables (like `open: process.env.DEPLOY_FTP === '1'`) to prevent local routine builds from overwriting production files.
|
|
112
|
+
- **Multiple Targets**: Ensure all paths listed in `uploadPath` are intended targets, especially when uploading to production environments.
|
|
113
|
+
- **Backup Speed**: Full backups require downloading the remote directory and uploading a zip archive back. This can be slow if the remote directory is large.
|
|
114
|
+
- **Rate Limits**: If the remote FTP server is unstable or rate-limited, do not set `concurrency` too high.
|
|
115
|
+
|
|
116
|
+
## Examples
|
|
117
|
+
|
|
118
|
+
### Multiple FTP Servers
|
|
115
119
|
|
|
116
120
|
```ts
|
|
117
121
|
import vitePluginDeployFtp from 'vite-plugin-deploy-ftp'
|
|
@@ -146,7 +150,7 @@ export default {
|
|
|
146
150
|
}
|
|
147
151
|
```
|
|
148
152
|
|
|
149
|
-
###
|
|
153
|
+
### Multiple Upload Directories
|
|
150
154
|
|
|
151
155
|
```ts
|
|
152
156
|
import vitePluginDeployFtp from 'vite-plugin-deploy-ftp'
|
|
@@ -166,50 +170,50 @@ export default {
|
|
|
166
170
|
}
|
|
167
171
|
```
|
|
168
172
|
|
|
169
|
-
##
|
|
170
|
-
|
|
171
|
-
###
|
|
172
|
-
|
|
173
|
-
|
|
|
174
|
-
|
|
|
175
|
-
| `open` | `boolean` | `true` |
|
|
176
|
-
| `uploadPath` | `string \| string[]` | - | FTP
|
|
177
|
-
| `singleBack` | `boolean` | `false` |
|
|
178
|
-
| `singleBackFiles` | `string[]` | `['index.html']` |
|
|
179
|
-
| `debug` | `boolean` | `false` |
|
|
180
|
-
| `maxRetries` | `number` | `3` |
|
|
181
|
-
| `retryDelay` | `number` | `1000` |
|
|
182
|
-
| `showBackFile` | `boolean` | `false` |
|
|
183
|
-
| `autoUpload` | `boolean` | `false` |
|
|
184
|
-
| `fancy` | `boolean` | `true` |
|
|
185
|
-
| `failOnError` | `boolean` | `true` |
|
|
186
|
-
| `concurrency` | `number` | `1` |
|
|
187
|
-
|
|
188
|
-
###
|
|
189
|
-
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
| `name` | `string` | -
|
|
193
|
-
| `host` | `string` | -
|
|
194
|
-
| `port` | `number` | `21`
|
|
195
|
-
| `user` | `string` | -
|
|
196
|
-
| `password` | `string` | -
|
|
197
|
-
| `alias` | `string` | `''`
|
|
198
|
-
|
|
199
|
-
###
|
|
200
|
-
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
| `ftps` | `FtpConfig[]` | FTP
|
|
204
|
-
| `defaultFtp` | `string` |
|
|
205
|
-
|
|
206
|
-
### FtpConfig
|
|
207
|
-
|
|
208
|
-
|
|
|
209
|
-
|
|
|
210
|
-
| `name` | `string` | -
|
|
211
|
-
| `host` | `string` | -
|
|
212
|
-
| `port` | `number` | `21`
|
|
213
|
-
| `user` | `string` | -
|
|
214
|
-
| `password` | `string` | -
|
|
215
|
-
| `alias` | `string` | `''`
|
|
173
|
+
## Options Reference
|
|
174
|
+
|
|
175
|
+
### General Options
|
|
176
|
+
|
|
177
|
+
| Options | Type | Default | Description |
|
|
178
|
+
| :---------------- | :------------------- | :--------------- | :--------------------------------------------------------------------------- |
|
|
179
|
+
| `open` | `boolean` | `true` | Enable or disable the plugin. |
|
|
180
|
+
| `uploadPath` | `string \| string[]` | - | FTP destination path(s). Array values will upload sequentially to all paths. |
|
|
181
|
+
| `singleBack` | `boolean` | `false` | Enable single file backup mode. |
|
|
182
|
+
| `singleBackFiles` | `string[]` | `['index.html']` | List of file paths to back up when `singleBack` is enabled. |
|
|
183
|
+
| `debug` | `boolean` | `false` | Enable verbose debug logs and duration metrics. |
|
|
184
|
+
| `maxRetries` | `number` | `3` | Maximum retry attempts for connection/upload failures. |
|
|
185
|
+
| `retryDelay` | `number` | `1000` | Delay between retry attempts (ms). |
|
|
186
|
+
| `showBackFile` | `boolean` | `false` | Print backup file list to the console. |
|
|
187
|
+
| `autoUpload` | `boolean` | `false` | Bypass CLI confirmation prompt before starting uploads. |
|
|
188
|
+
| `fancy` | `boolean` | `true` | Enable stylish console UI outputs. |
|
|
189
|
+
| `failOnError` | `boolean` | `true` | Throw errors to fail the Vite build command on upload failure. |
|
|
190
|
+
| `concurrency` | `number` | `1` | Number of simultaneous file uploads. |
|
|
191
|
+
|
|
192
|
+
### Single FTP Configuration
|
|
193
|
+
|
|
194
|
+
| Options | Type | Default | Description |
|
|
195
|
+
| :--------- | :------- | :------ | :-------------------------------------------------------- |
|
|
196
|
+
| `name` | `string` | - | Identifier for the FTP configuration. |
|
|
197
|
+
| `host` | `string` | - | FTP host address. |
|
|
198
|
+
| `port` | `number` | `21` | FTP port. |
|
|
199
|
+
| `user` | `string` | - | FTP username. |
|
|
200
|
+
| `password` | `string` | - | FTP password. |
|
|
201
|
+
| `alias` | `string` | `''` | Public site URL alias used to format the final page link. |
|
|
202
|
+
|
|
203
|
+
### Multiple FTP Configuration
|
|
204
|
+
|
|
205
|
+
| Options | Type | Description |
|
|
206
|
+
| :----------- | :------------ | :----------------------------------------------- |
|
|
207
|
+
| `ftps` | `FtpConfig[]` | List of FTP server configurations. |
|
|
208
|
+
| `defaultFtp` | `string` | Default FTP config name to select automatically. |
|
|
209
|
+
|
|
210
|
+
### FtpConfig Object
|
|
211
|
+
|
|
212
|
+
| Options | Type | Default | Description |
|
|
213
|
+
| :--------- | :------- | :------ | :-------------------------------------------------------- |
|
|
214
|
+
| `name` | `string` | - | FTP configuration name (shown in selection prompt). |
|
|
215
|
+
| `host` | `string` | - | FTP host address. |
|
|
216
|
+
| `port` | `number` | `21` | FTP port. |
|
|
217
|
+
| `user` | `string` | - | FTP username. |
|
|
218
|
+
| `password` | `string` | - | FTP password. |
|
|
219
|
+
| `alias` | `string` | `''` | Public site URL alias used to format the final page link. |
|