JS visitor plugin deprecation roadmap

[kwonoj]

Status	Last Updated	Target version
Open	2023.Jul.18	2

Summary

This RFC proposes a migration for JS-based plugins when @swc/core no longer offers support, by creating a userland wasm plugin that runs a JS visitor with limited runtime support.

Motivation

After introducing a new plugin system based on wasm / rust native codes, core team has been seeking for a path for the legacy, JS plugin support. The current architecture may not be able to address the known limitations, so the core team is considering consolidating efforts to support a new plugin system with wasm instead of having 2 different plugin systems, which could cause fragmentation.

So far as we aware, there aren't a lot of SWC plugins written in JS and hope this workaround provides time to migrate those plugins into new one once after core does not support to running JS visitors.

Detailed design

1. Introducing user-land wasm plugin can run JS visitor

   The core of this proposal is moving JS visitor execution to the userland. Instead of relying on host (node.js for @swc/core, non-exist for any other platforms like swcx or @swc/wasm) runtime that executes JS, a wasm plugin can embed a modest JS interpreter. Plugin internally interops between seralized AST to the JSON payload that JS visitor accepts.

   Initial implementation to the plugin can be found at swc-plugin-js-transformer, currently able to execute the simplest plugins with below examples:

   // visitor.js
   // The actual JS visitor plugin user writes
   class TransformVisitor extends Visitor {
       visitCallExpression(n) {
           if (n?.callee?.object?.value === "console") {
               if (n.arguments.length >= 1) {
               n.arguments[0].expression.value = "from_plugin";
               n.arguments[0].expression.raw = `"from_plugin"`;
               }
           }
           return n;
       }
   }
   
   // calling plugin
   transformSync(`console.log("hello")`, {
     jsc: {
       experimental: {
         plugins: [
          [ 'swc-plugin-js-transformer',
           {
            //Relative path to the plugin visitor implementation	         
            transformImplPath: 'visitor.js'
            /* In case of inherited class name is different to `TransformVisitor`
            visitorClassName: 'SomeClass'
            */
           }
          ]
         ]
       }
     }
   })

   Calling plugin is pretty much similar to any other swc plugins. Difference is the plugin is a thin layer to the JS visitor, that only executes & interop AST back and forth.

   As example illustrates there are some differences between usual JS implementation to the visitor supplied to the plugin. There's no import to base class, as well as no exports. The plugin is sandboxed and does not support module resolution, so plugin-js-transformer adds the base class and executes automatically.

2. @swc/[email protected] warns plugin deprecation

   Once after plugin releases, @swc/core will emit a warning message if configuration specifics plugin. @swc/core will emit a warning message if the configuration specifies a plugin, but this is not a hard failure.

3. JS-transformer plugin owns @swc/core/visitor

   Instead of depending on @swc/core/visitor, js transformer plugin owns JS visitor directly. This may not remove the existing visitor from @swc/core yet to avoid breaking changes.

4. @swc/core@2 release with breaking changes

   @swc/core@2 removes configuration option for the existing plugin, as well as @swc/core/visitor implementation.

5. Deprecate / archive js-transformer plugin

   After some time period, gracefully archive js transformer plugin.

Drawbacks

This is soft landing plan, but still it doesn't provide 100% compatibility. Notably, since plugin will run its own JS engine, it is not identical to the node.js runtime. There won't be equivalent JS module support, and most of JS runtime features will not be available as well. It may possible to stopgap some important blockers for the JS visitor though.

Alternatives

• We could hard-deprecate without this migration support and force users jump to the new plugin with @swc/core@2 release.

Unresolved questions

References (if exists)

• https://github.com/kwonoj/swc-plugin-js-transformer

[kwonoj]

Clarification just in case, this RFC does not discuss if @swc/core should keep the current JS visitor for the next major release. Unless core team can find a major breakthrough, supporting JS visitor is not in the current roadmap - and even if it really happens, it is likely entirely different to how current JS visitor works so we won't keep current implementation.