Sp-dev-docs: Separation of SASS to CSS conversion and CSS Modules in build task

[StfBauer]

Category

• [x] Question
• [ ] Typo
• [x] Bug
• [ ] Additional article idea

Expected or Desired Behavior

The files should only be generated when the file is named with the extension module.scss and not with anything else.

In this screenshot, the module.scss was mistyped by modules.scss

Observed Behavior

Whenever you create a new file with the extension .scss the following files get generated.

test.scss
This file contains the compiled style sheets.
test.d.ts
Remains empty because it is not using CSS Modules but will be will be generated anyway. This empty file can be used in web part or extension.
test.scss.js
This file contains a requrie statement and a link to an source map:

/* tslint:disable */
require('./test.css');
/* tslint:enable */ 

//# sourceMappingURL=test.scss.js.map

test.scss.js.map
This file contains an SCSS source that doesn't work at all because other than taking the styles directly from the folder those were embedded directly on the page.

All it seems like that the compilation from SCSS to CSS and the CSS Module compilation are chained together. The last one fails silently but still generates some files that are not needed because they do not work.

Trough the separation of SCSS build chain and CSS Modules build chain those additional files can be avoided and better handled in case of error handling.

In addition, the source maps should be fixed. Currently, it is pretty hard to debug style issues because the files do not reference in the source directly and the styles are embedded on the page.

Steps to Reproduce

1.) Create a new project of type extension or web part.
2.) Add additional files with only .scss or scss.modules extension.
3.) Check generated files in /lib folder.
4.) Check Browser if the style information leads to the origin file or the place on the page.

[jonathanhotono]

I raised the sourcemap issue on #479 and still haven't got any news about it. It's getting increasingly harder now to debug styling issues on big projects.

[StfBauer]

Sadly without going to the folder ./lib it is impossible.

[nickpape]

Let's look at a scenario with a sample HelloWorld.scss file.

In this case, we generate a single file in the src/ folder:

• HelloWorld.scss.ts - this file allows you to add a require('./HelloWorld.scss') in your source files. This file essentially only exists so that the thing you add a require() for also exists in your src/. It is perfectly equivalent to require('./HelloWorld.css') although that file will not exist in the src directory.

In the lib/ folder you end up with:

• HelloWorld.scss.js - this is the compiled version of the TS file. All it has is a simple require statement.
• HelloWorld.scss.js.map - the sourcemap, although (as you pointed out) it isn't super helpful since the load-styles webpack loader is actually injecting extra JS that loads the styles.
• HelloWorld.scss.d.ts - an empty typings file. It is empty since HelloWorld.scss.ts doesn't export anything. This is the side-effect of adding any TypeScript file that doesn't have any exports.
• HelloWorld.css - the actual compiled CSS output.

In the module.scss-world, the generated HelloWorld.scss.ts file actually has a bunch of exports that let you know what the classnames were mangled to. This in turn makes the compiled HelloWorld.scss.d.ts actually have a lot of useful exports.

Proposal

In my opinion, rather than completely doing away with generating HelloWorld.scss.ts, it should have the same output as what a module.scss file would do, sans the name-mangling.

This would allow you to create a regular HelloWorld.scss file such as:

.helloWorld {
  .container {
    max-width: 700px;
    margin: 0px auto;
  }
}

And import like so:

import * as styles from './HelloWorld.scss';

The generated HelloWorld.scss.ts file would be similar to a module.scss, sans the name mangling:

/* tslint:disable */
require('./HelloWorldWebPart.css');
const styles = {
  helloWorld: 'helloWorld',
  container: 'container'
};
export default styles;

@StfBauer, what do you think about this idea?

[nickpape]

Also, @StfBauer @jonathanhotono we will be looking at the sourcemaps issue shortly.

[StfBauer]

@nickpape-msft
Your solution would be possible but I would not use it. From my point of view only module.scss the extension should be used and the responsible gulp task should not convert .scss at all.

The problem when I add code for example in the header or footer section and the CSS classes and ID's run at global scope. This means that I can influence the overwrite even styles that will be used later in the page. CSS Module, on the other hand, reduces the possibility that the same class name will be used by other web parts. other extensions and so on.

I can always switch to the :global scope inside the module.scss file.

In case I have stored a file in my extension with the name HelloWorld.scss no conversion should happen at all. Instead, an error should be raised that says something like:

You can only use module.scss for your extension styles

Here are some cases and solutions:

I have a file named .css or .scss that I like to use in my extension

Solution 1
Name the file _mypartialfile.scss in the .module.scss file please @import the partial file.
This way the SASS compiler will embed the external file anyway, but won't convert it to the '/lib' folder.

Solution 2
Copy the content of the SCSS, CSS file directly inside the module.scss

This makes way safer extensions, at least it reduce the possible problems.

One this: If you looking forward to support pure .scss the I won't have any use for 'require' and 'import' in the TypeScript code anyway.

[nickpape]

In case I have stored a file in my extension with the name HelloWorld.scss no conversion should happen at all. Instead, an error should be raised that says something like:

You can only use module.scss for your extension styles

I agree to some extent. We already have a warning when you create a .scss file that is not a module.scss:

Would you like to see this turned into an error? That may be too restrictive in certain cases. (I'd have to think about this, but I know we do use non-module .scss in some places in our code as we were legally unable to change the source files due to licensing issues. In those cases we just overrode the warning above.)

One this: If you looking forward to support pure .scss the I won't have any use for 'require' and 'import' in the TypeScript code anyway.

My point here was that doing the proper import * as styles from './MyStyles.scss' could give you type-safety with regards to your CSS class-names, whereas it is required to be used with .module.scss due to the name-mangling.

Name the file _mypartialfile.scss in the .module.scss file please @import the partial file.

I'm not sure I see the advantage of this? Why not just make _mypartialfile.scss be a module.scss ?

Are you asking to remove support for non-.module.scss SASS files ?

[StfBauer]

Would you like to see this turned into an error?

No, it doesn't have to be an error the warning is already enough but this wasn't there when I opened the issue.

That may be too restrictive in certain cases. (I'd have to think about this, but I know we do use non-module .scss in some places in our code as we were legally unable to change the source files due to licensing issues. In those cases we just overrode the warning above.)

Interesting. Haven't seen that before an actually wouldn't use it for many reasons.

In case of restrictive. No. it is not really that restrictive because you will always be able to switch to a global context anyway.

:global{
    @import '/node_module/some.css' 
}

This leaves the CSS class names intact and you can use it like you are in a regular CSS. To be honest in case of type save CSS class names. This is a way too overrated. The real benefit is that all classes will be scoped to the header and web part/header/footer only. The reason why type safe doesn't really matter in CSS is that no browser will ever raise an error when a class name is not applied properly.
There are also many scenarios where the type-safe approach is not applicable because you like to use a 3rd party library.

I'm not sure I see the advantage of this? Why not just make _mypartialfile.scss be a module.scss?

From a non-enterprise perspective that is an opportunity. For an enterprise approach where you get style elements from a centralised department the actually not really care about any specifics of SPFx or Office UI Fabric, partial files are the only useful thing to use.

1. I can replace files that define a specific UI Component
2. Better separation of concern - One File per UI Component
3. Import style component form centralised Application Style Guide

So when you like to follow the strict .moduel.css approach to name every file you even have to import the separated files to the typescript code. Not practicable cause the most important feature in SASS is exactly the separation fo concern.

I know many companies that already have style guides that were developed by a centralised design department. The use it for any kind of enterprise applications already and want to provide a consistent user experience through all their applications.

Removing non-"CSS Module' support would the only safe approach for extension customisations. Through partial files, I am even able to import bootstrap for the header or footer customisations without breaking the overall experience.

[nickpape]

We've taken this issue into consideration and decided not to do this at the current time. Thank you for the suggestion and productive discussion, though.

[msft-github-bot]

Issues that have been closed & had no follow-up activity for at least 7 days are automatically locked. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: Issue List: Our approach to locked issues