docs: update getting started guide

[activescott]

This adds a few minor changes to fix the fact that the existing getting started steps actually fail to compile.

This PR contains a:

• bugfix
• new feature
• code refactor
• test update
• typo fix
• metadata update

Motivation / Use-Case

Currently if you follow the steps in the Getting Starting section of the readme you'll end up with a configuration that fails to compile. This makes a few minor changes to the steps such that, when followed, they will successfully compile. Additional details below.

Breaking Changes

There are no breaking changes.

Additional Info

Here are the steps in a terminal running the existing readme "Getting Started" steps:

scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npm install sass-loader sass webpack --save-dev

added 96 packages in 2s

12 packages are looking for funding
  run `npm fund` for details
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ echo 'import "./style.scss";' > app.js
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ echo '$body-color: red;

body {
  color: $body-color;
}' > style.scss
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ echo 'module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // Creates `style` nodes from JS strings
          "style-loader",
          // Translates CSS into CommonJS
          "css-loader",
          // Compiles Sass to CSS
          "sass-loader",
        ],
      },
    ],
  },
};' > webpack.config.js
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npx webpack
CLI for webpack must be installed.
  webpack-cli (https://github.com/webpack/webpack-cli)

We will use "npm" to install the CLI via "npm install -D webpack-cli".
Do you want to install 'webpack-cli' (yes/no): y
Installing 'webpack-cli' (running 'npm install -D webpack-cli')...

added 40 packages, and audited 137 packages in 1s

18 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
assets by status 0 bytes [cached] 1 asset

WARNING in configuration
The 'mode' option has not been set, webpack will fallback to 'production' for this value.
Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/

ERROR in main
Module not found: Error: Can't resolve './src' in '/Users/scott/src/activescott/junk/old-webpack-saas-loader'
resolve './src' in '/Users/scott/src/activescott/junk/old-webpack-saas-loader'
  using description file: /Users/scott/src/activescott/junk/old-webpack-saas-loader/package.json (relative path: .)
    Field 'browser' doesn't contain a valid alias configuration
    using description file: /Users/scott/src/activescott/junk/old-webpack-saas-loader/package.json (relative path: ./src)
      no extension
        Field 'browser' doesn't contain a valid alias configuration
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/src doesn't exist
      .js
        Field 'browser' doesn't contain a valid alias configuration
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/src.js doesn't exist
      .json
        Field 'browser' doesn't contain a valid alias configuration
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/src.json doesn't exist
      .wasm
        Field 'browser' doesn't contain a valid alias configuration
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/src.wasm doesn't exist
      as directory
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/src doesn't exist

webpack 5.88.2 compiled with 1 error and 1 warning in 154 ms
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ 

We can fix the errors with these steps (there are other ways obviously, but these steps are a minimal set of changes keeping in spirit with a "Getting Started" guide):

scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ mkdir src   
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ mv app.js src/index.js           
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ mv style.scss src/

scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npx webpack            
assets by status 132 bytes [cached] 1 asset
./src/index.js 23 bytes [built] [code generated]

WARNING in configuration
The 'mode' option has not been set, webpack will fallback to 'production' for this value.
Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/

ERROR in ./src/index.js 1:0-22
Module not found: Error: Can't resolve 'style-loader' in '/Users/scott/src/activescott/junk/old-webpack-saas-loader'
resolve 'style-loader' in '/Users/scott/src/activescott/junk/old-webpack-saas-loader'
  Parsed request is a module
  using description file: /Users/scott/src/activescott/junk/old-webpack-saas-loader/package.json (relative path: .)
    resolve as module
      looking for modules in /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules
        single file module
          using description file: /Users/scott/src/activescott/junk/old-webpack-saas-loader/package.json (relative path: ./node_modules/style-loader)
            no extension
              /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules/style-loader doesn't exist
            .js
              /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules/style-loader.js doesn't exist
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules/style-loader doesn't exist
      /Users/scott/src/activescott/junk/node_modules doesn't exist or is not a directory
      /Users/scott/src/activescott/node_modules doesn't exist or is not a directory
      /Users/scott/src/node_modules doesn't exist or is not a directory
      /Users/scott/node_modules doesn't exist or is not a directory
      /Users/node_modules doesn't exist or is not a directory
      /node_modules doesn't exist or is not a directory

webpack 5.88.2 compiled with 1 error and 1 warning in 169 ms

Install style-loader per the error and try again:

scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npm install -D style-loader

added 1 package, and audited 138 packages in 421ms

19 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npx webpack                
assets by status 132 bytes [cached] 1 asset
./src/index.js 23 bytes [built] [code generated]

WARNING in configuration
The 'mode' option has not been set, webpack will fallback to 'production' for this value.
Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/

ERROR in ./src/index.js 1:0-22
Module not found: Error: Can't resolve 'css-loader' in '/Users/scott/src/activescott/junk/old-webpack-saas-loader'
resolve 'css-loader' in '/Users/scott/src/activescott/junk/old-webpack-saas-loader'
  Parsed request is a module
  using description file: /Users/scott/src/activescott/junk/old-webpack-saas-loader/package.json (relative path: .)
    resolve as module
      looking for modules in /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules
        single file module
          using description file: /Users/scott/src/activescott/junk/old-webpack-saas-loader/package.json (relative path: ./node_modules/css-loader)
            no extension
              /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules/css-loader doesn't exist
            .js
              /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules/css-loader.js doesn't exist
        /Users/scott/src/activescott/junk/old-webpack-saas-loader/node_modules/css-loader doesn't exist
      /Users/scott/src/activescott/junk/node_modules doesn't exist or is not a directory
      /Users/scott/src/activescott/node_modules doesn't exist or is not a directory
      /Users/scott/src/node_modules doesn't exist or is not a directory
      /Users/scott/node_modules doesn't exist or is not a directory
      /Users/node_modules doesn't exist or is not a directory
      /node_modules doesn't exist or is not a directory

webpack 5.88.2 compiled with 1 error and 1 warning in 171 ms

Now install css-loader per the error and try again:

scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npm install -D css-loader

added 15 packages, and audited 153 packages in 811ms

22 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

scott@imacbiggie-eth: ~/src/activescott/junk/old-webpack-saas-loader$ npx webpack              
asset main.js 4.08 KiB [emitted] [minimized] (name: main)
runtime modules 698 bytes 4 modules
orphan modules 1.19 KiB [orphan] 1 module
modules by path ./node_modules/ 8.15 KiB
  modules by path ./node_modules/style-loader/dist/runtime/*.js 5.84 KiB
    ./node_modules/style-loader/dist/runtime/injectStylesIntoStyleTag.js 2.42 KiB [built] [code generated]
    ./node_modules/style-loader/dist/runtime/styleDomAPI.js 1.5 KiB [built] [code generated]
    ./node_modules/style-loader/dist/runtime/insertBySelector.js 1000 bytes [built] [code generated]
    ./node_modules/style-loader/dist/runtime/setAttributesWithoutAttributes.js 298 bytes [built] [code generated]
    + 2 modules
  modules by path ./node_modules/css-loader/dist/runtime/*.js 2.31 KiB
    ./node_modules/css-loader/dist/runtime/noSourceMaps.js 64 bytes [built] [code generated]
    ./node_modules/css-loader/dist/runtime/api.js 2.25 KiB [built] [code generated]
modules by path ./src/ 1.65 KiB
  ./src/index.js + 1 modules 1.22 KiB [built] [code generated]
  ./node_modules/css-loader/dist/cjs.js!./node_modules/sass-loader/dist/cjs.js!./src/style.scss 441 bytes [built] [code generated]

WARNING in configuration
The 'mode' option has not been set, webpack will fallback to 'production' for this value.
Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/

webpack 5.88.2 compiled with 1 warning in 589 ms

Now, below is a console session with the proposed changes:

scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ npm install sass-loader sass webpack style-loader css-loader --save-dev

added 112 packages in 3s

16 packages are looking for funding
  run `npm fund` for details
scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ mkdir src
scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ echo 'import "./style.scss";' > src/index.js
scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ echo '$body-color: red;

body {
  color: $body-color;
}' > src/style.scss
scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ echo 'module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // Creates `style` nodes from JS strings
          "style-loader",
          // Translates CSS into CommonJS
          "css-loader",
          // Compiles Sass to CSS
          "sass-loader",
        ],
      },
    ],
  },
};' > webpack.config.js
scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ npx webpack
CLI for webpack must be installed.
  webpack-cli (https://github.com/webpack/webpack-cli)

We will use "npm" to install the CLI via "npm install -D webpack-cli".
Do you want to install 'webpack-cli' (yes/no): y
Installing 'webpack-cli' (running 'npm install -D webpack-cli')...

added 40 packages, and audited 153 packages in 1s

22 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
asset main.js 4.08 KiB [emitted] [minimized] (name: main)
runtime modules 698 bytes 4 modules
orphan modules 1.19 KiB [orphan] 1 module
modules by path ./node_modules/ 8.15 KiB
  modules by path ./node_modules/style-loader/dist/runtime/*.js 5.84 KiB
    ./node_modules/style-loader/dist/runtime/injectStylesIntoStyleTag.js 2.42 KiB [built] [code generated]
    ./node_modules/style-loader/dist/runtime/styleDomAPI.js 1.5 KiB [built] [code generated]
    ./node_modules/style-loader/dist/runtime/insertBySelector.js 1000 bytes [built] [code generated]
    ./node_modules/style-loader/dist/runtime/setAttributesWithoutAttributes.js 298 bytes [built] [code generated]
    + 2 modules
  modules by path ./node_modules/css-loader/dist/runtime/*.js 2.31 KiB
    ./node_modules/css-loader/dist/runtime/noSourceMaps.js 64 bytes [built] [code generated]
    ./node_modules/css-loader/dist/runtime/api.js 2.25 KiB [built] [code generated]
modules by path ./src/ 1.65 KiB
  ./src/index.js + 1 modules 1.22 KiB [built] [code generated]
  ./node_modules/css-loader/dist/cjs.js!./node_modules/sass-loader/dist/cjs.js!./src/style.scss 441 bytes [built] [code generated]

WARNING in configuration
The 'mode' option has not been set, webpack will fallback to 'production' for this value.
Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/

webpack 5.88.2 compiled with 1 warning in 646 ms
scott@imacbiggie-eth: ~/src/activescott/junk/new-webpack-saas-loader$ 

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: activescott / name: scott willeke (78bafa1)

[alexander-akait]

You can use sass-loader without style-loader and css-loader, we have Examples to provide different cases

[activescott]

Fair enough, but the starting guide explicitly uses style-loader and css-loader in its webpack config, it just doesn't install them in the prior steps and that causes the getting started steps to not work. Seems those steps should work ideally, no?

I'm not trying to argue with you, just making sure it's not overlooked :) If I'm on the wrong track, happy to have you're recommendation on how to handle this. Just trying to leave things better than I found them.

If you want something changed let me know and I'll be happy to update this PR w/ master and make any changes.

[evenstensberg]

Ideally we need to have the readme examples as simple as possible. We can rather have explicit examples elsewhere.

[activescott]

Agreed. I'd like to help make the readme example work - I'm just not sure how to do that in a way the maintainers want. Let me know if there's some way that I can help here.

[alexander-akait]

Let's add an extra small section with npm i style-loader css-loader (or your prefered package manager) and describe that you will need them and why, just couple words to links on these loaders too