"sass-typings" task

This task generates TypeScript typings for CSS styles. It supports three different stylesheet formats:

• .css for plain Cascading Style Sheets
• .scss which extends the CSS file format with preprocessor macros, as defined by the Syntactically Awesome Style Sheet (SASS) project
• .sass the older indented syntax which is still supported because some people prefer it

When to use it

We recommend using SASS for any TypeScript web application that uses CSS styles. The .scss file format is a good choice because its syntax is a proper superset of plain CSS.

How it works

Suppose your CSS styles are defined in a file like this:

src/my-styles.scss

$marginValue: 20px;

.label {
  margin-bottom: $marginValue;
}

Before Heft invokes the TypeScript compiler, the sass-typings task can generate a temporary file containing type declarations:

temp/sass-ts/styles.scss.d.ts

// This file was generated by a tool. Modifying it will produce unexpected behavior
export interface IExportStyles {
  label: string;
}
declare const strings: IExportStyles;
export default strings;

This enables the styles.label style to be imported like this:

src/ExampleApp.tsx

import * as React from 'react';
import styles from './my-styles.scss';

export class ExampleApp extends React.Component {
  public render(): React.ReactNode {
    return <p className={styles.label}>Example text</p>;
  }
}

The typical approach used by toolchains such as create-react-app will produce an untyped styles object. This can be error-prone. Heft's generated .d.ts file provides full IntelliSense for style names, and enables the compiler to catch common mistakes such as misspelled identifiers.

The .d.ts file is generated using @rushstack/typings-generator. You can reuse this library to implement custom Heft plugins that generate typings for other resources besides CSS.

package.json dependencies

None - this feature is implemented internally by Heft.

Config files

The build-tests/heft-sass-test project provides examples of .css, .scss, and .sass imports.

The sass-typings plugin is enabled by default and will automatically generate typings for any files under the src folder with supported file extension (.css, .scss, and .sass). Its behavior can be customized using the sass.json config file, but in most cases the default behavior is sufficient.

Reference the generated typings by adding temp/sass-ts to the rootDirs setting in your compiler configuration:

tsconfig.json

{
  "$schema": "http://json.schemastore.org/tsconfig",

  "compilerOptions": {
    "rootDirs": ["src/", "temp/sass-ts/"],

Make sure that the copy-static-assets task is configured to copy CSS file extensions.