How to use in an external package consumed by other projects?

[mattfelten]

Reading the docs I see how to get set up and seems pretty straightforward for one project.

How do you recommend setting this up where the theme and CSS would be in project-one which is published and then consumed by project-two/three/etc (think design system)? I could see either needing to compile before publishing or needing to have any consumer project adjust their build setup. Do you have any guides for this type of setup?

[TheComputerM]

I too would like to know more about this, maybe like a ContextProvider in vanilla-extract.

[TheComputerM]

This is a serious issue as dynamic imports do not work in vanilla extract

[rtkaaho]

I have been able to to get this to work using vite in lib mode. You essentially need to just createGlobalTheme's and be sure they are exported in your entry file. vanilla-extract will then parse through your typescript and generate a style.css file that is comprised of all of your themes and css variables.

Consuming the themes in a different package just involves importing the style.css and then importing the theme that you want. Typically it is best to use the theme contract api.

Here is a really simple example of what I have done:

// contract.css.ts

const contract = createThemeContract({
  brand: {
    blue: {
      primary: {
        base: null,
        low: null,
        mid: null,
        high: null,
      },
      secondary: {
        base: null,
        ultra: null,
        low: null,
        mid: null,
        high: null,
      },
    }
  }
});

// light.css.ts

const lightColors = createGlobalTheme("html[data-theme-mode='light']", contract, {
  brand: {
    blue: {
      primary: {
        base: toRGB("#23618E"),
        low: toRGB("#A7C0D2"),
        mid: toRGB("#1C4E72"),
        high: toRGB("#153A55"),
      },
      secondary: {
        base: toRGB("#3195D2"),
        ultra: toRGB("#ECF7FF"),
        low: toRGB("#9ED7FF"),
        mid: toRGB("#2777A8"),
        high: toRGB("#0A1E2A"),
      },
    },
  }
});

// dark.css.ts

const darkColors = createGlobalTheme("html[data-theme-mode='dark']", contract, {
  brand: {
    blue: {
      primary: {
        base: toRGB("#9ED7FF"),
        low: toRGB("#C5E7FF"),
        mid: toRGB("#5AAADB"),
        high: toRGB("#3195D2"),
      },
      secondary: {
        base: toRGB("#3195D2"),
        ultra: toRGB("#ECF7FF"),
        low: toRGB("#9ED7FF"),
        mid: toRGB("#2777A8"),
        high: toRGB("#0A1E2A"),
      },
    },
  }
});

// index.ts (entry point of the lib)

import colors from "./contract.css";
import light from "./light.css";
import dark from "./dark.css";

export { colors, light, dark };

Then using this in something like a react application.

Import the generated css into the app

/* index.css */

@import "@my-lib/css/style.css";

Use the contract vars in any component. Can be used with vanilla-extract, styled-components, emotion, etc. Any css-in-js lib you want :)

// my-component.tsx

import { colors } from "@my-lib/css";

const MyComponent = () => {
  return (
    <div style={{ background: colors.brand.blue.primary.base }}>
     My component text
   </div>
  );
};

[rtkaaho]

Then changing between themes is as simple as document.getElementsByTagName('html')[0].setAttribute('data-theme-mode', 'dark') or document.getElementsByTagName('html')[0].setAttribute('data-theme-mode', 'light').

[christiankaindl]

This is also how I also currently do it, but it would be nicer if you wouldn't need to import the generated CSS explicitly (as a consumer). That would make components more self-contained.

Vite has a feature that handles this when you import regular .css files, which automatically adds the CSS in a <style> tag to the page when you import a component (https://vitejs.dev/guide/features.html#css). Haven't yet figured out how this would work with vanilla-extract though.

[mattcompiles]

Pre-compiling and compiling in the consuming application could both work but I personally suggest adjusting the consuming applications bundling config if possible. So basically shipping .css.js files in your package to then be compiled into .js/.css in the consuming app. Our design system uses this approach.

[mattfelten]

That does seem like a good approach if you have control of the build in the consuming app. I'm working on a project used by ~20 different apps and don't have access to all their build configs, so pre-compiling seems like the way to go.

[rtkaaho]

One fear I have with pre-compiling is that if you plan on using sprinkles to create atomic styles, the amount of css generated can get pretty large. At this point, I am not sure how we could go about purging any unused css that is generated from sprinkles/vanilla extract. Either way you would need to edit the consuming apps build configs imo.

[dannyrb]

@mattcompiles , is this still the case? "main" for the design system appears to look at: lib/components/index.ts

I see your ESBuild config, but I don't see a dist folder for the published NPM package:
https://unpkg.com/browse/[email protected]/

I think where I'm struggling is getting Webpack to build the primary bundle, and to keep the .css.js separate. I'll keep playing around. Would love to help update the docs to include a "publishing a library" section w/ different bundler configs.

[mattcompiles]

@dannyrb Yeah it's still the case. The braid setup is quite complicated for legacy reasons but we're definitely staying with the compile in the application approach. We're also planning on doing some changes in braid that should be a better example use-case for reference outside of Seek. That will come hopefully sometime early next year.

I agree this is something that should be documented specifically, it's on my ever-growing list of things I should do 😅. If you're keen to work on this I'd encourage a blog post to start with as we're not even sure where it fits within the current docs site IA.

[cadbox1]

I wanted to do the same thing and ended up pre-compiling largely based on @rtkaaho's approach.

The package is cadells-vanilla-components and you can see how it's used in cadells-nextjs-template.

I ended up using tsup which is based on esbuild after running into some issues with a rollup that I couldn't work out.

Hope that helps someone!