Package that exports a workerdEnvironmentProvider
function that can be used to set a Vite Environment to run code inside the workerd
runtime (via Miniflare
).
[!NOTE] Based on the vite@6.0.0-alpha.18 Environment API implementation.
The package exposes the workerdEnvironmentProvider
function that can be used to create new environments that run code inside the workerd runtime:
environments: {
myEnvironment: workerdEnvironmentProvider(),
}
this sets both a dev
and a build
environments (of course users can also process the workerdEnvironmentProvider
returned value to tweak the returned environments and/or use only one of them).
In the case of the dev environment, the environment instance is enhanced with an api
field that contains a getHandler
method, this is what can then be used to handle incoming requests (making sure that they are run inside workerd):
const handler = await devEnv.api.getHandler({
entrypoint: workerEntrypoint,
});
You can see usage examples here and here.
The package's code is structured in the following way:
src
├── debug-dumps
│ ├── ...
│ └── ...
├── worker
│ └── index.ts
├── codeTransformation.ts
├── index.ts
└── workerd-custom-import.cts
-
debug-dumps
can be ignored, it contains logic that we've used to dump logs and files that the environment encounters which we've used for debugging (this is off by default and can be enabled by setting theDEBUG_DUMPS
env variable) -
worker/index.ts
the actual entrypoint worker code that we run inside workerd, this includes the Vite Module Runner. It runs code by importing thegetHandler
'sentrypoint
argument. -
codeTransformation.ts
logic that we needed to include to make workerd correctly handles esm modules importing cjs ones, this will soon become unnecessary since changes in workerd are being worked on to fix the cjs issues -
index.ts
the package's index file, it exposes theworkerdEnvironmentProvider
function which creates the Vite Environments. In the case of the dev one, it creates one that spins up a miniflare instance that uses theworker/index.ts
transpiled code as is main module. -
workerd-custom-import.cts
this is a file that we use to implement interoperability between ems and cjs (external) code.
In the index.ts
code you can see a unsafeModuleFallbackService
this is a relatively new feature of workerd and miniflare that is instrumental here to enable the module runner's runExternalModule
method to function in workerd.
How this works is that when workerd tries to import a module and it can't find it in its module graph then it sends a request to the module fallback service providing the import details.
The module fallback service can then fetch and return the code for the module from the filesystem (in our case using DevEnvironment#pluginContainer#resolveId
to allow Vite to perform the correct module resolution).
Allowing the import inside workerd to them be resolved (and the workerd module graph updated).
Workerd supports cjs code but not as part of it's main/entrypoint module. So with a standard setup with a single esm module we wouldn't be able to import cjs modules. The way we workaround this limitation is by creating an additional CommonJS
module which exports a custom import function (which is actually implement by a plain dynamic import) such import can then import both cjs and esm modules, allowing us to have interoperability between the two.