Goal

The goal of the project is to produce a UI widget set that works well with Solid.js and SSR.

Requirements

• No CSS-in-JS generated at runtime. This produces an ugly flash of unstyled content when the page is rendered on the server.
• Users of the library should only have to bundle what is needed:
  • All JavaScript needs to be tree-shakeable.
  • CSS resources should not be prematurely bundled - instead, a separate CSS resource for each widget. If the user wants to combine CSS resources, they can do that in the bundler for their app.
• Users of the library should not be constrained to using the same CSS framework as the library. Instead, the CSS bundled with the library should be static CSS that has already been processed.

Current Status

Currently I am using vanilla-extract to generate CSS resources from TypeScript at build time. There is a small amount of runtime for generating class name lists, but this is SSR-compatible.

Vanilla-extract requires a bundler - it will work with esbuild, Vite, Webpack, rollup, and some others. This means that in a production app, the library gets bundled twice: once at the library level, and once at the application level.

In order to work with Solid SSR, the library needs to provide something close to the original source, with the JSX tags preserved. However, at minimum the files in dist/ should be run through tsc, because the application may have a tsconfig.json with different compiler options. (Most tsconfig options don't affect how the code is written, but some - like isolateModules - can have an impact on how the code is written.)

Other than stripping type annotations and resolving stylesheet import references, the bundler at this level should do as little as possible.

Bundling Options

Here is a list of the various possible bundling options:

• tsc - this is the simplest solution, unfortunately it doesn't work because there's no vanilla-extract plugin for tsc.
• esbuild has nothing like a "preserveModules" option, meaning that the only option is to combine all JavaScript into a single output file. While this file is tree-shakeable, the problem is that there's no way to tree-shake CSS - the file has to include an import for every generated stylesheet, and the app has no way to exclude stylesheets that are not being used.
• vite While vite does have a 'library mode', the problems are similar to esbuild: there's no way to generate individual modules for each source file.
• rollup - there is both a vanilla-extract plugin and a preserve modules option. This almost works, however rollup isn't smart enough to preserve the '.jsx' extension on files containing JSX syntax. In other words, input files with the extension '.tsx' get mapped to '.js' even when the JSX option is set to "preserve". This causes the application-level bundler to choke.
  • There is a rollup plugin which can be used to customize output file extensions, however it is old, appears to be unmaintained, and I could not get it to work.

As you can see, none of these options currently work.

Alternatives

The most obvious approach is to abandon using vanilla-extract and re-write all of the stylesheets in SASS, possibly using CSS modules. However, in doing so I lost a lot of the benefits of vanilla-extract - type safety for CSS classes, dead code discovery, and so on.

In this case, I would probably then use plain tsc for generating the dist folder.