Need better CSS modules + Typescript support

[mosesoak]

Description

While Gatsby 3 provides general Typescript and css-module support, the two are hard to use together. (Error-ridden, not well-documented.)

Steps to reproduce

1. Start a Gatsby 3 project with typescript, e.g. index.tsx page
2. Add a css module next to index.tsx with a single style in it.
3. Import the style using `import * as styles from './index.module.css'

Expected result

There are no type errors, docs will clearly describe how to access class names, and Typescript will be able to see styles imported into components.

Actual result

• Immediately Typescript shows an error on the import path.
• Hyphenated class names are somewhat more difficult to access, which is not addressed in the docs or example project.
• Typescript doesn't see or link to the imported classes, and no solution is currently offered by the docs or available on the market.

First point:

The import error can be patched by adding a file like src/global.d.ts with the line declare module "*.css;", but this doesn't seem to be documented. (The same issue comes up for direct imports of media assets, this is a pretty well-known Typescript hurdle but it would be nice if Gatsby users trying out Typescript got a bit more help.)

Second point:

As to hyphens, the Gatsby docs do not mention any camelCase options for css, only for the sass plugin. The Gatsby example project similarly lacks any hyphenated class names, that might be a great place to add something like classname={styles['main-heading']}, if that is indeed the only way to do it.

Third point:

Lastly, this may be out of Gatsby's scope but using VS Code (and probably other editors) there's no code-hinting or definition linkage between the imported class name and the classes in the CSS file. Typescript isn't even mentioned anywhere in the css or sass module docs. There only seems to be a 3rd-party plugin to addresses this lack. (It's not great, it auto-generates type definition files that get added next to each style file, which is messy and doesn't solve jumping to the definition.) CSS modules and Typescript are both first-class tools, so it would be nice to see the Gatsby team put out an official plugin to help smooth out this area.

Thanks for considering these things, I would not be posting this issue if I hadn't dropped many hours trying to get Typescript, Gatsby 3, and SCSS modules to play better together. (I landed on a VS Code 'CSS Modules' extension which helps a little, but some love from the Gatsby team could go a lot further.)

Environment

System:
OS: Linux Ubuntu
Binaries:
Node: 12.18.3 - /tmp/yarn--1622242100159-0.5254414059011245/node
Yarn: 1.22.10 - /tmp/yarn--1622242100159-0.5254414059011245/yarn
npm: 6.14.6 - ~/.nvm/versions/node/v12.18.3/bin/npm
npmPackages:
gatsby: ^1.9.119 => 1.9.279
gatsby-link: ^1.6.28 => 1.6.46
gatsby-plugin-react-helmet: ^1.0.8 => 1.0.8
gatsby-plugin-sass: ^4.6.0 => 4.6.0
gatsby-plugin-typescript: ^1.4.10 => 1.4.20

[LekoArts]

Hi, thanks for the write-up. Appreciate it!

Since most of our users still use JavaScript and not TypeScript the docs are primarily written with those people in mind. TypeScript additions to docs then often come from community members. We also have to strike the correct balance between providing information relevant to Gatsby and general information. While adding information about e.g. your first bullet point is cheap, the maintenance dept on those things can become huge over time if you add those things all over your docs. A better strategy is to link out to e.g. the official TypeScript docs.

First and foremost, I'm not sure if your Environment information is correct as this is a really outdated Gatsby version. You did start e.g. with npm init gatsby, right?

Generally speaking any additional TypeScript information can be added under a <h2> TypeScript heading here: https://www.gatsbyjs.com/docs/how-to/styling/css-modules/ - and other information there, too.

First Point:

As I said, if the TypeScript docs have a section on this we should link to this.

Second Point:

Are you sure about that? The normal CSS Modules integration should convert kebab case to camel case.

Third Point:

For now I don't think that this will be a priority for us in the near future as there isn't any demand on this. You could use https://github.com/seek-oss/vanilla-extract for a better TypeScript experience.

[mosesoak]

@LekoArts Thank you for your reply, also much appreciated!

You were right about the gatsby version, I'd used an old typescript starter, but that's no longer needed! I have the same results after doing a fresh npx gatsby new install though, which is as follows:

• you set up a project, add a css module, and import * as styles in index.js, no problem, well documented, works great! you click the Go to "Using TypeScript" link and are pleased to learn that Gatsby supports typescript out of the box, cool!
• you rename to pages/index.tsx. Immediately you get an error on the import. Neither VS Code nor Gatsby understands how to import the css module. you weep a bitter tear.
• you desperately rummage around the dustbins of Github and Medium looking for answers. You find nothing but a few half-working solutions to smooth over what you'd thought would be just a regular afternoon. you realize that no one cares.
• unable to proceed, you quit your job, buy a shotgun, move to a mountain retreat, and are never heard from again aside from the occasional 'get offa my land!' outburst.

That's not the most delightful user journey I've ever read.

(Although one of the finest I've ever written, if I do say so.)

Our team does actively try out a lot of the css-in-js solutions out there, but TBH none of them feels anywhere near a new standard that would replace the first-class citizen known as CSS modules. I'd suggest that if Gatsby loudly proclaims compatibility with both Typescript and CSS modules, it shouldn't ignore the fact that these two can't be used together without problems. That could be easily remedied with a little documentation in the short term -- not saying to go down a rabbit hole, just suggesting adding some docs to address this overlooked area.

[webstackdev]

I'm on step #3, six months after this was written, in an identical situation as the post describes...

[commscheck]

@mosesoak was there any update on this? At the very least some official documentation on how to work around the issue? I'm getting the same issue in a new project using Gatsby v4.

[JustFly1984]

My friend @awwit maintains vscode extension types css modules. It's main feature is generating d.ts files for css/scss files on save.

[marcobiedermann]

@mosesoak

I had the same issue but found a good solution to this problem.
I'm using typed-css-modules to generate types for my CSS class definitions.
I've added a small npm script to my package.json to generate them for me: "generate:css": "tcm -p 'src/**/*.module.css' ."
This will generate a type definition file next to it's CSS file e.g.

/* header.module.css */

.header {}

// header.module.css.d.ts

declare const styles: {
  readonly header: string;
};
export = styles;

Next, you have to import it into your React component.

// Header.tsx

import { header } from './header.module.css';

function Header(props) {
  return <header className={header} {...props} />;
}

export default Header;

Note that you have to restructure your imports to allow tree-shaking. import * as styles from './path/to/component.module.css' will log some warnings.

[JonJamesDesign]

You can also add the -w flag, to watch for changes.

You can then use something like concurrently to modify your start script to both spin up the local dev server, and start watching+generating type definitions for css modules, like so:

{
  "scripts": [
    "dev": "gatsby develop",
    "gen-css-types": "tcm -p 'src/**/*.module.css' . -w",
    "start": "concurrently --kill-others-on-fail \"yarn dev\" \"yarn gen-css-types\"",
  ]
}

[junowong0114]

Great work-around. Still, the world is moving towards TypeScript, I would second the motion of officially providing typescript support in the docs.

[ErikAGriffin]

Wow, after a few painstaking hours of trying to get my typescript-gatsby3 project to compile a sass module.. is this currently the only functioning work-around anyone has come across? The previous threads I've found seem to no longer work with Gatsby v3