Merge pull request #6 from TeamSupercell/UpgradeAllTheThings

Changes for v2.0.0
TeamSupercell · Aug 14, 2019 · 56b60f5 · 56b60f5
2 parents e7814ff + 57479f7
commit 56b60f5
Show file tree

Hide file tree

Showing 40 changed files with 11,024 additions and 644 deletions.
diff --git a/.babelrc b/.babelrc
diff --git a/.eslintrc b/.eslintrc
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
+.DS_Store
 node_modules
 lib
 bundle.js
 example*.css.d.ts
+*.log
diff --git a/.npmignore b/.npmignore
@@ -1,6 +1,4 @@
-.babelrc
-.eslintrc
-.editorconfig
-jsconfig.json
-src
-test
+**/*
+!src/**/*
+!package.json
+!README.md
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,6 @@
+language: node_js
+node_js:
+  - "8"
+branches:
+  only:
+    - master
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,18 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Jest",
+      "program": "${workspaceFolder}/node_modules/.bin/jest",
+      "args": ["${workspaceFolder}/test/index.test.js"],
+      "console": "integratedTerminal",
+      "autoAttachChildProcesses": true,
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}
diff --git a/README.md b/README.md
@@ -1,6 +1,10 @@
+[![npm][npm]][npm-url]
+[![build][build]][build-url]
+[![deps][deps]][deps-url]
+
 # typings-for-css-modules-loader
 
-Webpack loader that works as a css-loader drop-in replacement to generate TypeScript typings for CSS modules on the fly
+Webpack loader that generates TypeScript typings for CSS modules from css-loader on the fly
 
 ## Disclaimer
 
@@ -10,105 +14,115 @@ This repository is a fork of the unmaintained https://github.com/Jimdo/typings-f
 
 Install via npm `npm install --save-dev @teamsupercell/typings-for-css-modules-loader`
 
-## Options
-
-Just like any other loader you can specify options e.g. as query-params
-
-### css-loader options
-Any option that your installed version of css-loader supports can be used and will be passed to it.
-
-### `namedExport`-option
-As your fellow css-developer may tend to use characters like dashes(`-`) that are not valid characters for a typescript variable the default behaviour for this loader is to export an interface as the default export that contains the classnames as properties.
-e.g.:
-```ts
-export interface IExampleCss {
-  'foo': string;
-  'bar-baz': string;
-}
-declare const styles: IExampleCss;
-
-export default styles;
-```
-
-A cleaner way is to expose all classes as named exports, this can be done if you enable the `namedExport`-option.
-e.g.
-```js
-  { test: /\.css$/, loader: 'typings-for-css-modules-loader?modules&namedExport' }
-```
+**webpack.config.js**
 
-As mentioned above, this requires classnames to only contain valid typescript characters, thus filtering out all classnames that do not match /^\w+$/i. (feel free to improve that regexp)
-In order to make sure that even classnames with non-legal characters are used it is highly recommended to use the `camelCase`-option as well, that - once passed to the css-loader - makes sure all classnames are transformed to valid variables.
-with:
 ```js
-  { test: /\.css$/, loader: 'typings-for-css-modules-loader?modules&namedExport&camelCase' }
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [
+          "style-loader",
+          "@teamsupercell/typings-for-css-modules-loader",
+          "css-loader"
+        ]
+      }
+    ]
+  }
+};
 ```
-using the following css:
-```css
-.foo {
-  color: white;
-}
 
-.bar-baz {
-  color: green;
-}
-```
+## Options
 
-will generate the following typings file:
-```ts
-export const foo: string;
-export const barBaz: string;
-```
+|             Name              |    Type    | Description                                                                  |
+| :---------------------------: | :--------: | :--------------------------------------------------------------------------- |
+|    **[`banner`](#banner)**    | `{String}` | To add a 'banner' prefix to each generated `*.d.ts` file                     |
+| **[`formatter`](#formatter)** | `{String}` | Formats the generated `*.d.ts` file with specified formatter, eg. `prettier` |
+|       **[`eol`](#eol)**       | `{String}` | Newline character to be used in generated `*.d.ts` files                     |
 
-`css-loader` exports mappings to `exports.locals` which is incompatible with the `namedExport`-option unless paired with `extract-text-webpack-plugin` or `style-loader`. They move the exported properties from `exports.locals` to `exports` making them required for `namedExport` to work, and `namedExport` required for them to work. *Always combine usage of `extract-text-webpack-plugin` or `style-loader` with the `namedExport`-option.*
+### `banner`
 
-### `orderAlphabetically`-option
-Orders generated exports or interface properties alphabetically. This is useful when committing the .d.ts files as the default ordering is not always consistent and can change from commit to commit.
-e.g.:
+To add a "banner" prefix to each generated `*.d.ts` file, you can pass a string to this option as shown below. The prefix is quite literally prefixed into the generated file, so please ensure it conforms to the type definition syntax.
 
 ```js
-  { test: /\.css$/, loader: 'typings-for-css-modules-loader?modules&orderAlphabetically' }
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [
+          {
+            loader: "@teamsupercell/typings-for-css-modules-loader",
+            options: {
+              banner:
+                "// autogenerated by typings-for-css-modules-loader. \n// Please do not change this file!"
+            }
+          },
+          "css-loader"
+        ]
+      }
+    ]
+  }
+};
 ```
 
-### `silent`-option
-To silence the loader because you get annoyed by its warnings or for other reasons, you can simply pass the "silent" query to the loader and it will shut up.
-e.g.:
+### `formatter`
 
-```js
-  { test: /\.css$/, loader: 'typings-for-css-modules-loader?silent' }
-```
-
-### `banner`-option
-To add a "banner" prefix to each generated `*.d.ts` file, you can pass a string to this option as shown below. The prefix is quite literally prefixed into the generated file, so please ensure it conforms to the type definition syntax.
+Possible options: `none` and `prettier` (requires `prettier` package to be installed). Defaults to prettier if `prettier` module can be resolved.
 
 ```js
-  { test: /\.css$/, loader: 'typings-for-css-modules?banner="// This file is automatically generated by typings-for-css-modules.\n// Please do not change this file!"' }
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [
+          {
+            loader: "@teamsupercell/typings-for-css-modules-loader",
+            options: {
+              formatter: "prettier"
+            }
+          },
+          "css-loader"
+        ]
+      }
+    ]
+  }
+};
 ```
 
-## Usage
-
-Keep your `webpack.config` as is just instead of using `css-loader` use `typings-for-css-modules-loader`
-*its important you keep all the params that you used for the css-loader before, as they will be passed along in the process*
+### `eol`
 
-before:
-```js
-webpackConfig.module.loaders: [
-    { test: /\.css$/, loader: 'css?modules' },
-    { test: /\.scss$/, loader: 'css?modules&sass' }
-];
-```
+"Newline character to be used in generated d.ts files. By default a value from `require('os').eol` is used.
+This option is ignored when [`formatter`](#formatter) `prettier` is used.
 
-after:
 ```js
-webpackConfig.module.loaders: [
-    { test: /\.css$/, loader: 'typings-for-css-modules-loader?modules' },
-    { test: /\.scss$/, loader: 'typings-for-css-modules-loader?modules&sass' }
-];
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [
+          {
+            loader: "@teamsupercell/typings-for-css-modules-loader",
+            options: {
+              eol: "\r\n"
+            }
+          },
+          "css-loader"
+        ]
+      }
+    ]
+  }
+};
 ```
 
 ## Example
 
 Imagine you have a file `~/my-project/src/component/MyComponent/myComponent.scss` in your project with the following content:
-```css
+
+```scss
 .some-class {
   // some styles
   &.someOtherClass {
@@ -121,45 +135,46 @@ Imagine you have a file `~/my-project/src/component/MyComponent/myComponent.scss
 ```
 
 Adding the `typings-for-css-modules-loader` will generate a file `~/my-project/src/component/MyComponent/myComponent.scss.d.ts` that has the following content:
+
 ```ts
 export interface IMyComponentScss {
-  'some-class': string;
-  'someOtherClass': string;
-  'some-class-sayWhat': string;
+  "some-class": string;
+  someOtherClass: string;
+  "some-class-sayWhat": string;
 }
-declare const styles: IMyComponentScss;
 
-export default styles;
+export const locals: IExampleCss;
+export default locals;
 ```
 
-### using `namedExport` with the `camelCase`-option
-Using the `namedExport` as well as the `camelCase` options the generated file will look as follow:
 ```ts
-export const someClass: string;
-export const someOtherClass: string;
-export const someClassSayWhat: string;
+// using default export when used with style-loader or mini-css-extract-plugin
+import styles from "./myComponent.scss";
+
+console.log(styles["some-class"]);
+console.log(styles.someOtherClass);
 ```
 
-### Example in Visual Studio Code
-![typed-css-modules](https://cloud.githubusercontent.com/assets/749171/16340497/c1cb6888-3a28-11e6-919b-f2f51a282bba.gif)
+```ts
+// using locals export when used without style-loader or mini-css-extract-plugin
+import { locals } from "./myComponent.scss";
 
-If you encounter the following errors:
-```
-error TS1192: Module '"xxxxx/xxxx/src/style.sass"' has no default export.
-```
-maybe you should export the styles as following:
-```
-import * as styles from './style.sass';
+console.log(locals["some-class"]);
+console.log(locals.someOtherClass);
 ```
 
+### Example in Visual Studio Code
+
+![typed-css-modules](https://cloud.githubusercontent.com/assets/749171/16340497/c1cb6888-3a28-11e6-919b-f2f51a282bba.gif)
+
 ## Support
 
 As the loader just acts as an intermediary it can handle all kind of css preprocessors (`sass`, `scss`, `stylus`, `less`, ...).
 The only requirement is that those preprocessors have proper webpack loaders defined - meaning they can already be loaded by webpack anyways.
 
 ## Requirements
 
-The loader uses `css-loader`(https://github.com/webpack/css-loader) under the hood. Thus it is a peer-dependency and the expected loader to create CSS Modules.
+The loader is supposed to be used with `css-loader`(https://github.com/webpack/css-loader). Thus it is a peer-dependency and the expected loader to create CSS Modules.
 
 ## Known issues
 
@@ -168,6 +183,7 @@ The loader uses `css-loader`(https://github.com/webpack/css-loader) under the ho
 As the loader generates typing files, it is wise to tell webpack to ignore them.
 The fix is luckily very simple. Webpack ships with a "WatchIgnorePlugin" out of the box.
 Simply add this to your webpack plugins:
+
 ```
 plugins: [
     new webpack.WatchIgnorePlugin([
@@ -176,9 +192,18 @@ plugins: [
     ...
   ]
 ```
+
 where `css` is the file extension of your style files. If you use `sass` you need to put `sass` here instead. If you use `less`, `stylus` or any other style language use their file ending.
 
-### Typescript doesnt find the typings
+### Typescript does not find the typings
 
 As the webpack process is independent from your typescript "runtime" it may take a while for typescript to pick up the typings.
-Any hints on how this could be fixed deterministically are welcome!
+
+It is possible to write a custom webpack plugin using the `fork-ts-checker-service-before-start` hook from https://github.com/TypeStrong/fork-ts-checker-webpack-plugin#plugin-hooks to delay the start of type checking until all the `*.d.ts` files are generated. Potentially, this plugin can be included in this repository.
+
+[npm]: https://img.shields.io/npm/v/@teamsupercell/typings-for-css-modules-loader.svg
+[npm-url]: https://npmjs.com/package/@teamsupercell/typings-for-css-modules-loader
+[build]: https://travis-ci.com/TeamSupercell/typings-for-css-modules-loader.svg?branch=master
+[build-url]: https://travis-ci.com/TeamSupercell/typings-for-css-modules-loader
+[deps]: https://david-dm.org/@teamsupercell/typings-for-css-modules-loader.svg
+[deps-url]: https://david-dm.org/@teamsupercell/typings-for-css-modules-loader