Skip to content
Dropkit Docs

WordPress plugin

The dropkit WordPress plugin turns dropkit into a drop-in replacement for your site’s uploads directory. New uploads are pushed to dropkit the moment WordPress finishes writing them to disk, and every WordPress-generated thumbnail size is pushed as its own file too. Existing media can be migrated in one click. Works on every dropkit plan, free included, since no on-the-fly resize is required for registered sizes.

What it does

  • New uploads. The original is POSTed to /v1/upload on wp_handle_upload. After WordPress generates intermediate thumbnail sizes (thumbnail, medium, medium_large, large, plus any sizes a theme or plugin registered with add_image_size), each one is pushed to dropkit as a separate file. The returned ids and URLs are saved on the attachment as post meta.
  • Mirror or Move. Mirror keeps the local copy alongside dropkit. Move deletes the original plus every thumbnail once they have all landed on dropkit.
  • URL rewriting. wp_get_attachment_url, image_downsize, and the <img> srcset all return bare CDN URLs. Each size is its own immutable file, cache-friendly at the edge.
  • Bulk migration. Walk the existing Media Library, push every original plus its thumbnails. Batched, resumable, with live status.
  • Delete sync. Deleting an attachment in WordPress fires DELETE /v1/files/:id for every variant.

Install

  1. Grab dropkit-wordpress-1.1.0.zip from your dashboard at dash.dropkit.app/plugins.
  2. WordPress admin, Plugins, Add New, Upload Plugin, pick the zip.
  3. Activate.

Configure

  1. Open the dashboard, project, Keys, and create a server key (sk_live_...).
  2. In WordPress: Settings, dropkit, paste the key, Save.
  3. Upload a new image. Check the Media Library, the URL should now be on cdn.dropkit.app.

Options

OptionDefaultWhat it does
Server keyblanksk_live_... from your dropkit dashboard. Required.
StrategyMirrorMirror keeps local files alongside dropkit. Move deletes the original plus every thumbnail after they have all reached dropkit.
Rewrite URLsonWhen on, attachment URLs and srcset return dropkit CDN URLs. Off keeps WP’s own /wp-content/uploads/ URLs.
CDN basehttps://cdn.dropkit.appOverride if you configured a custom domain on a paid plan.
API basehttps://api.dropkit.appRarely changed.

Migrating existing media

The plugin never touches existing attachments on its own. Two paths:

  1. Leave them local. Only new uploads go to dropkit. Simplest, no risk to existing media.
  2. Run the migration tool. Settings, dropkit, Start migration. Walks every attachment that is not yet on dropkit, plus any that pre-date v1.1 and lack the per-size map. Pushes the original and every existing thumbnail in batches of five. Logs per-file status, updates a running total, remembers tombstones so subsequent runs skip files that can’t be uploaded (missing on disk, or over the 100 MiB cap). Safe to stop and resume.

Image transforms

For registered sizes the plugin pre-uploads each variant, so no ?w= query is ever needed and the browser hits a cache-friendly bare CDN URL. For ad-hoc array sizes (e.g. wp_get_attachment_image_src($id, [612, 408]) or a theme that asks for an exact pixel size that wasn’t registered with add_image_size), the URL falls back to a transform query (?w=&h=&fit=cover). On a paid plan dropkit resizes on the fly; on free the CDN serves the original. The fallback is rare in practice since most themes use registered sizes.

How many files is this?

A typical WordPress upload becomes around six files in dropkit: the original plus five built-in thumbnail sizes (thumbnail, medium, medium_large, large, 1536x1536). Themes that register additional sizes push more. Each thumbnail is a small fraction of the original’s bytes, but file counts and storage do add up.

Limits

  • 100 MiB per file. /v1/upload caps the Worker body at that. Files larger than 100 MiB stay local and the migration tool marks them as skipped. For very large files, use the SDK’s direct upload flow in your own frontend code.
  • Server key storage. The key lives in wp_options. Standard WordPress security applies: anyone with admin access to your site can read it.

Troubleshooting

  • Uploads work but URLs are still local. Check Settings, dropkit. Make sure “Rewrite URLs” is on.
  • 500 on upload. Usually a bad key. Verify with curl -X POST https://api.dropkit.app/v1/upload -H "authorization: Bearer sk_live_..." -F "file=@test.jpg".
  • Some thumbnail sizes are missing. Run the migration tool again; it picks up partial uploads and pushes whatever is missing.
  • Large files don’t upload. Anything over 100 MiB is skipped. The error_log entry reads [dropkit] file exceeds 100 MiB cap, skipped.

Uninstall

Deactivating from the Plugins screen only disables the hooks. Uninstalling (Plugins, Delete) runs uninstall.php, which drops the dropkit_settings option. Attachment meta is preserved so reinstalling picks up right where you left off. Files on dropkit are untouched. Delete them from the dashboard if you want them gone.

Source

Plugin source lives at plugins/wordpress/dropkit/ in the dropkit repo (private). The zip is generated at request time from that source, so what you download is always in sync with what’s shipped.