Implement an asset pipeline for CSS, JavaScript, and images

[mattt]

Package Resources offer a way to load CSS and JavaScript from the module bundle (as opposed to our current approach of hard-coding CSS in a string literal).

Although it looks like the "Package Manager Extensible Build Tools" proposal is no longer being considered, I think we should be able to leverage webpack (or any of its myriad colleagues) to generate resources on an as-needed basis.

[mattt]

The same pipeline can be used to take our icons and inline them into our CSS

[kaishin]

@mattt This is the issue we discussed earlier, right?

[mattt]

@kaishin Indeed it is. Any thoughts / opinions?

[kaishin]

So from what I gathered so far, here's what we want to achieve:

1. Track the CSS (or other pre/post processor) sources in the repository.
2. Generate the CSS resources before or during build time (lint, minify, etc).
3. Since we can't load these at runtime (SPM limitation), we have to inject them during build time.

For 1, can we consider using Sass or PostCSS for taking care of things like auto-prefixing, polyfills, etc?

For 2, I guess webpack is a good place to start. Not my favorite in terms of overhead, but we can try to keep the config manageable.

For 3, I guess auto-generating the Swift file is one option. Any others that we can consider?

[kaishin]

Oh and we have also to decide how running webpack commands will fit in the workflow. Doing it manually is likely going to be error-prone.

[mattt]

Oh and we have also to decide how running webpack commands will fit in the workflow. Doing it manually is likely going to be error-prone.

Here are a few options to consider:

Option A: Add a call to webpack in our Makefile before we run swift build; this would guarantee consist results with derivative asset files, but would introduce npm as a hard dependency for (manual / non-bottled) installation.

Option B: Add webpack to a git pre-commit hook; this has the benefits of A without making npm a hard dependency (you only need it as a contributor, not a user). However, git hooks are inconvenient to setup.

Option C: Accept the possibility of stale assets in builds.

Right now, I'm towards Option C.

If you're working on the design of the HTML docs, you're almost certainly running webpack every time you make a change to see the result (perhaps automatically with a Guardfile or the like). When you're done working, and it comes time to commit the changes, any derivative files would be already generated — fresh and ready to go.

The one situation where this would fail, though, is with conflict resolution. If I merge a PR that changes a source asset, I may need to re-run webpack to refresh the results. I think it'd be possible to write a GitHub Action to do this automatically, but I'd defer that work until it's proven to be necessary.

[mattt]

So from what I gathered so far, here's what we want to achieve:

1. Track the CSS (or other pre/post processor) sources in the repository.
2. Generate the CSS resources before or during built time (lint, minify, etc).
3. Since we can't load these at runtime (SPM limitation), we have to inject them during build time.

For 1, can we consider using Sass or PostCSS for taking care of things like auto-prefixing, polyfills, etc?

Absolutely. I have a slight preference for PostCSS if it's convenient, but Sass is fine too.

For 2, I guess webpack is a good place to start. Not my favorite in terms of overhead, but we can try to keep the config manageable.

Actually, taking another look at the available options, I think Parcel looks a bit more palatable, at least for an MVP.

For 3, I guess auto-generating the Swift file is one option. Any others that we can consider?

Alternatively, we can just copy the files into the built documentation directory, and have our HTML point to where they'll be. Inlining CSS was something I did primarily to get beta 1 out the door.

[kaishin]

Absolutely. I have a slight preference for PostCSS if it's convenient, but Sass is fine too.

Cool, I can set that up. It's my preference too.

Actually, taking another look at the available options, I think Parcel looks a bit more palatable, at least for an MVP.

Let's go with Parcel for now. I looked at it a while back and it seemed nicer.

Alternatively, we can just copy the files into the built documentation directory, and have our HTML point to where they'll be. Inlining CSS was something I did primarily to get beta 1 out the door.

I prefer this option as well. Keeps things tidy at a negligible cost.

Right now, I'm towards Option C.

C it is. I was going to pitch A initially but you bring up good points about the hard npm dependency.

[kaishin]

@mattt Can you assign me to this issue? Not able to do that myself...