From 84a7ed632aaf514b70344c725424b4324a58a767 Mon Sep 17 00:00:00 2001
From: Neko Ayaka <neko@ayaka.moe>
Date: Wed, 26 Nov 2025 23:39:10 +0800
Subject: [PATCH] docs(vite-plugin-warpdrive): updated README.md

---
 packages/vite-plugin-warpdrive/README.md | 44 +++++++++++++++++-------
 1 file changed, 31 insertions(+), 13 deletions(-)

diff --git a/packages/vite-plugin-warpdrive/README.md b/packages/vite-plugin-warpdrive/README.md
index 3e4b6929b..5e9cb5a9f 100644
--- a/packages/vite-plugin-warpdrive/README.md
+++ b/packages/vite-plugin-warpdrive/README.md
@@ -24,11 +24,15 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   plugins: [
     WarpDrivePlugin({
-      prefix: 'remote-assets', // optional path prefix in the bucket
-      include: [/\.wasm$/i, /\.ttf$/i, /\.vrm$/i], // which assets to rewrite/upload
-      // includeBy: (file, ctx) => ctx.hostId?.includes('duckdb'),
-      // contentType: (file) => file.endsWith('.wasm') ? 'application/wasm' : undefined,
+      prefix: 'remote-assets', // path prefix in the bucket (default: remote-assets)
+      include: [/\.wasm$/i, /\.ttf$/i, /\.vrm$/i], // which assets to rewrite/upload (required)
+      // includeBy: (file, ctx) => ctx.hostId?.includes('duckdb'), // extra predicate with host info
+      // contentTypeBy: (file) => file.endsWith('.wasm') ? 'application/wasm' : undefined,
       manifest: true, // emit remote-assets.manifest.json in dist
+      delete: true, // delete local uploaded assets (default: true)
+      clean: true, // clean remote prefix before upload (default: true if provider supports it)
+      skipNotModified: true, // skip uploads if provider supports it (default: true)
+      // dryRun: true, // rewrite URLs/manifest only; skip cleaning/uploading
       provider: createS3Provider({
         endpoint: process.env.S3_ENDPOINT!,
         accessKeyId: process.env.S3_ACCESS_KEY_ID!,
@@ -43,13 +47,27 @@ export default defineConfig({
 
 ### Options
 
-- `prefix`: string path prefix for uploaded keys and URLs (e.g. `remote-assets` -> `remote-assets/assets/foo.wasm`).
-- `include`: array of regex or predicate functions to decide which assets to rewrite/upload.
-- `includeBy`: optional `(filename, ctx) => boolean` for finer control (ctx has `hostId`, `hostType`).
+- `provider` (required): object implementing `UploadProvider` (see below).
+- `prefix`: string path prefix for uploaded keys and URLs (default: `remote-assets`; e.g. `remote-assets/assets/foo.wasm`).
+- `include`: array of regex or predicate functions to decide which assets to rewrite/upload (empty array means nothing is rewritten).
+- `includeBy`: optional `(filename, ctx) => boolean` for finer control (`ctx` has `hostId`, `hostType`).
+- `contentTypeBy`: optional `(filename) => string | Promise<string | undefined> | undefined` resolver passed to `provider.upload`.
 - `manifest`: when true, emits `remote-assets.manifest.json` describing fileName/key/url/hostId/hostType/size.
-- `contentType`: optional `(filename) => string | undefined` resolver passed to the provider upload.
-- `logger`: optional logger ({ info, warn, error }) for custom logging sinks.
-- `provider`: any object implementing `{ getPublicUrl(key): string; upload(localPath, key, contentType?): Promise<void> }`.
+- `delete`: when true (default), delete uploaded local assets from disk after upload.
+- `clean`: when true (default), call `provider.cleanPrefix(prefix)` before uploading; skipped if no prefix or provider lacks `cleanPrefix`.
+- `skipNotModified`: when true (default), skip uploads if `provider.shouldSkipUpload` returns true.
+- `dryRun`: when true, rewrite URLs/emit manifest without cleaning or uploading.
+
+#### UploadProvider interface
+
+```ts
+interface UploadProvider {
+  getPublicUrl: (key: string) => string
+  upload: (localPath: string, key: string, contentType?: string) => Promise<void>
+  cleanPrefix?: (prefix: string) => Promise<void>
+  shouldSkipUpload?: (localPath: string, key: string) => Promise<boolean>
+}
+```
 
 ### createS3Provider
 
@@ -57,10 +75,10 @@ Light wrapper around `s3mini`. Required fields:
 
 - `endpoint`: full bucket URL (e.g. `https://s3.example.com/my-bucket`).
 - `accessKeyId`, `secretAccessKey`: credentials.
-- Optional: `region`, `requestSizeInBytes`, `requestAbortTimeout`, `publicBaseUrl` (override public URL base).
+- Optional: `region`, `requestSizeInBytes`, `requestAbortTimeout`, `publicBaseUrl` (override public URL base), `skipNotModified` (default: true; uses ETag/MD5 to skip uploads).
 
 ## How it works
 
 1. `renderBuiltUrl` returns the remote URL for matching assets while remembering the key/hostId/hostType.
-2. In `generateBundle`, local artifacts are uploaded via the provider.
-3. Optional manifest is emitted for traceability/debugging.
+2. `generateBundle` records assets to upload, emits the optional manifest, and leaves the local files in `dist/`.
+3. `closeBundle` optionally cleans the prefix, skips unmodified uploads when supported, uploads assets, and deletes local copies (unless `delete` is false).