Building results in entirely borked stylesheets

smileBeda commented 1 month ago

I cloned the repo
I installed NPM in the sass-js folder
I started npm in the same
I run the localhost (index file) and tested > all good but no icons
I run the same in the icons-font > half the bootstrap doesn't work (badges, col-breakpoint...), despite that it loads @import "bootstrap/scss/bootstrap"; just like the sass-js one.

What is the problem? The two examples should load the same Bootstrap, just one with, the other without fonts - or not? If not, how would one include the fonts in the full bootstrap bundle?

I am sorry if this has an obvious answer - however the obvious to me seems that if it loads @import "bootstrap/scss/bootstrap";... it should load the full bootstrap, yet it does not seem to.

julien-deramond commented 1 month ago

Hello there, Just re-executed the following manipulations:

git clone git@github.com:twbs/examples.git
cd examples/sass-js
npm i
npm run start

Then go to http://localhost:3000/

Screenshot 2024-06-07 at 14 51 53

The images/icons are well displayed, the offcanvas is well triggered when clicking on the button, etc.

With exactly the same commands in icons-font, the rendering is OK too.

What exact steps have you done on your side?

smileBeda commented 1 month ago

@julien-deramond - the exact same workflow, and I can see in your screenshot how no icons are shown or working. I refer to the  - which when inserted in the index won't work - rather than the SVGs as added in the default Index you are showing in the screenshot.

For example I used Search Icon  in the sass-js and that won't work.

As many other parts are also excluded in the sass-js (like pills, etc etc), what one ought to do is edit the styles.scss and include @import "bootstrap/scss/bootstrap"; instead of micromanaging the imports, and since that is supposed to import everything, remove all other imports in said file.

Done that, every feature of Bootstrap appears to work, however icons still won't show. Screenshot before including @import "bootstrap/scss/bootstrap";

Screenshot after including @import "bootstrap/scss/bootstrap";

In neither of both icons work.

Now, if you do the same in icons-font example, icons work, Badges too, since that example already uses @import "bootstrap/scss/bootstrap";

And as I compiled this one yesterday, neither did col-{breakpoints}, however, interestingly that one is solved as I recompiled today (thus probably due to me doing some sort of mistake yesterday)

However what clearly won't work in the fonts example is the whole JS relying part (accordions, etc). Thus again, it doesn't include the full bootstrap, even if we did @import "bootstrap/scss/bootstrap";

Now, I think I figured it out.

To get the full bootstrap (inclusive icons, js and everything else) this would be the minimal sass setup:

$bootstrap-icons-font-dir: "../node_modules/bootstrap-icons/font/fonts";
@import "bootstrap/scss/bootstrap";
@import "bootstrap-icons/font/bootstrap-icons";

And the minimal JS setup: import "../node_modules/bootstrap/dist/js/bootstrap.bundle.min.js";

And a minimal index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="css/styles.css">
    ....
  </head>
  <body>
    <script type="module" src="js/main.js"></script>
  </body>
</html>

with a package.json as follows:

{
    "name": "full-bs",
    "description": "Full Bootstrap CSS, JS and icons.",
    "version": "0.0.0",
    "private": true,
    "repository": "twbs/examples",
    "license": "MIT",
    "stackblitz": {
      "startCommand": "npm start"
    },
    "scripts": {
      "build": "npm run css",
      "css-compile": "sass --style compressed --source-map --embed-sources --no-error-css --load-path=node_modules scss/:css/",
      "css-lint": "stylelint scss/",
      "css-prefix": "postcss --replace css/styles.css --use autoprefixer --map",
      "css-purge": "purgecss --keyframes --css css/styles.css --content index.html --output css/styles.css",
      "css": "npm-run-all css-compile css-prefix css-purge",
      "server": "sirv --dev --no-clear --port 3000",
      "start": "npm-run-all --parallel watch server",
      "watch": "nodemon -e html,scss -x \"npm run css\"",
      "test": "npm-run-all css-lint css"
    },
    "dependencies": {
      "@popperjs/core": "^2.11.8",
      "bootstrap": "^5.3.3",
      "bootstrap-icons": "^1.11.3"
    },
    "devDependencies": {
      "autoprefixer": "^10.4.19",
      "nodemon": "^3.1.2",
      "npm-run-all": "^4.1.5",
      "postcss": "^8.4.38",
      "postcss-cli": "^11.0.0",
      "purgecss": "^6.0.0",
      "sass": "^1.77.4",
      "sirv-cli": "^2.0.2",
      "stylelint": "^16.6.1",
      "stylelint-config-twbs-bootstrap": "^14.1.0"
    }
  }

Did I get this right? It appears to work, doing some testing. Not sure though the package.json is correct as such (I basically merged the one from icons into the one of js). Sorry again if all this is fairly obvious to you, I am new to NPM.

Thank you for your patience!

smileBeda commented 1 month ago

There is something wrong with this. Sometimes, several of the things simply don't work. Example Center aligned text on all viewport sizes.

Then, I delete the files in /css/ and re-run npm (npm run start), at which point it works. Note that I always use the @import "bootstrap/scss/bootstrap"; to get full bootstrap.

It's as if the build wouldn't complete properly 50% of the time

smileBeda commented 1 month ago

????????

it uses the index.html to decide what to include and what not in the CSS?

I build the css
I check if things work by altering the index.html file (for example add an accordion, add some table, columns etc)
they do not work
rebuild css while those elements are present in index.html
things work????

I am at a loss to understand this.

Any hint as of what I might be doing wrong, is appreciated.

purge-css is the reason for that. Gosh. I guess now I got it, it appears to work...

@julien-deramond I feel like the example(s) would deserve a word on the issues I found while approaching the task?

how to compile a "complete" bootstrap
how to not run into purge-css issues, or in other words, if you use purge, then you must have your entire HTML in the index (or else) file to make sure it is not purged. With a multi-page application this is probably not the case, so you might want to omit purge in most cases...

julien-deramond commented 1 month ago

OK, I think I get it.

The sass-js example indeed voluntarily does not load all Bootstrap CSS as you can see in https://github.com/twbs/examples/blob/main/sass-js/scss/styles.scss because we want to show how you can override variables and how to fine-tune loading to avoid having a big CSS file in the end.

Based on this example, if you want to display more components or features, you'll have to add them one by one (see https://getbootstrap.com/docs/5.3/customize/sass/#importing), or import the entire @import "bootstrap/scss/bootstrap"; instead.

In this example, the images come from the last piece of Sass at the end of the file + https://github.com/twbs/examples/blob/main/sass-js/scss/_icon-list.scss:

https://github.com/twbs/examples/blob/103a176c0d749d9a017b85366f3b7ad0a1ece744/sass-js/scss/styles.scss#L88-L96

Here there's only one icon defined in SVG, it's not linked to Bootstrap icons.

The icons-font example wants to render Bootstrap Icons, so needs bootstrap-icons in the package.json. We don't want especially to show how to reduce the CSS bundle so Bootstrap Sass files are imported entirely with @import "bootstrap/scss/bootstrap";.

smileBeda commented 1 month ago

Right, I think I got that now.

Except, at least the icons example does also purge CSS which means you'll never get a complete Bootstrap from that run - unless of course you include each and every class available in the index.html I didn't see purge used on the sass-js example, which is probably why there most things worked.

I think this ought to be mentioned in the readme of each of the examples. It might be very obvious to someone very familiar with npm, but perhaps it can help newbies in future?

julien-deramond commented 1 month ago

For the icons-font README, it's mentioned as:

Include the Bootstrap Icons icon fonts via npm with Sass, Autoprefixer, and PurgeCSS.

For the other, it's not mentioned because it's not used.

But I can understand, while playing with several examples, how it can be difficult to understand.

I think this ought to be mentioned in the readme of each of the examples. It might be very obvious to someone very familiar with npm, but perhaps it can help newbies in future?

What would have helped you here? To mention in sass-js that we don't use PurgeCSS? It might also be a little weird.

smileBeda commented 1 month ago

In this case, I think what would've even avoided this very ticket is a phrase like something below:

On the fonts example:

Note! This example uses PurgeCSS and this means your build will ONLY include the css required to render your index.html page. ALL other CSS will be purged (css AND icons). Do NOT use this to build a complete bootstrap.

On the sass-js example:

Note! While this example includes a custom icon set, it does NOT include the Bootstrap Icons!

What (I think) really would've made it lovely

an example that helps starters like me compile a complete bootstrap (with icons, without PurgeCSS). I guess though it can also be seen as an advantage not to have that so people (like me) learn something on the way.

As for the issue here, it clearly is a non-issue. Thanks!

julien-deramond commented 1 month ago

Thank you, @smileBeda, for the feedback. I'll try to think about something to improve the READMEs based on your ideas. I let the issue open for now not to forget this action :)

twbs / examples