Skip to content

Commit 56b60f5

Browse files
Obi-DannObi-Dann
authored
Merge pull request #6 from TeamSupercell/UpgradeAllTheThings
Changes for v2.0.0
2 parents e7814ff + 57479f7 commit 56b60f5

40 files changed

+11024
-644
lines changed

‎.babelrc

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎.eslintrc

Lines changed: 0 additions & 45 deletions
This file was deleted.

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1+
.DS_Store
12
node_modules
23
lib
34
bundle.js
45
example*.css.d.ts
6+
*.log

‎.npmignore

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
.babelrc
2-
.eslintrc
3-
.editorconfig
4-
jsconfig.json
5-
src
6-
test
1+
**/*
2+
!src/**/*
3+
!package.json
4+
!README.md

‎.travis.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
language: node_js
2+
node_js:
3+
- "8"
4+
branches:
5+
only:
6+
- master

‎.vscode/launch.json

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"type": "node",
9+
"request": "launch",
10+
"name": "Jest",
11+
"program": "${workspaceFolder}/node_modules/.bin/jest",
12+
"args": ["${workspaceFolder}/test/index.test.js"],
13+
"console": "integratedTerminal",
14+
"autoAttachChildProcesses": true,
15+
"internalConsoleOptions": "neverOpen"
16+
}
17+
]
18+
}

‎README.md

Lines changed: 123 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1+
[![npm][npm]][npm-url]
2+
[![build][build]][build-url]
3+
[![deps][deps]][deps-url]
4+
15
# typings-for-css-modules-loader
26

3-
Webpack loader that works as a css-loader drop-in replacement to generate TypeScript typings for CSS modules on the fly
7+
Webpack loader that generates TypeScript typings for CSS modules from css-loader on the fly
48

59
## Disclaimer
610

@@ -10,105 +14,115 @@ This repository is a fork of the unmaintained https://github.com/Jimdo/typings-f
1014

1115
Install via npm `npm install --save-dev @teamsupercell/typings-for-css-modules-loader`
1216

13-
## Options
14-
15-
Just like any other loader you can specify options e.g. as query-params
16-
17-
### css-loader options
18-
Any option that your installed version of css-loader supports can be used and will be passed to it.
19-
20-
### `namedExport`-option
21-
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.
22-
e.g.:
23-
```ts
24-
export interface IExampleCss {
25-
'foo': string;
26-
'bar-baz': string;
27-
}
28-
declare const styles: IExampleCss;
29-
30-
export default styles;
31-
```
32-
33-
A cleaner way is to expose all classes as named exports, this can be done if you enable the `namedExport`-option.
34-
e.g.
35-
```js
36-
{ test: /\.css$/, loader: 'typings-for-css-modules-loader?modules&namedExport' }
37-
```
17+
**webpack.config.js**
3818

39-
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)
40-
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.
41-
with:
4219
```js
43-
{ test: /\.css$/, loader: 'typings-for-css-modules-loader?modules&namedExport&camelCase' }
20+
module.exports = {
21+
module: {
22+
rules: [
23+
{
24+
test: /\.css$/i,
25+
use: [
26+
"style-loader",
27+
"@teamsupercell/typings-for-css-modules-loader",
28+
"css-loader"
29+
]
30+
}
31+
]
32+
}
33+
};
4434
```
45-
using the following css:
46-
```css
47-
.foo {
48-
color: white;
49-
}
5035

51-
.bar-baz {
52-
color: green;
53-
}
54-
```
36+
## Options
5537

56-
will generate the following typings file:
57-
```ts
58-
export const foo: string;
59-
export const barBaz: string;
60-
```
38+
| Name | Type | Description |
39+
| :---------------------------: | :--------: | :--------------------------------------------------------------------------- |
40+
| **[`banner`](#banner)** | `{String}` | To add a 'banner' prefix to each generated `*.d.ts` file |
41+
| **[`formatter`](#formatter)** | `{String}` | Formats the generated `*.d.ts` file with specified formatter, eg. `prettier` |
42+
| **[`eol`](#eol)** | `{String}` | Newline character to be used in generated `*.d.ts` files |
6143

62-
`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.*
44+
### `banner`
6345

64-
### `orderAlphabetically`-option
65-
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.
66-
e.g.:
46+
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.
6747

6848
```js
69-
{ test: /\.css$/, loader: 'typings-for-css-modules-loader?modules&orderAlphabetically' }
49+
module.exports = {
50+
module: {
51+
rules: [
52+
{
53+
test: /\.css$/i,
54+
use: [
55+
{
56+
loader: "@teamsupercell/typings-for-css-modules-loader",
57+
options: {
58+
banner:
59+
"// autogenerated by typings-for-css-modules-loader. \n// Please do not change this file!"
60+
}
61+
},
62+
"css-loader"
63+
]
64+
}
65+
]
66+
}
67+
};
7068
```
7169

72-
### `silent`-option
73-
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.
74-
e.g.:
70+
### `formatter`
7571

76-
```js
77-
{ test: /\.css$/, loader: 'typings-for-css-modules-loader?silent' }
78-
```
79-
80-
### `banner`-option
81-
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.
72+
Possible options: `none` and `prettier` (requires `prettier` package to be installed). Defaults to prettier if `prettier` module can be resolved.
8273

8374
```js
84-
{ 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!"' }
75+
module.exports = {
76+
module: {
77+
rules: [
78+
{
79+
test: /\.css$/i,
80+
use: [
81+
{
82+
loader: "@teamsupercell/typings-for-css-modules-loader",
83+
options: {
84+
formatter: "prettier"
85+
}
86+
},
87+
"css-loader"
88+
]
89+
}
90+
]
91+
}
92+
};
8593
```
8694

87-
## Usage
88-
89-
Keep your `webpack.config` as is just instead of using `css-loader` use `typings-for-css-modules-loader`
90-
*its important you keep all the params that you used for the css-loader before, as they will be passed along in the process*
95+
### `eol`
9196

92-
before:
93-
```js
94-
webpackConfig.module.loaders: [
95-
{ test: /\.css$/, loader: 'css?modules' },
96-
{ test: /\.scss$/, loader: 'css?modules&sass' }
97-
];
98-
```
97+
"Newline character to be used in generated d.ts files. By default a value from `require('os').eol` is used.
98+
This option is ignored when [`formatter`](#formatter) `prettier` is used.
9999

100-
after:
101100
```js
102-
webpackConfig.module.loaders: [
103-
{ test: /\.css$/, loader: 'typings-for-css-modules-loader?modules' },
104-
{ test: /\.scss$/, loader: 'typings-for-css-modules-loader?modules&sass' }
105-
];
101+
module.exports = {
102+
module: {
103+
rules: [
104+
{
105+
test: /\.css$/i,
106+
use: [
107+
{
108+
loader: "@teamsupercell/typings-for-css-modules-loader",
109+
options: {
110+
eol: "\r\n"
111+
}
112+
},
113+
"css-loader"
114+
]
115+
}
116+
]
117+
}
118+
};
106119
```
107120

108121
## Example
109122

110123
Imagine you have a file `~/my-project/src/component/MyComponent/myComponent.scss` in your project with the following content:
111-
```css
124+
125+
```scss
112126
.some-class {
113127
// some styles
114128
&.someOtherClass {
@@ -121,45 +135,46 @@ Imagine you have a file `~/my-project/src/component/MyComponent/myComponent.scss
121135
```
122136

123137
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:
138+
124139
```ts
125140
export interface IMyComponentScss {
126-
'some-class': string;
127-
'someOtherClass': string;
128-
'some-class-sayWhat': string;
141+
"some-class": string;
142+
someOtherClass: string;
143+
"some-class-sayWhat": string;
129144
}
130-
declare const styles: IMyComponentScss;
131145

132-
export default styles;
146+
export const locals: IExampleCss;
147+
export default locals;
133148
```
134149

135-
### using `namedExport` with the `camelCase`-option
136-
Using the `namedExport` as well as the `camelCase` options the generated file will look as follow:
137150
```ts
138-
export const someClass: string;
139-
export const someOtherClass: string;
140-
export const someClassSayWhat: string;
151+
// using default export when used with style-loader or mini-css-extract-plugin
152+
import styles from "./myComponent.scss";
153+
154+
console.log(styles["some-class"]);
155+
console.log(styles.someOtherClass);
141156
```
142157

143-
### Example in Visual Studio Code
144-
![typed-css-modules](https://cloud.githubusercontent.com/assets/749171/16340497/c1cb6888-3a28-11e6-919b-f2f51a282bba.gif)
158+
```ts
159+
// using locals export when used without style-loader or mini-css-extract-plugin
160+
import { locals } from "./myComponent.scss";
145161

146-
If you encounter the following errors:
147-
```
148-
error TS1192: Module '"xxxxx/xxxx/src/style.sass"' has no default export.
149-
```
150-
maybe you should export the styles as following:
151-
```
152-
import * as styles from './style.sass';
162+
console.log(locals["some-class"]);
163+
console.log(locals.someOtherClass);
153164
```
154165

166+
### Example in Visual Studio Code
167+
168+
![typed-css-modules](https://cloud.githubusercontent.com/assets/749171/16340497/c1cb6888-3a28-11e6-919b-f2f51a282bba.gif)
169+
155170
## Support
156171

157172
As the loader just acts as an intermediary it can handle all kind of css preprocessors (`sass`, `scss`, `stylus`, `less`, ...).
158173
The only requirement is that those preprocessors have proper webpack loaders defined - meaning they can already be loaded by webpack anyways.
159174

160175
## Requirements
161176

162-
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.
177+
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.
163178

164179
## Known issues
165180

@@ -168,6 +183,7 @@ The loader uses `css-loader`(https://github.com/webpack/css-loader) under the ho
168183
As the loader generates typing files, it is wise to tell webpack to ignore them.
169184
The fix is luckily very simple. Webpack ships with a "WatchIgnorePlugin" out of the box.
170185
Simply add this to your webpack plugins:
186+
171187
```
172188
plugins: [
173189
new webpack.WatchIgnorePlugin([
@@ -176,9 +192,18 @@ plugins: [
176192
...
177193
]
178194
```
195+
179196
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.
180197

181-
### Typescript doesnt find the typings
198+
### Typescript does not find the typings
182199

183200
As the webpack process is independent from your typescript "runtime" it may take a while for typescript to pick up the typings.
184-
Any hints on how this could be fixed deterministically are welcome!
201+
202+
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.
203+
204+
[npm]: https://img.shields.io/npm/v/@teamsupercell/typings-for-css-modules-loader.svg
205+
[npm-url]: https://npmjs.com/package/@teamsupercell/typings-for-css-modules-loader
206+
[build]: https://travis-ci.com/TeamSupercell/typings-for-css-modules-loader.svg?branch=master
207+
[build-url]: https://travis-ci.com/TeamSupercell/typings-for-css-modules-loader
208+
[deps]: https://david-dm.org/@teamsupercell/typings-for-css-modules-loader.svg
209+
[deps-url]: https://david-dm.org/@teamsupercell/typings-for-css-modules-loader

0 commit comments

Comments
 (0)