Docs: fix scss autorecompile in dev mode

[MaxLardenois]

TL;DR: This PR makes it possible for Astro to compile Bootstrap SCSS while developing and see SCSS modification w/o the need to relaunch astro dev.

Description

Differentiates what CSS/SCSS we include in the Astro layouts between dev and prod. In dev mode this will add bootstrap SCSS directly instead of using plain <link> to compiled CSS from dist/

This is probably an incomplete solution, as we might be able to delete some "watch" scripts from package.json but I'm not sure about that. Also there might be an issue with RTL mode testing.
But I think it would be better to discuss and see what you think before going further.

Motivation & Context

While developing Bootstrap (or a fork), the documentation compilation via Astro is currently independent from the Bootstrap Sass compilation. SCSS is compiled (and watched) by a nodemon --watch script which put the resulting CSS files in dist folder but those new files are not picked up by Astro (even when reloading the page). *

This is especially an issue with the CSS because we do not see the result of SCSS modification directly, we need to relaunch astro dev server to re-read CSS from dist. This issue is probably the problem @mdo noted after the Astro migration (see the 4th item here #41380).

* I also tried to call copyBootstrap() in a dev hook in astro.ts but it did not work. Anyway in my opinion Astro should be responsible for SCSS compilation as far as it is used in the documentation. It does not prevent from having a more complete compilation process for publishing.

Type of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the contributing guidelines
• My code follows the code style of the project (using npm run lint)
• My change introduces changes to the documentation
• I have updated the documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed

Live previews

• https://deploy-preview-41574--twbs-bootstrap.netlify.app/

Related issues

#41380

[julien-deramond]

Thansk for this PR @MaxLardenois 🙏

I agree that for local development, a setup that recompiles everything is much better for live coding: it’s incredibly handy. That’s exactly what we’re aiming for, and as you mentioned, it was also pointed out by @mdo.

That said, this PR seems to introduce a twofold issue.

First, something seems inverted in the logic here: ScssProd likely should not load bootstrap.scss, since it's already included via the <Stylesheet> (CDN). So, Scss (used in local/dev) should compile and import bootstrap.scss. It's a small detail, but it affects the output significantly.

Right now:

main branch:

npm run docs ; cd _site ; http-server

When loaded:

• bootstrap.min.css : 232.33kB
• _slug.CJzIHdSW.css: 62.39kB

This branch:

When loaded

• bootstrap.min.css : 232.33kB
• _slug.C6b7iAa1.css: 296.31kB → it embeds both the docs styles and the entire Bootstrap CSS, which it shouldn’t.

However, and this is the issue I encountered initially, even if you apply the following change:

diff --git a/site/src/components/head/Scss.astro b/site/src/components/head/Scss.astro
index fc10fe75a..bf6b60ea0 100644
--- a/site/src/components/head/Scss.astro
+++ b/site/src/components/head/Scss.astro
@@ -2,6 +2,7 @@
 ---
 
 <style is:global lang="scss">
+  @import '../../../../scss/bootstrap.scss';
   @import '../../scss/docs';
   @import '../../scss/docs_search';
 </style>
diff --git a/site/src/components/head/ScssProd.astro b/site/src/components/head/ScssProd.astro
index a9ea10428..fc10fe75a 100644
--- a/site/src/components/head/ScssProd.astro
+++ b/site/src/components/head/ScssProd.astro
@@ -1,9 +1,7 @@
 ---
-
 ---
 
 <style is:global lang="scss">
-  @import '../../../../scss/bootstrap.scss';
   @import '../../scss/docs';
   @import '../../scss/docs_search';
 </style>

Astro still appears to import and compile the contents of Scss.astro, even when wrapped in a conditional like:

{!import.meta.env.PROD && (
  <Scss />
)}

I haven’t yet found the correct syntax to prevent Sass from being compiled when the condition is false; it seems Astro processes the SCSS regardless of runtime conditionals.

Hope I didn’t mix anything up while walking through all these cases 🙃😄

[MaxLardenois]

Thanks for the feedback, sorry for the wrong naming, I guess the heat wave is melting my brain.
For the problem with Astro still importing and compiling the Scss even in a conditional, I have the same issue. Probably a side-effect of their handling of styles elements. I may need to open an issue on their side.

[MaxLardenois]

Found some information here, not looking good for us though. withastro/astro#6563 : the bundling stage of Astro always extract and bundle all the CSS beforehand irrespective of which component will be in the page at the end.
Maybe we would need not to use Bootstrap build css for the doc in prod and go on with what Astro is outputting but I do not know if that would open us to some side effects.

[julien-deramond]

It needs more testing, but d4e21e2 could be a workaround. If not, I'll revert the commit :)

[MaxLardenois]

It needs more testing, but d4e21e2 could be a workaround. If not, I'll revert the commit :)

Worth a try but unsure it will work, a related issue: withastro/astro#9495

[julien-deramond]

Maybe it’s the heat, or maybe I've missed something, but so far, everything seems to be working fine.

Built Version (Prod)

npm i ; npm run docs ; cd _site ; http-server

Note: the generated slug file does not contain the contents of bootstrap.css 👌.

Can be checked also at https://deploy-preview-41574--twbs-bootstrap.netlify.app/.

Local Version (Development)

npm run start

Live updates work correctly:

1. Changing $primary to $yellow on-the-fly in scss/_variables.scss updates the browser rendering dynamically—Sass recompiles automatically.
2. Changing $bd-purple to #fd0 on-the-fly in site/src/scss/_variables.scss updates the browser rendering dynamically—Sass recompiles automatically.
3. Chaging --docsearch-primary-color to var(--bs-secondary-color) in site/src/scss/_search.scss updates the browser rendering dynamically—Sass recompiles automatically.

Feel free to confirm with the Boosted team to ensure everything behaves as expected on your side. I’ve only tested this on macOS.

[MaxLardenois]

Well that's a relief, will confirm tomorrow

[louismaximepiton]

Looks a bit tricky, but it works even better than before on my side. Great work in here !

[MaxLardenois]

This might be for the future but couldn't we get rid of the nodemon --watch jobs (or some of them) in dev?

[julien-deramond]

This might be for the future but couldn't we get rid of the nodemon --watch jobs (or some of them) in dev?

Yep sure, let's do it in a follow-up PR so that we can already merge this enhancement right away as it will be really useful for playing with #41512. I haven't tested out yet if we can get rid of all the watch npm scripts, or just some of them.