feat: add support for kirby serve w/ HMR plugin

[jonaskuske]

fix #17

depends on getkirby/kirby#4541

To do:

• verify asset imports work in serve mode
• verify env vars (default and from .env) work in serve mode
• verify default aliases and kirby.config.js#alias work in serve mode
• verify postcss transforms work in serve mode
• enable reload for PHP changes (configurable?)
• CLI help texts in cli-start.ts
• investigate slowdown caused by kirbyup config (done, separate issue: Extremely slow starts if kirbyup.config exists #19)
• investigate slow server response times with vite-plugin-live-reload
• Update README
• check process SIGINT/exit handler sometimes not working
• Add tests

[johannschopplich]

This is the greatest contribution to a project of mine. Thank you so much, digging into this feature. Stunning work.

Regarding the docs

Since the README got pretty verbose by now, I will migrate to VitePress soon. We can then add a dedicated section to the serve feature.

Edit: Once I've set it up, we can add the documentation for serve

Regarding reload for PHP changes

We could introduce a CLI option like kirby-dir to let the user point us to the right direction, while also checking for something like parentPath.endsWith('site/plugins') to somewhat detect the environment. Most plugin devs probably develop right from their plugins folder of their Kirby instance. Could be activated by default with an opt-out, I think.

---

I haven't yet tested the feature thoroughly.

[jonaskuske]

Status update:

✅ Verified that .env, alias and PostCSS features work as intended in serve mode.

👀 Assets are a different beast however:

• Vite inlines all imported static assets in library mode, so the JS and CSS files get huuuuuge if you import any images, fonts etc.. This isn't serve related and definitely a separate issue. (see: add an option to not to inline assets in library mode when format is 'es' vitejs/vite#4454 library mode can't extract static assets vitejs/vite#3295 feat: build library new option - emitAssets vitejs/vite#5028)

• For kirbyup serve, we must specify the server.origin option in the Vite config, otherwise assets are requested from the Kirby/PHP server and error out.

  • This means we need to hardcode the port kirbyup uses so we can specify it in server.origin. A bit unfortunate, but not a dealbreaker, I think?
  • vite-plugin-vue2 appears to have a bug where URLs referenced from the template (img src="../...") don't properly include the origin - a slash is missing (http:/...) so the URL isn't treated as absolute and asset loading breaks

So yeah, the asset story is a bit unclear. I can think of a couple ways to fix the behavior in serve mode (fix plugin-vue2 so assets can be loaded from the Vite server directly, or set a base so assets can be imported from Kirby's site/ or media/ directories and the request doesn't hit Vite) – but even with these fixes in, the behavior in build mode is still terrible, and I don't see an easy way to fix it, as it even applies to assets in the public/ dir.

Aside from the whole assets endeavor, I'm currently investigating some possible issues with server closing and server response times, which seem to be affected by the existence of a kirbyup.config.js and also by vite-plugin-full-reload 🤔

[jonaskuske]

Submitted the fix so that server.origin doesn't break asset URLs in vuejs/vue#12732 :)

[johannschopplich]

👀 Assets are a different beast however

Most of the Kirby Panel plugins don't actually include custom assets, as far as I know. As relevant as a bloated bundle is, I think it's neglectable if you can't make it working. 🙂

Aside from the whole assets endeavor, I'm currently investigating some possible issues with server closing and server response times, which seem to be affected by the existence of a kirbyup.config.js and also by vite-plugin-full-reload 🤔

I'm completely fine tracking that in a separate issue!

Submitted the fix so that server.origin doesn't break asset URLs in vuejs/vue#12732 :)

You're even spotting issues in Vue 2 itself. Great, man. 👏

[jonaskuske]

Most of the Kirby Panel plugins don't actually include custom assets, as far as I know. As relevant as a bloated bundle is, I think it's neglectable if you can't make it working. 🙂

Alright, so I take it that vuejs/vue#12732 is non-blocking - we can move forward with this PR, assets in dev break and if the Vue PR is merged we simply need to update @vue/compiler-sfc and it should work. :)
The dev server needs a fixed port for the asset URLs, which defaults to 5177 and can be set via the -p, --port CLI flag.

I'm completely fine tracking that in a separate issue!

Found the issue with vite-plugin-live-reload: ElMassimo/vite-plugin-full-reload#9 (and added a workaround)

---

So, everything should be working now I think!

As for docs, I'd suggest adding the new command and its options to the README for now, switching to VitePress sounds like material for another PR.

Then the only open question would be how (and how thoroughly) to test this. Apart from that, HMR support should be ready and we just need getkirby/kirby#4541 to move forward! :)

[johannschopplich]

Alright, so I take it that vuejs/vue#12732 is non-blocking - we can move forward with this PR, assets in dev break and if the Vue PR is merged we simply need to update @vue/compiler-sfc and it should work. :)
The dev server needs a fixed port for the asset URLs, which defaults to 5177 and can be set via the -p, --port CLI flag.

It is non-blocking. Sounds good.

Another approach, would be to use pnpm patch to patch the package until the issue is resolved upstream. We have to patch @vitejs/plugin-vue2 currently as well to ensure it's working with npx. Without patching, the Vite plugin will not work ran from the global _npx dir.

Adding another fix for the Vue compiler would be fine by me. Otherwise, we just wait. Maybe it's not worth the time patching it now. What do you think?

Found the issue with vite-plugin-live-reload: ElMassimo/vite-plugin-full-reload#9 (and added a workaround)

Good catch!

So, everything should be working now I think!

Seems like it. Again, amazing work!

As for docs, I'd suggest adding the new command and its options to the README for now, switching to VitePress sounds like material for another PR.

👍 I don't have the resources to migrate to VitePress at the moment and don't want to rush it. A section in the README should do the job just as fine.

Then the only open question would be how (and how thoroughly) to test this. Apart from that, HMR support should be ready and we just need getkirby/kirby#4541 to move forward! :)

I'm unsure how to debug as well. In an older version of kirbyup I used npx tsx cli.ts to run the tests. It may be suitable for the serve tests if some kind of output artifact is readable and reproducible.

[jonaskuske]

Another approach, would be to use pnpm patch to patch the package until the issue is resolved upstream.

Already tried that, but it doesn't work. :(
It only works for plugin-vue2 because it is inlined into the built kirbyup, so downstream users don't load it from their node_modules but use the shipped and patched copy. But inlining @vue/compiler-sfc doesn't work, it has a ton of optional dependencies which rollup transforms into sync imports so unless stylus, velocityjs etc. all are installed, it won't execute.

[johannschopplich]

Dang, you're right, I had to inline @vitejs/plugin-vue2 for the fix to be effective… :rocket-down-emoji:
Doesn't make sense for the Vue SFC Compiler. Non-blocking it is, still. When your fix is approved, we can release a minor update. 🙌

[johannschopplich]

One more optional task: Adding your name to the license file and README, since your contribution will be an impactful one. Feel welcome to do so!

[johannschopplich]

We can add automated tests later. 🙂