Vite Plugin: Run Task

A simple plugin to side run a function during build and serve phases
of Vite, by implementing configResolved and handleHotUpdate hooks and
delegate follow up to a user defined task.

The user defined task is invoked whenever a change is detected in files/folder
matching a specified pattern.

> If your need is to run a shell command/process then this plugin is not for
> you. Checkout [awesome vite repo][1.1] to find plugins that may fit your bill.

The plugin was created to be able to build a CSS library using lightningcss
while using Astro for its documentation. It exists because the act of building a
main artefact (i.e the CSS library in this instance) should not be masked by the
quirks or capabilities of the framework used to document that artefact.

We think this idea rings true for a few [other use cases][1.2] where creating
well defined tasks to produce an artefact is better than hacking package.json
with additional steps that are either chained to execute in sequence or have the
developer issue additional commands to produce the artefact.

Quick start

$3

``bash
$ npm install @m5nv/vite-plugin-run-task
`

How to use it and why

To understand why we need this plugin, let's setup the stage to provide some
context.

We are developing kis.css library. We made a decision to use Astro to document
it and use kis.css itself to style the documentation. So, we want to see the
changes to the content of the documentation and changes to the style as we
develop kis.css, simultaneously.

This is a classic chicken and egg problem.

Astro does a beautiful job in hot reloading the content (it manages). We need a
way to hot build kis.css as we make changes to it in the src folder -
which as a reminder is our main character.

Here is how we solve it.

$3

`js
// kis-builder.js
import browserslist from "browserslist";
import { browserslistToTargets, bundle } from "lightningcss";

const browsers = browserslist(process.env.npm_package_browserslist);
const targets = browserslistToTargets(browsers);

export default function (context, event) {
let file, timestamp, server, command;
if (event == "hotUpdate") {
({ file, timestamp, server } = context);
command = server.config.command;
} else {
command = context.command;
timestamp = Date.now();
}

if (!(command === "build" || event === "hotUpdate")) {
return;
}

console.log(${event}, ${command}, ${file} | building kis.css);

let { code, warnings } = bundle({
targets,
filename: path.resolve("src/kis.css"),
minify: false,
});

if (code) {
let codeStream = fs.createWriteStream("public/kis.css");
codeStream.write(code);
codeStream.end();
}

if (warnings.length) {
console.table(warnings);
}

let followup = false;
if (event === "hotUpdate") {
// see vite hmrPayload.d.ts for event type and payload content
return {
type: "update",
updates: [{ path: "/kis.css", timestamp }],
};
}

return followup;
}
`

$3

`js
import { defineConfig } from "astro/config";
import runTask from "@m5nv/vite-plugin-run-task";
import task from "./kis-builder";

// https://astro.build/config
export default defineConfig({
site: "https://kiscss.github.io",
vite: {
plugins: [runTask({ watch: ["src/*/.css"], task })],
},
});
``

References

[1.1]: (Awesome Vite)
[1.2]: (Issue, unresolved - plugin to hot reload static assets)

- Vite Plugin API
- Lightning CSS
- Configuring Astro

---

Contributing

Contributions to enhance @m5nv/vite-plugin-run-task are welcome. Whether you
have suggestions, improvements, or bug fixes, please submit an issue or pull
request on our GitHub repository.

---

License

Distributed under the MIT License. See LICENSE for details.