docs: Add information about how to customize PostCSS

[jaredcwhite]

With the PostCSS config that's landed in main, I'd like to reference useful documentation on how to configure it to support various features…nesting, custom media query variables, environment variables, etc. It looks like preset-env provides a lot of functionality out of the box, but it probably requires changing the "stage: 3" config to something else or adding an allowlist of desired features. There may be additional plugins out there that are popular as well we could link to.

ref: http://preset-env.cssdb.org/ https://github.com/csstools/postcss-preset-env#features https://github.com/csstools/postcss-preset-env/blob/master/src/lib/plugins-by-id.js#L36

[andrewmcodes]

I agree this could be helpful but think we need to draw a line at regurgitating the already very thorough postcss docs.

My proposal would be to create “recipes/cookbooks” instead of arbitrary links. A recipe would be a description of how to accomplish an end goal vs blindly including things.

Ex: —-

CSS Minification via cssnano

Prerequisites:

• PostCSS is installed
• postcss-loader is installed and configured for the env

Directions:

Make the following change to your PostCSS Config file:

+ const cssnano = require("cssnano")({
+    preset: "default"
+ });

module.exports = {
    plugins: [
        // ...
        // This should be at the end of your plugin list
+        ...(process.env.NODE_ENV === "production" ? [cssnano] : [])
    ]
};

Additional Resources

• https://cssnano.co/

[andrewmcodes]

Sorry for formatting, I’m on my phone.

But doing something in this format would answer How? vs begging the user to ask Why?

• why would I need postcss import
• why would I need to do x y z

Telling them how to accomplish a task will reduce decision fatigue, be easier to search for, and could give us a nice template for other things that could be recipes like How to add Tailwing.

Thoughts?

I will re look at this on a computer and fix any typos or weirdness that occurred btw 😬

Edit: Also realized it would be good to site my sources. I specifically realized this would be a helpful construct after seeing what Gatsby does (https://www.gatsbyjs.com/docs/recipes/) but the concept of a cookbook is pretty popular in Rails. I like recipe a bit better bc it implies that these are small in scope and modular. Seeing this usage of it is what pushed me to like it over recipe. https://chasem.co/notes/css-recipes

[jaredcwhite]

I'm tracking with everything you said and I love your recipie example for cssnano. Not sure how to slot it into the current docs structure, but that's merely an implementation detail. Let's do it!

[ayushn21]

Just thinking out loud; how about we bundle in automations for some common PostCSS configurations into Bridgetown? So instead of documenting "how" a user could do something and describing the config; we could just say "run this command".

So for a Tailwind configuration: it could be bridgetown new --use-postcss and then bridgetown install:tailwind or something like that.

This would simplify the docs and it'd be really easy for the user to get started with a configuration of their choice. We could potentially also include an "omakase" configuration of PostCSS which includes things like nesting, mixins and stuff but no reliance on a monolithic framework or CSS processor.

I got this idea from rails webpacker:install:stimulus so conceptually I'm thinking along those lines.

[jaredcwhite]

That sounds good to me. We could add an official install command to bridgetown, and it would pull from a list of first-party automations. So bridgetown install tailwind would run that particular automation. There's some other stuff in the pipeline that would benefit from this approach. (Under the hood it can just use the existing apply infrastructure so should be pretty easy to implement.)

[andrewmcodes]

@ayushn21 @jaredcwhite this may be of some interest to you @btrb/configs

I have already begun work on a postcss plugin but stopped after some internal bikeshedding about which plugins should and shouldn't be included and getting annoyed that I couldn't get font-magician to cooperate.

Here is a searchable catalog of PostCSS plugins I stumbled on as well: postcss.parts

[ayushn21]

Thanks @andrewmcodes. I'm not sure how commonly used the prettier and babel configs would be; but we could definitely include them as first party automations if we think it'd be useful.

So far I've created a Tailwind automation to include and copied over everything from http://github.com/bridgetownrb/automations.

I think getting consensus on a PostCSS setup will take a bit of time and discussion but I reckon we could include one in the near future.

I'm nearly done with my PR to add a configure command along with first-party automations mentioned above. I think the best approach would be to merge that first and then discuss and finalise a Bridgetown recommended PostCSS setup and then implement and include that as a bundled configuration.

[ayushn21]

Now that the configure command is in main; I think we should compile a recommended list of PostCSS plugins and write a configuration to set them up.

If there are any plugins we like but they don't quite fit with our recommended setup, we could just list them in the docs (in the description of the PostCSS config) saying "These are some other plugins that we recommend:"

After a (very) brief look on postcss.parts, these are the plugins I'm initially proposing for inclusion:

• import
• nested
• mixins
• custom-media
• cssnano

What do you think?

[ayushn21]

Thinking a bit more about @andrewmcodes recipes/cookbooks idea; I wonder if it'd still be worth doing something like that?

It could be useful to educate users on how to configure and use PostCSS by explaining how to set up some plugins. I don't think it's practical to include a configuration for every individual plugin we like.

Not sure, I'm a bit torn! Thoughts??

[andrewmcodes]

Personally I'm not super in favor of it because I fear it'll make the docs harder to maintain. There are several factors that contribute to whether these plugins will work or not like order in the config, environment, and versions.

I've written the instructions for a few but haven't gotten around to doing anything with them.

[ayushn21]

All good points. I've lost count of the number of times I followed a configuration guide in the docs of something or other and failed to get the thing working 😂

So shall we just bundle a "recommended" PostCSS configuration that overwrites the postcss.config.js (So we control the order of plugins/versions etc) and draw the line at that then?

[jaredcwhite]

The most fancy-pants I've gotten so far with PostCSS is something like this:

module.exports = {  
  plugins: {
    'postcss-flexbugs-fixes': {},
    'postcss-color-adjustment': {},
    'postcss-preset-env': {
      autoprefixer: {
        flexbox: 'no-2009'
      },
      stage: 4,
      features: {
        'nesting-rules': true,
        'custom-media-queries': true
      }
    }
  }
}

but by no means do I feel like that should be a default setup per se. I also hesitate to get too far into the documentation weeds on this as PostCSS is only tangentially related to Bridgetown. I think as long as we have a basic default that seems reasonable and then link people to the most actionable PostCSS config docs elsewhere, we've done our job.

[jaredcwhite]

• import
• nested
• mixins
• custom-media
• cssnano

Seems a good list. Some (all?) of these are available out of the box with postcss-preset-env, so it's just a matter of configuring. I also like the color adjustment one (requires an explicit npm/yarn install):

https://github.com/mpeutz/postcss-color-adjustment

[ayushn21]

Some (all?) of these are available out of the box with postcss-present-env

Ah! I haven't looked into postcss-present-env closely enough to see how deep the rabbit hole goes! I'll take a closer look soon.

The color adjustment plugin looks awesome! I'll have a play around and put something together soon.