How to use libraries built with Vanilla Extract in development mode with Vite (optimizeDeps issue)

[bestickley]

Hi, I've created a UI component library using vanilla extract called gboost-ui. I built the library by simply using tsc such that my .css.ts files are compiled to a .css.js file. When I install the library in an app built with Vite and do a production build everything runs smoothly. However, when I run vite in development server mode, dependencies (including gboost-ui) are pre-bundled such that they are not transformed by @vanilla-extract/vite-plugin (I think) and I get this error:

vanilla-extract-css-fileScope.browser.esm.js:27 Uncaught Error: Styles were unable to be assigned to a file. This is generally caused by one of the following:

- You may have created styles outside of a '.css.ts' context
- You may have incorrect configuration. See https://vanilla-extract.style/documentation/getting-started
    at getFileScope (vanilla-extract-css-fileScope.browser.esm.js:27:11)
    at generateIdentifier (vanilla-extract-css.browser.esm.js:159:7)
    at style (vanilla-extract-css.browser.esm.js:345:19)
    at FooterArea.css.js:2:27

However, if I install gboost-ui locally and link it to my Vite app then the development server successfully runs! I think this is because the gboost-ui is not being pre-bundled so @vanilla-extract/vite-plugin is transforming the code.

A potential solution to this issue is that I could add to my vite.config.ts:

{
  ...,
  optimizeDeps: { exclude: "gboost-ui" },
  plugins: [
      react(),
      vanillaExtractVitePlugin(),
    ],
  ...,
}

BUT I have CJS dependencies within gboost-ui that then throw errors.
Vite uses esbuild to pre-bundle dependencies so I tried in my vite.config.ts:

optimizeDeps: {
      esbuildOptions: {
        plugins: [vanillaExtractEsbuildPlugin()],
      },
    },

but then I got the error:

 ERROR  Error:   Failed to scan for dependencies from entries:                                                                                                                                                                                    15:05:28
  /Users/stickb/Code/scratch/stickb-crud-postgres/ui/index.html

  ✘ [ERROR] Cannot import "vanilla-extract-css-ns:src/App.css.ts.vanilla.css?source=KiwgKjo6YmVmb3JlLCAqOjphZnRlciB7CiAgYm94LXNpemluZzogYm9yZGVyLWJveDsKfQoqIHsKICBtYXJnaW46IDA7CiAgZm9udC1mYW1pbHk6IHZhcigtLWFtcGxpZnktZm9udHMtZGVmYXVsdC12YXJpYWJsZSk7Cn0KaHRtbCxib2R5IHsKICBoZWlnaHQ6IDEwMCU7Cn0KYm9keSB7CiAgbGluZS1oZWlnaHQ6IDEuNTsKICBmb250LXNtb290aDogYW50aWFsaWFzZWQ7Cn0KaW1nLCBwaWN0dXJlLCB2aWRlbywgY2FudmFzLCBzdmcsIGlmcmFtZSB7CiAgZGlzcGxheTogYmxvY2s7CiAgbWF4LXdpZHRoOiAxMDAlOwp9CnAsIGgxLCBoMiwgaDMsIGg0LCBoNSwgaDYgewogIG92ZXJmbG93LXdyYXA6IGJyZWFrLXdvcmQ7Cn0KI3Jvb3QsICNfX25leHQgewogIGlzb2xhdGlvbjogaXNvbGF0ZTsKfQphIHsKICBhbGw6IHVuc2V0Owp9" into a JavaScript file without an output path configured

    src/App.css.ts:1:7:
      1 │ import 'src/App.css.ts.vanilla.css?source=KiwgKjo6YmVmb3JlLCAqOjphZ...
        ╵        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


✘ [ERROR] Cannot import "vanilla-extract-css-ns:src/components/NavAsideLink.css.ts.vanilla.css?source=Lk5hdkFzaWRlTGlua19saW5rX18xNXBteHpqMCB7CiAgdGV4dC1kZWNvcmF0aW9uOiBub25lOwp9Ci5OYXZBc2lkZUxpbmtfYWN0aXZlTGlua19fMTVwbXh6ajEgewogIGJhY2tncm91bmQtY29sb3I6IHZhcigtLWFtcGxpZnktY29sb3JzLW5ldXRyYWwtNDApOwp9" into a JavaScript file without an output path configured

    src/components/NavAsideLink.css.ts:1:7:
      1 │ import 'src/components/NavAsideLink.css.ts.vanilla.css?source=Lk5hd...
        ╵        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


    at failureErrorWithLog (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:1636:15)
    at /Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:1048:25
    at runOnEndCallbacks (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:1471:45)
    at buildResponseToResult (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:1046:7)
    at /Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:1058:9
    at new Promise (<anonymous>)
    at requestCallbacks.on-end (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:1057:54)
    at handleRequest (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:723:19)
    at handleIncomingPacket (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:745:7)
    at Socket.readFromStdout (/Users/stickb/Code/scratch/stickb-crud-postgres/node_modules/.pnpm/[email protected]/node_modules/esbuild/lib/main.js:673:7)
    at Socket.emit (node:events:513:28)
    at addChunk (node:internal/streams/readable:324:12)
    at readableAddChunk (node:internal/streams/readable:297:9)
    at Readable.push (node:internal/streams/readable:234:10)
    at Pipe.onStreamRead (node:internal/stream_base_commons:190:23)

Does anyone have a solution?

There are likely a number of way to solve this issue, but I think the best would be to try and use @vanilla-extract/esbuild-plugin to transform vanilla extract .css.js files into styles into the pre-bundled dependencies.

Vite Docs:

You can further customize esbuild too with the optimizeDeps.esbuildOptions option. For example, adding an esbuild plugin to handle special files in dependencies.

VE files are "special files" so an esbuild plugin should be used to handle them but the vanilla extract one gives me an error as shown above.

UPDATE:
I realized the the error shown above are about files in the consuming application (App.css.ts, and NavAsideLink.css.ts). Maybe the vanilla extract plugins are working against each other here since I'm using the vite plugin AND esbuild plugin?

[bestickley]

Solved!
The key here is the line: plugins: [veEsbuildPlugin({ runtime: true })], in the below vite.config.ts:

import { defineConfig, loadEnv } from "vite";
import { createHtmlPlugin } from "vite-plugin-html";
import { vanillaExtractPlugin as veVitePlugin } from "@vanilla-extract/vite-plugin";
import { vanillaExtractPlugin as veEsbuildPlugin } from "@vanilla-extract/esbuild-plugin";
import tsconfigPaths from "vite-tsconfig-paths";
import _react from "@vitejs/plugin-react";
// https://github.com/vitejs/vite/issues/10481
const react = _react as unknown as typeof _react.default;

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd());
  return {
    optimizeDeps: {
      esbuildOptions: {
        plugins: [veEsbuildPlugin({ runtime: true })],
      },
    },
    plugins: [
      react(),
      createHtmlPlugin({ inject: { data: env } }),
      tsconfigPaths(), // needed for baseUrl tsconfig option
      veVitePlugin(),
    ],
    resolve: {
      alias: [
        {
          // https://ui.docs.amplify.aws/getting-started/installation#vite
          find: "./runtimeConfig",
          replacement: "./runtimeConfig.browser",
        },
      ],
    },
  };
});

runtime: true is what's required for development mode.

[chris-ldgk]

Adding to @bestickley wonderful answer, for me that was only part of the issue, as I also use Astro (and thus vite's SSR functionality to render my pages).
The above solution fixed the client side issues for me, the fix for the issue on the server side was also adding my packages that use VE for styling for noExternal like follows:

export default defineConfig({
    optimizeDeps: {
      esbuildOptions: {
        plugins: [veEsbuildPlugin({ runtime: true })],
      },
    },
    plugins: [
      react(), veVitePlugin()
    ],
    ssr: {
      noExternal: ["@your-namespace/your-component-package-name"],
    },
})

Hope this helps anyone that's also using Astro or Vite SSR.