Feature Request: add a way to register dependencies by plugins

[sapphi-red]

Plugins may rely on a different file but there's no way to tell that information to lightningcss.

For example, the plugin below depends on .json placed next to the input file.

export function fooVisitor() {
  /** @type {string[]} */
  let currentStyleSheetSources
  return {
    StyleSheet(stylesheet) {
      currentStyleSheetSources = stylesheet.sources
    },
    Rule: {
      unknown: {
        foo(rule) {
          const from = currentStyleSheetSources[rule.loc.source_index]
          const importedFile = JSON.parse(fs.readFileSync(from + '.json', 'utf8'))
          const cssAst = convertJsonToAst(importedFile) // convert json to lightningcss somehow
          return cssAst
        },
      },
    },
  }
}

To make the re-transform happen when the json file is changed, the user that calls lightningcss.bundle needs to know which css file depends on which json file.

Simply having a convention (e.g. expose dependencies property from the visitor) would work if composeVisitors supports it, but having the information in TransformResult.dependency feels natural.

For reference postcss, achieves this via messages.
https://github.com/postcss/postcss/blob/main/docs/guidelines/plugin.md#31-use-messages-to-specify-dependencies
Maybe it makes sense to have a way to emit warnings from visitors as well.

[devongovett]

Is that something that lightning css itself needs to handle? Couldn't plugins accept a callback in their options or something?

export function fooVisitor(onDependency) {
  return {
    Rule(rule) {
      // ...
      onDependency(...);
    }
  }
}

Lightning css already doesn't handle loading plugins or composing them, that has to be done explicitly by the caller, so it's not clear where dependencies would go otherwise.

[sapphi-red]

I think it'd be better to be handled by lightning css or have a convention recommended by it, otherwise the way to achieve would be fragmented.

it's not clear where dependencies would go otherwise.

If you mean the way to register dependencies from the plugin, I can think of two ways:

1. add this.addDependencies: Rule(rule) { this.addDependencies(...) }
2. accept functions on visitor option and pass an object with a addDependencies method for visitors that are functions:

   visitor: ({ addDependencies }) => ({ Rule(rule) { addDependencies(...) } })

   (if a plugin wants to receive their own option they can be (options: PluginOptions) => (opts: { addDependencies: Function }) => Visitor)

[devongovett]

What I mean is that lightningcss itself doesn't use this info, so I'd rather not have to pass it back and forth between JS and Rust if it can live entirely in the JS layer.

I assume this is for Vite? How are you planning on loading/configuring plugins? I couldn't find it in the current docs.

[sapphi-red]

The ways I suggested doesn't require passing the data between JS and Rust.

I assume this is for Vite? How are you planning on loading/configuring plugins? I couldn't find it in the current docs.

It currently receives the options directly without any pre/postprocess via css.lightningcss.
https://stackblitz.com/edit/vitejs-vite-xtiiglue?file=vite.config.js&terminal=build
I can implement these (#877 (comment)) on Vite side, but that would (kind of) make those lightningcss Vite-specific.

[devongovett]

I suppose we could create a wrapper around transform/bundle that traverses the visitor and binds a this context to all of the functions. But not sure how expensive that would be. Right now the visitor functions are called directly from Rust.

[devongovett]

@sapphi-red I decided to go with your second idea of accepting a function as the visitor option which passes an addDependency function to the visitor. This way doesn't require binding all of the individual visitor functions, and will work even if you use arrow functions. Let me know if this works for you: #1170.