Gatsby

Set up Vortex in an existing Gatsby 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 postcss@^8 @csstools/postcss-global-data postcss-custom-media cssnano gatsby-plugin-postcss

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 site.

Configure PostCSS

Vortex styles use @custom-media breakpoint queries that your build must resolve. Gatsby loads a CommonJS PostCSS config, so use postcss.config.js:

postcss.config.js

const { config } = require("@vortexlabs/vortex/config/postcss");

module.exports = config;

If you customize breakpoints, point PostCSS at your generated definitions; see Custom breakpoints.

Configure Gatsby

Vortex components import their CSS Modules as default exports, while Gatsby uses named exports by default. Configure gatsby-plugin-postcss to allow default exports. Keep any other options in your existing config.

gatsby-config.ts

import type { GatsbyConfig } from "gatsby";

const config: GatsbyConfig = {
  jsxRuntime: "automatic",
  plugins: [
    {
      resolve: "gatsby-plugin-postcss",
      options: {
        cssLoaderOptions: {
          esModule: false,
          modules: { namedExport: false },
        },
      },
    },
  ],
};

export default config;

jsxRuntime: "automatic" lets the files below use JSX without importing React. Restart the dev server after configuration changes.

Add the provider and theme

Import the generated theme and wrap your site with VortexProvider in the browser:

gatsby-browser.tsx

import "./src/themes/acme/globals.css";
import { VortexProvider } from "@vortexlabs/vortex";
import type { GatsbyBrowser } from "gatsby";

export const wrapRootElement: GatsbyBrowser["wrapRootElement"] = ({ element }) => (
  <VortexProvider defaultTheme="acme" defaultColorMode="light">
    {element}
  </VortexProvider>
);

Wrap it the same way during server rendering, and set the theme attributes on <html> so the first paint uses the right theme:

gatsby-ssr.tsx

import { VortexProvider } from "@vortexlabs/vortex";
import type { GatsbySSR } from "gatsby";

const htmlAttributes = {
  lang: "en",
  "data-vortex-theme": "acme",
  "data-vortex-color-mode": "light",
};

export const onRenderBody: GatsbySSR["onRenderBody"] = ({ setHtmlAttributes }) => {
  setHtmlAttributes(htmlAttributes);
};

export const wrapRootElement: GatsbySSR["wrapRootElement"] = ({ element }) => (
  <VortexProvider defaultTheme="acme" defaultColorMode="light">
    {element}
  </VortexProvider>
);

Use a component

src/pages/index.tsx

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

const IndexPage = () => (
  <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 IndexPage;

bun run develop

Fonts

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