Skip to content

Commit 3c7488b

Browse files
committed
Add README and fix typo
1 parent 691fe4e commit 3c7488b

File tree

4 files changed

+94
-25
lines changed

4 files changed

+94
-25
lines changed

README.md

Lines changed: 83 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,28 @@ for [CSS Modules](https://github.com/css-modules/css-modules).
99

1010
<img src="https://raw.githubusercontent.com/mrmckeb/typescript-plugin-css-modules/master/.github/images/example.gif" alt="typescript-plugin-css-modules example" />
1111

12-
This project was inspired by this [`create-react-app` issue](https://github.com/facebook/create-react-app/issues/5677)
13-
and was based on [`css-module-types`](https://github.com/timothykang/css-module-types).
12+
## Table of contents
13+
14+
- [Installation](#installation)
15+
- [Importing CSS](#importing-css)
16+
- [Options](#options)
17+
- [Visual Studio Code](#visual-studio-code)
18+
- [Custom definitions](#custom-definitions)
19+
- [Troubleshooting](#troubleshooting)
20+
- [About this project](#about-this-project)
1421

1522
## Installation
1623

1724
To install with Yarn:
1825

1926
```sh
20-
yarn add typescript-plugin-css-modules
27+
yarn add -D typescript-plugin-css-modules
2128
```
2229

2330
To install with npm:
2431

2532
```sh
26-
npm install --save typescript-plugin-css-modules
33+
npm install -D typescript-plugin-css-modules
2734
```
2835

2936
Once installed, add this plugin to your `tsconfig.json`:
@@ -36,6 +43,8 @@ Once installed, add this plugin to your `tsconfig.json`:
3643
}
3744
```
3845

46+
If you're using Visual Studio Code, please also follow these [instructions](#visual-studio-code).
47+
3948
### Importing CSS
4049

4150
A default export is always provided for your CSS module.
@@ -58,12 +67,16 @@ const b = styles['my_other-class'];
5867

5968
### Options
6069

61-
| Option | Default value | Description |
62-
| --------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
63-
| `customMatcher` | `"\\.module\\.(c\|le\|sa\|sc)ss$"` | Change the file extensions that this plugin works with. |
64-
| `camelCase` | `false` | Implements the behaviour of the [`camelCase` CSS Loader option](https://github.com/webpack-contrib/css-loader#camelcase) (accepting the same values). |
70+
Please note that no options are required. However, depending on your configuration, you may need to customise these options.
6571

66-
The below is an example that only matches "\*.m.css" files, and [camel-cases dashes](https://github.com/webpack-contrib/css-loader#camelcase).
72+
| Option | Default value | Description |
73+
| ----------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
74+
| `camelCase` | `false` | Implements the behaviour of the [`camelCase` CSS Loader option](https://github.com/webpack-contrib/css-loader#camelcase) (accepting the same values). |
75+
| `customMatcher` | `"\\.module\\.(c\|le\|sa\|sc)ss$"` | Changes the file extensions that this plugin processes. |
76+
| `customRenderer` | `false` | See [`customRenderer`](#customRenderer) below. |
77+
| `dotenvOptions` | `{}` | Provides options for [`dotenv`](https://github.com/motdotla/dotenv#options). |
78+
| `postCssOptions` | `{}` | See [`postCssOptions`](#postCssOptions) below. |
79+
| `rendererOptions` | `{}` | See [`rendererOptions`](#rendererOptions) below. |
6780

6881
```json
6982
{
@@ -72,22 +85,69 @@ The below is an example that only matches "\*.m.css" files, and [camel-cases das
7285
{
7386
"name": "typescript-plugin-css-modules",
7487
"options": {
88+
"camelCase": "dashes",
7589
"customMatcher": "\\.m\\.css$",
76-
"camelCase": "dashes"
90+
"customRenderer": "./myRenderer.js",
91+
"dotenvOptions": {},
92+
"postCssOptions": {},
93+
"rendererOptions": {}
7794
}
7895
}
7996
]
8097
}
8198
}
8299
```
83100

101+
#### `customRenderer`
102+
103+
The `customRenderer` is an advanced option, letting you provide the CSS renderer.
104+
105+
When a custom renderer is provided, not other renderers will be used.
106+
107+
The path to the `customRenderer` must be relative to the project root (i.e. `./myRenderer.js`).
108+
109+
The custom renderer itself should be a JavaScript file. The function will be called with two arguments: a `css` string, and an `options` object (see [`options.ts`](https://github.com/mrmckeb/typescript-plugin-css-modules/blob/master/src/options.ts#L36-L39)). It must be synchronous, and must return valid CSS.
110+
111+
```js
112+
module.exports = (css, { fileName, logger }) => {
113+
try {
114+
// ...process css here
115+
return renderedCss;
116+
} catch (error) {
117+
logger.error(error.message);
118+
}
119+
};
120+
```
121+
122+
You can find an example custom renderer in our test fixtures ([`customRenderer.js`](https://github.com/mrmckeb/typescript-plugin-css-modules/blob/master/src/helpers/__tests__/fixtures/customRenderer.js)).
123+
124+
The [internal `logger`](https://github.com/mrmckeb/typescript-plugin-css-modules/blob/master/src/helpers/logger.ts) is provided for [debugging](#troubleshooting).
125+
126+
#### `postCssOptions`
127+
128+
| Option | Default value | Description |
129+
| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
130+
| `useConfig` | `false` | Set to `true` to load plugins from your [PostCSS config](https://github.com/michael-ciniawsky/postcss-load-config#usage). |
131+
| `excludePlugins` | `false` | Only sync plugins are supported. Use this to set an array of async plugins to exclude (i.e. `['postcss-mixins']`) |
132+
133+
#### `rendererOptions`
134+
135+
| Option | Default value | Description |
136+
| ------ | ------------- | ------------------------------------------------------------------------------------ |
137+
| `less` | `{}` | Set [renderer options for Less](http://lesscss.org/usage/#less-options). |
138+
| `sass` | `{}` | Set [renderer options for Sass](https://sass-lang.com/documentation/js-api#options). |
139+
84140
### Visual Studio Code
85141

86-
By default, VSCode will use its own version of TypeScript. To make it work with this plugin, you have two options:
142+
#### Recommended usage
143+
144+
To use this plugin with Visual Studio Code, you should set your workspace's version of TypeScript, which will load plugins from your `tsconfig.json` file.
145+
146+
For instructions, see: [Using the workspace version of TypeScript](https://code.visualstudio.com/docs/languages/typescript#_using-the-workspace-version-of-typescript).
87147

88-
1. Use your workspace's version of TypeScript, which will load plugins from your `tsconfig.json` file. This is the recommended approach. For instructions, see: [Using the workspace version of TypeScript](https://code.visualstudio.com/docs/languages/typescript#_using-the-workspace-version-of-typescript).
148+
#### Alternative usage
89149

90-
2. Add this plugin to `"typescript.tsserver.pluginPaths"` in settings. Note that this method doesn't currently support plugin options.
150+
If you aren't using any [plugin options](#options), you can simple add this plugin to `"typescript.tsserver.pluginPaths"` in settings. You cannot provide plugin options with this approach.
91151

92152
```json
93153
{
@@ -101,9 +161,9 @@ _Note: Create React App users can skip this section if you're using `react-scrip
101161

102162
If your project doesn't already have global declarations for CSS Modules, you will need to add these to help TypeScript understand the general shape of the imported CSS during build.
103163

104-
Where you store global declarations is up to you. An example might look like: `src/custom.d.ts`.
164+
Where you store global declarations is up to you. An example might look like: `./src/custom.d.ts`.
105165

106-
The below is an example that you can copy or modify. If you use a `customMatcher`, you'll need to modify it.
166+
The below is an example that you can copy or modify. If you use a [`customMatcher`], you'll need to modify this.
107167

108168
```ts
109169
declare module '*.module.css' {
@@ -129,8 +189,13 @@ declare module '*.module.less' {
129189

130190
## Troubleshooting
131191

132-
If you're having issues with this extension, you can view the TypeScript Server Log in VSCode by entering `Typescript: Open TS Server log` in the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
192+
For troubleshooting and debugging, you can view the TypeScript Server Log in Visual Studio Code by entering `Typescript: Open TS Server log` in the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
193+
194+
If you're not using Visual Studio Code or are having trouble with the above method, you can set the [`TSS_LOG` environment variable](https://github.com/Microsoft/TypeScript/wiki/Standalone-Server-%28tsserver%29#logging).
195+
196+
You can include these logs with any issues you open for this project.
133197

134-
If that doesn't work, or you're not using VSCode, you can set the [TSS_LOG environment variable](https://github.com/Microsoft/TypeScript/wiki/Standalone-Server-%28tsserver%29#logging).
198+
## About this project
135199

136-
You can also include this with any issues you file on this project.
200+
This project was inspired by a Create React App [issue](https://github.com/facebook/create-react-app/issues/5677)
201+
and built on prior work from [`css-module-types`](https://github.com/timothykang/css-module-types).

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "typescript-plugin-css-modules",
3-
"version": "1.4.0",
3+
"version": "2.0.0",
44
"main": "lib/index.js",
55
"author": "Brody McKee <mrmckeb@hotmail.com>",
66
"license": "MIT",

src/index.ts

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,23 +25,22 @@ function init({ typescript: ts }: { typescript: typeof tsModule }) {
2525

2626
function create(info: ts.server.PluginCreateInfo) {
2727
const logger = createLogger(info);
28+
const directory = info.project.getCurrentDirectory();
2829

2930
// User options for plugin.
3031
const options: Options = info.config.options || {};
3132
logger.log(`options: ${JSON.stringify(options)}`);
3233

3334
// Set environment variables, resolves #49.
3435
// TODO: Add tests for this option.
35-
dotenv.config(options.dotEnvOptions);
36+
dotenv.config(options.dotenvOptions);
3637

3738
// Add postCSS config if enabled.
3839
const postCssOptions = options.postCssOptions || {};
3940

4041
let userPlugins: AcceptedPlugin[] = [];
4142
if (postCssOptions.useConfig) {
42-
const postcssConfig = getPostCssConfigPlugins(
43-
info.project.getCurrentDirectory(),
44-
);
43+
const postcssConfig = getPostCssConfigPlugins(directory);
4544
userPlugins = [
4645
filter({
4746
exclude: postCssOptions.excludePlugins,
@@ -51,6 +50,11 @@ function init({ typescript: ts }: { typescript: typeof tsModule }) {
5150
];
5251
}
5352

53+
// If a custom renderer is provided, resolve the path.
54+
if (options.customRenderer) {
55+
options.customRenderer = path.resolve(directory, options.customRenderer);
56+
}
57+
5458
// Create PostCSS processor.
5559
const processor = postcss([
5660
...userPlugins,

src/options.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ export interface Options {
1616
camelCase?: CamelCaseOptions;
1717
customMatcher?: string;
1818
customRenderer?: string;
19-
dotEnvOptions?: DotenvConfigOptions;
19+
dotenvOptions?: DotenvConfigOptions;
2020
postCssOptions?: PostCssOptions;
2121
rendererOptions?: RendererOptions;
2222
}
@@ -35,5 +35,5 @@ export interface CustomRendererOptions {
3535

3636
export type CustomRenderer = (
3737
css: string,
38-
Options: CustomRendererOptions,
38+
options: CustomRendererOptions,
3939
) => string;

0 commit comments

Comments
 (0)