Writing Runtime Plugin
A Farm runtime plugin is a pure javascript object that define a set of hooks to enhance Farm runtime. Example:
Above it's a runtime plugin that supports HMR for Farm. Essentials:
- A runtime plugin entry file should
export
a default object that defines a set of hooks. e.gexport default <Plugin>{/*...*/}
name
is required to identify the plugin, make surename
is unique- A
hook
is a method that defined in the exported object.
See @farmfe/runtime-plugin-hmr for full implementation of above examples.
Caveat
You should make your runtime plugin as simple as possible. You SHOULD NOT:
- Use big dependencies from node_modules, this would make your farm plugin very large, it's really bad for performance.
- Use new features like
top level await
as these runtime related features are hard to polyfill for low level runtime.
It's really recommended to make sure your runtime plugin as small and simple as possible.
import.meta.xxx
will be compiled to module.meta.xxx
, you can append values
to module.meta
in runtime plugins to enhance import.meta
. For example, module.meta.hot = createHotContext(module.id, hmrClient)
makes import.meta.hot
available.
Conventions
A Farm runtime plugin name should be prefixed by farm-runtime-plugin
, e.g farm-runtime-plugin-xxx
.
Both plugin.name
and package name
(Only if you publish your plugin as a package) should be prefixed.
Using Runtime Plugins
Use compilation.runtime.plugins
to configure runtime plugins for your project:
You can configure runtime plugin item by 3 ways:
relative path
: Path that is relative toroot
, e.g./src/my-plugin1.ts
will try load plugin from<root>/src/my-plugin1.ts
.absolute path
: e.g/root/project/src/my-plugin2.ts
. (Absolute path should beC:\project\src\my-plugin2.ts
on windows).package name
: Farm will try load this package fromnode_modules
, e.g@scope/plugin-package-from-node-modules
.
Writing Runtime Plugins
Farm support loading .ts
file directly, so you can configure a .ts
file(or a package whose entry is a ts
file) in runtime.plugins
directly.
Create a Plugin
As we mentioned above, a Farm runtime plugin is a pure javascript object that define a set of hooks, you can just create a ts file like:
Then define hooks you need in the exported object:
Debug the Plugin
Configure the plugin you created in runtime.plugins
:
Then start the Farm project, this plugin will be injected in the runtime of output resources.
Publish the Plugin(Optional)
You can publish the runtime plugin to npm registry to share your Farm runtime plugin. Just create a package.json
like:
You can just export ts
file using "main": "src/index.ts"
.