Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

[heft-sass-plugin] Emit declaration source maps so "go to definition" resolves to the stylesheet

Abierto
  • ¿Algo no está bien?
#5,908 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
sass, typescript
Área
build-system, tooling

Línea de trabajo

Start in the heft-sass-plugin's SassProcessor, where the plugin composes and writes its .d.ts, and review how postcss-modules and the Sass source map can provide class positions. Consider the relationship to typings-generator's serializeDeclarationMap from #5907 and the proposed opt-in behavior. Done means tsserver navigation reaches the declaring rule, including classes in partials and @media blocks.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Summary

Typings generated by @rushstack/heft-sass-plugin are written into a folder that is merged back
into the source tree via the TypeScript rootDirs compiler option, so the language service only
ever sees the generated .d.ts. The stylesheet that actually declares the class is invisible to it.

The effect is that "go to definition" on a CSS module class, or on the import specifier, navigates
to the generated declaration rather than to the file the developer can edit:

import * as styles from './HeaderBar.module.scss';

styles.headerBar; // -> temp/sass-ts/HeaderBar.module.scss.d.ts, not src/HeaderBar.module.scss

Because the generated file is a build artifact, landing there is a dead end.

This is the same underlying problem as #5906, which covers localization typings, but the Sass plugin
does not share the code path: it composes and writes its own .d.ts in SassProcessor rather than
going through @rushstack/typings-generator.

Repro steps

  1. Configure a project that uses @rushstack/heft-sass-plugin to emit typings into a folder listed
    in rootDirs.
  2. Import a .module.scss from a .ts file and reference one of its classes.
  3. Alt-click (or F12) the class, or the import specifier.

Expected result: the editor opens the .scss at the rule that declares the class.

Actual result: the editor opens the generated .module.scss.d.ts.

Details

TypeScript already solves this generally with declaration source maps (.d.ts.map): when a .d.ts
has a corresponding map pointing at real source, tsserver transparently redirects "go to
definition" there. The Sass plugin does not emit one, so there is nothing to redirect with.

The interesting part is obtaining accurate positions. Searching the stylesheet text for the class
name is unreliable in two common cases:

  • A class declared in an @imported partial does not appear in the entry file at all.
  • A class restated inside a @media or theme block can be matched instead of its primary rule.

Both are avoidable, because Sass can produce a source map for the compilation. A PostCSS plugin
registered before postcss-modules (which rewrites class names) can record where each class
selector appears in the compiled CSS, and that position maps back through the Sass source map to the
original stylesheet. Because the lookup is done in compiled-CSS order, the top-level rule is
naturally preferred over a later restatement, and classes from partials resolve into the partial.

I have prototyped this and confirmed with a live tsserver that navigation resolves to the correct
rule, including the partial and @media cases.

Two design points I would like guidance on before sending a PR:

  1. Where the shared pieces should live. #5907 adds serializeDeclarationMap to
    @rushstack/typings-generator. The Sass plugin additionally needs to decode a source map to do
    the position lookup. Putting the decoder alongside the encoder in typings-generator would keep
    one implementation, but heft-sass-plugin does not currently depend on that package.
  2. Whether the Sass-specific helpers should be exported. Other Sass typings generators exist
    outside this repo that would otherwise reimplement the same PostCSS-plus-source-map chain.
    Exporting them would let those consumers reuse this rather than duplicate it.

Requesting the Sass source map has a cost, so the feature would be opt-in and off by default.

Standard questions

Question Answer
Package name: @rushstack/heft-sass-plugin
Package version? 0.15.24
Operating system? Linux (also reproduced on Mac)
Would you consider contributing a PR? Yes
Node.js version (node -v)? 22.16.0
Lenguaje dominante
TypeScript
Estrellas
6.5k
Forks
708
Merge medio
4 d 7 h
PR fusionados (30 d)
61

Preparar el entorno

Aún no hemos revisado los archivos de configuración de este proyecto. Empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de microsoft/rushstack

Todos los issues de microsoft/rushstack

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.