Compatibily with @vitejs/react-plugin

[ArnaudBarre]

Configurations options

For reference here are the current options in 3.0.0-alpha.0:

interface Options {
    include?: string | RegExp | Array<string | RegExp>;
    exclude?: string | RegExp | Array<string | RegExp>;
    /**
     * Enable `react-refresh` integration. Vite disables this in prod env or build mode.
     * @default true
     */
    fastRefresh?: boolean;
    /**
     * Set this to `"automatic"` to use [vite-react-jsx](https://github.com/alloc/vite-react-jsx).
     * @default "automatic"
     */
    jsxRuntime?: 'classic' | 'automatic';
    /**
     * Control where the JSX factory is imported from.
     * This option is ignored when `jsxRuntime` is not `"automatic"`.
     * @default "react"
     */
    jsxImportSource?: string;
    /**
     * Set this to `true` to annotate the JSX factory with `\/* @__PURE__ *\/`.
     * This option is ignored when `jsxRuntime` is not `"automatic"`.
     * @default true
     */
    jsxPure?: boolean;
    /**
     * Babel configuration applied in both dev and prod.
     */
    babel?: BabelOptions | ((id: string, options: {
        ssr?: boolean;
    }) => BabelOptions);
}

include / exclude

This could be easily implemented, but I'm wondering if there is a usage for it.

For exclude, maybe some people want to ship un-transpiled non jsx files directly to the browser. But given that in a real world React codebase most of the code is in JSX or even TS/TSX, I'm questioning the need.

For include, I think this is because people want to transpile node_modules? But I think that a lot of work has been done supporting non-standard syntax in dependencies pre-bundling via esbuild.

The complexity in the plugin is low, but the runtime cost is not zero. The current implementation for the babel plugin uses various regex compare to path.extname + map access in this plugin

fastRefresh

This is the whole point of downloading 60mb of Rust. For punctual opt-out, if this plugin has very few options, people can just comment the plugin and get back to transpiling via esbuild.

jsxRuntime

This is already supported but by looking at the esbuild configuration. This can be changed for simplicity and compatibility.

jsxImportSource

Easy to implement but for people using TS it can be a duplication with TSConfig. Reading it like most tools does is a possibility but a non-zero cost when done in JS.

jsxPure

From my research this is not supported by SWC. This was added very recently do esbuild for a use case of a still WIP library. I'm not sure if I want to bother the maintainer of SWC for this myself. Plus this is a build only requirement, which is not an issue if SWC is dev-only.

babel

Obviously this doesn’t make sense. But the possibility to configure SWC is an open question. See conclusion

Use SWC for builds

esbuild is very well integrated in Vite, and with automatic jsx runtime support, there is no big need to use SWC in build mode. This makes the plugin a bit simpler.

I did an experiment to be able to benchmark but the issue is that disabling esbuild also disable minification. The build time went from 35s to ~44s on my professional project, but it's difficult to know the cause without fixing the minification issue. I will try to fix it in the coming days to make a fair benchmark (if you have a fix let me know).

For reference, the Babel plugin uses a mix of both in v3

Check for refresh boundaries

React refresh is an awesome tool, but it comes with some limitations, that sadly, are not shared the React core team. It's only on the React Native docs, but Next and Gatsby also made their own version.

The frustrating part as a React dev is that some tools tend to hide these limitations and just throw a full page reload at you without any notice (CRA, Vite, Bun). Next is the only good student here and logs a warning (with a stack trace 😕) in the terminal and in the browser (but it's not visible if logs are preserved). Gatsby gets around it by bundling every page and forbids export from pages.

IMO the limitations are worth the benefits, and they should be enforced by tools. There is nothing more painful that starting to debug a component written by a coworker and getting full-reload because the file also export a function at the bottom. So I made this ESLint plugin (And I'm still very surprised that the core team didn't make one compared to well-designed ESLint rules for hooks).

Side note: There is the same issue in Vite core with circular imports. It triggers a full page reload without explanations.

In the short term, I understand that not everyone want to install ESLint on every React project, so I could add some runtime checks like IanVS did for the Babel version. But I think that both plugins should at least log a warning. My opinion would be to keep HMR and display an overlay.

In the long term, we should push react-refresh implementations (only Babel and SWC in my knowledge, Bun has one but not usable outside the runtime currently) to take into account these limitations so that toolchain don't need to re-analyse all exports via additional plugins and fragile naming conventions. In my opinion they should throw an error pointing to the exact export that is causing an issue, but they could also give back a transpiled version without fast refresh enable and a warning that the toolchain can log. In that second case, the current check for code.includes("$RefreshReg$") would be enough and won't require additional checks and post invalidation.

Conclusion

SWC and esbuild are both incredible tools that support out of the box a lot of features like automatic jsx runtime and satisfies operator even before TS 4.9 is stable. I think that writing custom AST plugins attach to a specific compiler is not worth it anymore and that this plugin should have a very small API surface so that we can make performance improvements (ex caching), use a different compiler for builds or make it easy to migrate to a new one later. For this reason I don't think the plugin should allow custom configuration for SWC. People with special needs can still fork it (it's currently only 120 lines long) or patch it.

I would even go one step further and only support automatic jsx runtime so that the plugin don't have to do some
gymnastic to allow people to skip React imports. This also removes the need for the jsxImportSource option.

I think that keeping esbuild for build is safe and (still to be confirmed) even make builds faster. Also, keeping the possibility to use the same native tool for both transpiling and bundling is a game changer in terms of build speed. The web app I mentioned earlier that builds in 35s can be bundled in ~3s with a custom script using esbuild (most time being spent on loading and running PostCSS).

I'm open to discuss all the points above and know more about different usage of React toolchains. The only thing I'm sure of is that given the extensibility of Vite plugin system, multiple plugins with different trade-offs can exist. The main question is what should be the default trade-offs that the core team recommends?

[patak-dev]

Thanks for the detailed write-up of your current rationale @ArnaudBarre!

About configurations options, my take is that we could release the plugin without most options as you propose, and then wait for users to request them with proper use cases. Supporting only the automatic jsx runtime for example may be a good idea, given that users can still fall back to the current react plugin to support legacy.

About configuring SWC, I see your point in pushing to try to keep it as standard as possible so it is easier to later change things on our side. But we have seen that providing an escape hatch like swcOptions (like esbuildOptions) is useful for the ecosystem when integrating with Vite. I think we could wait to have a use case on the repo before adding it, but it may be a good way to keep the API surface small for everybody while letting people work around some edge cases. People know that configuring swcOptions is an SWC-specific customization that may later require work if Vite decides to use a different tool. Also, if the plugin is called @vitejs/plugin-react-swc, we will not be using this package if we later recommend another tool (Bun?), so the option is a bit safer than if it would be added to @vitejs/plugin-react.

About the check for refresh boundaries, keeping HMR and a warning by default doesn't sound bad if it is what Next and other react frameworks are doing. I would like to hear the opinion of others here (cc @IanVS, @cyco130, @frandiox, @aleclarson)

[ArnaudBarre]

if it is what Next and other react frameworks are doing

Next currently only doing a warning/error in the console.

I think we could wait to have a use case on the repo before adding it

I agree. I'm not against adding swcOptions when people ask for it, but I would like to understand the need to see if we can solve some issues in Vite instead of having people adding edge case configuration from other tools.

[IanVS]

OK, thanks. I'm still 👎 on blocking like that. I can't stand when linting tools or typescript prevent me from compiling otherwise valid code (like CRA does, or at least did at one time). I think it will result in frustration from folks who won't understand what's happening or how to fix the problem, or who would have been otherwise fine with a page reload. It takes many 1s updates to equal the time it takes to understand and then resolve the issue. Teaching about it in a console warning would be one thing, but forcing users to rearchitect their file so that fast-refresh works feels like a bridge too far to me. (I'm only sharing my opinion because it was requested, I don't have a real horse in the race, but I can say I will personally not use the plugin if it does this with no way to disable it).

[patak-dev]

I think the best here would be to issue a warning by default in the console or terminal, maybe after a full refresh? So an improvement over our current DX, but still keep the same. And then add an option to opt into a more strict error explaining the tradeoffs. I also think that for a first impression it is better to let the users work even if the HMR structure of the app is way than ideal. A proper message hinting to them how to improve things could be good enough to push users in the right direction without making them angry by default.

[ArnaudBarre]

Yes true sometimes you want to test something hacky to make sure it works before changing things to make the linters happy. This is one of the reason I created my own eslint plugin. So yeah I agree that overlay is probably too disruptive.

I will try to make an implementation for warning (ideally terminal plus browser after reload, which is not trivial).

And after reflexion, given the eslint rule, maybe a stricter check is not needed

[patak-dev]

I think we can start with terminal only that should be easier. It would be interesting to see if we could add a vite:afterFullReload event although as you said, it may be hard to get right.

[dominikg]

include / exclude
This could be easily implemented, but I'm wondering if there is a usage for it.

• multiple plugin instances with different config for different parts of the app
• excluding files like something.totally-not-react-but-still-ends-with.jsx or something.spec.jsx

vite exports createFilter so you really don't have to do much to support it
https://github.com/sveltejs/vite-plugin-svelte/blob/main/packages/vite-plugin-svelte/src/utils/id.ts#L2
https://github.com/sveltejs/vite-plugin-svelte/blob/main/packages/vite-plugin-svelte/src/utils/id.ts#L120-L121

[ArnaudBarre]

Can share a bit more about your need to override transform on your custom project?

[ElMassimo]

Sorry, you read my comment faster than I was able to remove that. I realized I only need to do that because the plugin doesn't have support for include/exclude, as long as the plugin configures esbuild to manage the remaining JSX files.

The idea is, you could be importing JSX files that are not from a node_module, and you would want the JSX transform to happen for those (esbuild or SWC), but don't need HMR for those so the additional transform would be a waste of time.

Example: importing an internal library of components/icons in a monorepo.

[ArnaudBarre]

I will benchmark this but I'm pretty sure the cost of swc adding fast refresh is pretty negligeable.

For that specific need, I think instead we should enable "pre-bundling" of chunks or src via esbuild. So that you reduce the number of files vite has to process (currently an open question in the discussion thread on discord)

Then we could update the plugin to consider this new form of pre-bundle like node_modules, removing the need for people to configure it twice

[ElMassimo]

Allowing to pre-bundle dependencies "outside" node_modules would address the use case I have.

the cost of swc adding fast refresh is pretty negligeable.

It would be interesting to benchmark this in cases where the source file itself is almost smaller than the HMR injected portion. For example, a library with hundreds of icons (as React components).

[ArnaudBarre]

So I did some manual benchmarks on my codebase (180 tsx modules, 70 ts modules):
After multiple restart re-using the same browser tab, i started to get some stable timings for document load event

• all swc: 3.4-3.5s
• all esbuild: 3.2-3.3s
• tsx with swc, ts with esbuild: 3.9s (very strange)

It requires more investigation on bigger codebase and cleaner benchmarking, but I think that the real usecase to solve is really pre-bundling of "stable parts" of the app that can enable more significative improvements

[black7375]

I did an experiment to be able to benchmark but the issue is that disabling esbuild also disable minification. The build time went from 35s to ~44s on my professional project, but it's difficult to know the cause without fixing the minification issue. I will try to fix it in the coming days to make a fair benchmark (if you have a fix let me know).

As far as I know, vite's build.minify depends on esbuild.
Therefore, if you disable esbuild, minify does not work.

If you need it instead, you will be able to provide swc's minify like vite-plugin-swc-only that I just found.
(It looks like a fork of this project)