Skip to content

DEVX-2073: Draft of external plugin model#10119

Merged
dxh9845 merged 23 commits intocloudflare:mainfrom
dxh9845:dherzig/try-miniflare-plugin-model
Sep 9, 2025
Merged

DEVX-2073: Draft of external plugin model#10119
dxh9845 merged 23 commits intocloudflare:mainfrom
dxh9845:dherzig/try-miniflare-plugin-model

Conversation

@dxh9845
Copy link
Copy Markdown
Contributor

@dxh9845 dxh9845 commented Jul 29, 2025

This implements an 'external plugin' model for extending Miniflare with Workers + Services outside of the Workers-SDK repo.

With this change, a user could specify the following configuration in an unsafe binding and have it emulated locally in a Worker simulator as existing plugins do.

{
        // The name of the binding made available to this Worker
        "name": "MY_INTERNAL_BINDING",
        "service": "some-unsafe-service-binding",
        // We expect the '@cloudflare/example-external-plugin' package
        // to expose a plugin with name 'name-of-plugin-exposed-by-plugin'
        // that will provide the service binding for 'account-services-staging'
        "dev": {
          "package": "@cloudflare/example-external-plugin",
          "plugin": "name-of-plugin-exposed-by-plugin"
        },
        "type": "service",
      }

This package would need to expose a module with the following function export:

import {pluginimplementation } from 'plugins/my-plugin-implementation'
export registerMiniflarePlugins() {
   return {
       'name-of-plugin-exposed-by-plugin': pluginImplementation
   }
}

Notably, this can now happen outside of the Workers-SDK repo, which is important for plugins that may have non-public or implementation details that are confidential or restricted for internal Cloudflare usage.

Context:

Internally at Cloudflare, there is a desire to have a more functional local development environment when using "unsafe" bindings that aren't available for public consumption. Examples of internal bindings may include "unsafe" service bindings between internal Worker services or accessing a Quicksilver binding that will never be publicly exposed to customers but is still highly relevant to internal developers.

This MR tries to allow internal developers at Cloudflare to write and publish Miniflare plugins outside of the workers-sdk repo. These plugins can then be published internally and dynamically imported and merged into Miniflare's existing plugin model.

This MR is in rough draft state and definitely needs comments from the Workers ANT team members to help point out inconsistencies or areas for improvement. Particularly, I'd love reviews and help with:

  1. Cleaning up the logic of passing unsafe bindings and validating their options in the miniflare.ts file. I believe there's a better, more strongly typed approach here but it will require a bit of thinking.
  2. Tests. I am slightly lost on how to best specify and mock these options in the existing Miniflare test structure.
  3. Opinions on the approach for specifying unsafe bindings via a dev section in wrangler.jsonc.
  4. Improving the documentation for the anatomy of a plugin. It has taken me a while to understand what each individual plugin method should be returning, even after reading CONTRIBUTING.md. For users who struggle with the intracacies of Miniflare and how it interacts with Wrangler, better comments could go a long way in helping folks contribute plugins.
  • Tests
    • Tests included - Need a hand with how to best test this!
    • Tests not necessary because:
  • Public documentation
    • Cloudflare docs PR(s):
    • Documentation not necessary because: not for public consumption
  • Wrangler V3 Backport
    • Wrangler PR:
    • Not necessary because: new features are not backported

@dxh9845 dxh9845 requested a review from a team as a code owner July 29, 2025 15:58
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Jul 29, 2025

🦋 Changeset detected

Latest commit: bc0dcdb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages
Name Type
miniflare Minor
wrangler Minor
@cloudflare/pages-shared Patch
@cloudflare/vite-plugin Major
@cloudflare/vitest-pool-workers Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@dxh9845 dxh9845 changed the title Dherzig/try miniflare plugin model DEVX-2073: Draft of external plugin model Jul 29, 2025
Copy link
Copy Markdown
Contributor

@petebacondarwin petebacondarwin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good. The general approach looks sound.

Regarding tests, I think we should be able to create a new fixture that can have its own local mock of an unsafe binding installed.

Then you can treat this like a playground during development, and also add tests that will run in CI.

@dxh9845 dxh9845 force-pushed the dherzig/try-miniflare-plugin-model branch 3 times, most recently from d7c1a47 to 5cafd4c Compare August 4, 2025 22:51
@github-project-automation github-project-automation bot moved this to Untriaged in workers-sdk Aug 5, 2025
@dxh9845 dxh9845 force-pushed the dherzig/try-miniflare-plugin-model branch 8 times, most recently from 695865c to 20bcc31 Compare August 7, 2025 16:45
Copy link
Copy Markdown
Contributor

@petebacondarwin petebacondarwin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few comments on the fixture...

@dxh9845 dxh9845 force-pushed the dherzig/try-miniflare-plugin-model branch 2 times, most recently from 1e81bd1 to c45b1e8 Compare August 13, 2025 16:07
@petebacondarwin petebacondarwin self-assigned this Aug 14, 2025
Copy link
Copy Markdown
Contributor

@petebacondarwin petebacondarwin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool - Samuel and I have lots of questions about the API and configuration approach.
But if this is passing tests in CI then perhaps we land this and iterate?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this needed for the Worker?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would there be additional "production" config here that should be merged with the dev config above?

@github-project-automation github-project-automation bot moved this from Untriaged to Approved in workers-sdk Aug 14, 2025
@petebacondarwin petebacondarwin force-pushed the dherzig/try-miniflare-plugin-model branch from c45b1e8 to ed855f1 Compare August 14, 2025 17:10
@dxh9845 dxh9845 force-pushed the dherzig/try-miniflare-plugin-model branch 2 times, most recently from bb412ca to a71ccf8 Compare September 3, 2025 15:57
@penalosa penalosa force-pushed the dherzig/try-miniflare-plugin-model branch from 5c2b039 to f4cc133 Compare September 8, 2025 16:11
@penalosa penalosa force-pushed the dherzig/try-miniflare-plugin-model branch from aaee766 to c5b0cb5 Compare September 8, 2025 16:21
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Sep 8, 2025

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@10119

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@10119

miniflare

npm i https://pkg.pr.new/miniflare@10119

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@10119

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@10119

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@10119

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@10119

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@10119

wrangler

npm i https://pkg.pr.new/wrangler@10119

commit: bc0dcdb

Copy link
Copy Markdown
Contributor

@penalosa penalosa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for all your work on this @dxh9845!

I think this is ready to land, and we can iterate going forward.

@dxh9845 dxh9845 merged commit 336a75d into cloudflare:main Sep 9, 2025
33 of 34 checks passed
@github-project-automation github-project-automation bot moved this from Approved to Done in workers-sdk Sep 9, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

4 participants