Boilerplate as NPM package

[hv-pul]

Summary

Currently, the way we start projects is to clone the boilerplate repository, detach it from git and create a fresh git repo for each project. This makes it hard to push changes and bugfixes in the repo to existing projects.

What if the boilerplate was an NPM package instead? This would allow easily distributing new features to existing projects.

Motivation

With the current solution it is hard to integrate bugfixes or new features from the boilerplate into existing projects. Individual projects might also make changes to core boilerplate functionality that never lands upstream in the boilerplate itself.

Having the boilerplate available as a package would fix this and make it explicit which version of the boilerplate a project is using. It would also make the separation between client-side (dependencies) and server-side (devDependencies) plugins more clear.

Detailed design

New projects would add hv-boilerplate as a dev-dependency. The dev-server/build would be run with npx boilerplate --dev or a similar solution. To create the necessary folder structure, a CLI-script similar to create-react-app/vue-cli could be used, or a simpler solution with a built-in script, something like npx boilerplate --bootstrap.

A boilerplate.config.js file should be used for simple configuration options, together with a plugin/hook architecture that allows:

• Extending the gulp pipeline
• Adding stageny plugins
• Adding custom styling to the styleguide
• Adding additional styleguide components and extending/overriding existing ones

Drawbacks

While I think it would be worth it, a change like this would not be without risks:

• The initial implementation is not trivial.
• We would lose flexibility for custom adjustments within specific projects (or have a higher effort to enable
• Future boilerplate iterations would need to take more care with not breaking existing projects, so a good version-naming scheme would be good as well as making sure projects always run on specific boilerplate versions.

Alternatives

It would also be possible to take a more fine-grained approach where only specific boilerplate functionality is exported into packages. We already have this with small things, e.g. focus-helper. It would be possible to do this e.g. for the JS/Module-management part and the styleguide as well, but at the moment we have a lot of connected functionality, so it might be better to move everything to a package – it could still be a monorepo-architecture if we want more control (similar to stageny).

[betabong]

I have often thought about this, and without going into too much detail, I would continue to favour flexibility over the obvious advantages (like easier initial setup). Updating would become a much more difficult approach, but also extending it would come with the thought: "will this break future updates"? I do like the approach to move some stuff into NPM packages, could make sense for both pipeline stuff (best without gulp dependency) and clientside scripts (ModuleManager ...). But it would require more effort and with a certain risk to break unintended things.

[hv-pul]

Updating would become a much more difficult approach Would it be? I think updating the boilerplate used in an existing version is pretty much impossible now – maybe only possible for you 😉 – for several reasons:

• There are a lot of implicit little dependencies and changes between different projects
• There are individual fixes and project-specific changes in boilerplate files used in projects, so when you want to copy over things from newer boilerplate versions you need to go through line-by-line to make sure things don't break

extending it would come with the thought: "will this break future updates"? See above – it already breaks future updates now. Even worse: when I fix something in a project, I can often not push the fix to other projects that might have the same issue.

[betabong]

I did not mean "updating projects based on the boilerplate", that's a not so funny task indeed. I meant: updating the boilerplate itself will become more difficult.

Also: what would we actually put in a "boilerplate package". Parts of it? (like tasks) Or the entire composition? But how then adapt to small changes from standard?

In the whole, I am not at all against putting parts of the boilerplate to NPM, like some build tasks, or parts of the JS library like ModuleManager, but I'm not too convinced it's worth the effort to go with your approach given the many customisations we apply to those projects. (which is also one of the reasons they're so hard to update). But hey, why not give it a shot.