Document npm package support

[notramo]

There are several issues (both open and closed) in this repo, regarding npm package support.
What is the progress? Is it usable currently?
Please document it somewhere.

[jimafisk]

@notramo can you help me understand the desired workflow? Since Plenti generates the project scaffolding itself, I assume you'd want to install it as a global dependency and not a project dependency. So would NPM just be a means of downloading the binary onto your computer? If that makes folks life easier, we could probably add npm support using goreleaser. Does NPM have OS awareness and a way of downloading / executing the appropriate binary?

Some of the confusion may be Plenti's market positioning. The goal is to be more similar to Hugo than Gatsby. Ultimately I want to empower developers with base HTML/CSS/JS knowledge to build full fledged sites that can be edited by nontechnical users without having to wrestle with higher level concepts like auth, databases, server management, and complicated toolchains. Out of the box we have NPM scaffolding for Svelte and our router (Navaid), but I ultimately want to remove that. Ideally if you want to extend your system with NPM, you should be able to do that, but you should manage those tools outside of Plenti's build. That way if you want to bundle, transpile, etc, we'll get out of your way more and let you use whatever tools you want. I know that's a bit different than original discussion of downloading Plenti via NPM, but thought it might be useful to understand why we haven't fully embraced interoperability with the JS ecosystem.

Here's a reference to a previous discussion about NPM support: #135

[notramo]

This question originally is not about downloading Plenti via NPM, but using NPM packages in Plenti projects.
For example, to use FontAwesome icons, I would run npm i @fortawesome/free-solid-svg-icons, but then Plenti can't import the package.

I was reading something about not supporting modules, because Plenti uses raw V8 without module support. But in other comments it mentioned that some kind of support is present for ES modules. Unfortunately, it's hard to find out without reading all the issues and PR discussions, and following the development closely. You can't expect every new Plenti user to do it.

Maybe it's easier to give answer to exact questions, so I collected some of them:

• Does Plenti support NPM packages?
• If yes, but only partially, then what are the caveats?
• What are the reasons for lack of support (simply explained)? Is it a design limitation, meaning we can't expect it ever to be implemented, or simply haven't been coded yet?
• What should I do if I want to create a NPM package to be used in Plenti projects?

[jimafisk]

Ah sorry I misunderstood the question. Here are some details:

1. Plenti does support some NPM packages, but it's kind of spotty. This is one of the reasons that in the future it may be better to have people rig up there own NPM workflow so they can use the tools as they are intended
2. The main caveat is that the module needs to ship with ESM support. For instance Navaid, PocketBase, and Stripe all work. The challenge is that NPM allows maintainers to write the same thing in many different ways so there isn't a whole lot of standardization. ESM support can be specified by naming files with .ejs extensions, using a type declaration in the nearest package.json, using a module declaration in the nearest package.json. The other issue is if you want to do additional processing, like compiling Svelte components, you probably want to call out to your local nodejs for that.
3. Mostly that it hasn't been coded yet. I avoided bundlers originally and built Gopack (instead of using Snowpack) because those tools slowed down the build. Esbuild is likely a viable solution for introducing a true bundler, or potentially just using format from the transform API to create ESM if the module doesn't ship with it. I'm also not against removing the bundling capabilities and allowing people to introduce their typical NPM + webpack/rollup workflow so they can use the tools exactly how they want to.
4. If you create the NPM package using esm (imports/exports) instead of commonjs (require) and point to the entrypoint using the module key in your package.json it should work. If that gives you trouble, let me know.