Webpack

Set up Vortex in an existing webpack React project.

Install the packages

Vortex packages are private and available by invitation. Complete the package access prerequisites before installing.

bun add @vortexlabs/vortex @vortexlabs/vortex-themes

bun add -d style-loader css-loader postcss-loader postcss@^8 @csstools/postcss-global-data postcss-custom-media cssnano

Generate your theme

Create vortex.config.ts at your project root. Replace acme with your theme name; an empty definition inherits Vortex's defaults.

vortex.config.ts

import type { VortexThemeConfig } from "@vortexlabs/vortex-themes";

const config: VortexThemeConfig = {
  themes: {
    acme: {},
  },
};

export default config;

Add a script to your existing package.json:

package.json

"scripts": {
  "build:theme": "vortex-themes theming --output ./src/themes"
}

bun run build:theme

This creates src/themes/acme/. Run it again after changing vortex.config.ts or upgrading Vortex packages, before starting or building your app.

Configure PostCSS

Vortex styles use @custom-media breakpoint queries that your build must resolve. Add the package's PostCSS preset:

postcss.config.mjs

import { config } from "@vortexlabs/vortex/config/postcss";

export default config;

If you already have a PostCSS config, merge the preset's plugins into it. If you customize breakpoints, point PostCSS at your generated definitions; see Custom breakpoints.

Configure CSS loading

Vortex components import their CSS Modules as default exports and use class names with dashes. css-loader defaults to named exports, which leaves the page blank without a build error. Set namedExport: false and keep class names as written. Keep your existing rules and options.

webpack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: {
                auto: true,
                namedExport: false,
                exportLocalsConvention: "as-is",
              },
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};

Restart the dev server after configuration changes.

Add the provider and theme

Set the theme attributes on <html> in your HTML template so the first paint uses the right theme:

index.html

<html lang="en" data-vortex-theme="acme" data-vortex-color-mode="light">

In your entry file, import the generated theme and wrap your app with VortexProvider:

src/main.tsx

import "./themes/acme/globals.css";
import { VortexProvider } from "@vortexlabs/vortex";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <VortexProvider defaultTheme="acme" defaultColorMode="light">
    <App />
  </VortexProvider>,
);

Use a component

src/App.tsx

import { Button, Stack, Text } from "@vortexlabs/vortex";

const App = () => (
  <Stack gap={4}>
    <Text as="h1" size={{ xs: "heading-xl-mobile", sm: "heading-xl-desktop" }}>Hello Vortex</Text>
    <Button variant="primary">Get started</Button>
  </Stack>
);

export default App;

bun run dev

Fonts

Vortex doesn't load font files. Follow the Fonts guide to load the default fonts or your own.