Skip to Content
GuideGetting Started

Getting Started

This guide will walk you through installing the Fusion packages and setting up the essential configurations for both your Sanity Studio and your frontend application.

Next.js Quick Start

Our Next.js starter template includes the Fusion UI packages installed and configured. You can use it as a starting point for your project.

npm init @codedazur/app@latest

Manual Installation

Although our internal boilerplates come with the Fusion UI packages installed and configured, you can also install them manually.

Prepare Your Project

You will need NPM or a similar package manager and a React project. This guide will assume you’re using Next.js, but any React framework will do.

Install Fusion UI

Install the Fusion UI package into your project:

npm install @codedazur/fusion-ui

Configure Transpilation

Fusion UI is published as a TypeScript library, so you’ll need to transpile it to JavaScript. Below are examples for our most common use cases.

next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  transpilePackages: ["@codedazur/fusion-ui"],
};
 
export default nextConfig;

Configure Vanilla Extract

Fusion UI is designed to be used with Vanilla Extract, so you’ll need to configure your bundler to use it. Below are examples for our most common use cases.

npm install -D @vanilla-extract/next-plugin
next.config.ts
import { createVanillaExtractPlugin } from "@vanilla-extract/next-plugin";
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  // ...
};
 
const withVanillaExtract = createVanillaExtractPlugin();
 
export default withVanillaExtract(nextConfig);
Note

For more detailed information, please refer to the Vanilla Extract documentation .

Core Concepts

App Component

The App component from @codedazur/fusion-ui conveniently provides the necessary styles and contexts that Fusion components need. The fastest way to get started is to wrap your application’s root with Fusion’s App component. It is not a strict requirement, in case you prefer a more manual approach.

app/layout.tsx
import { App } from "@codedazur/fusion-ui";
import { ReactNode } from "react";
 
export default function RootLayout(props: { children: ReactNode }) {
  return (
    <html lang="en">
      <App as="body">{props.children}</App>
    </html>
  );
}

As you can see, you can tell the App component to render as a body element.

Note

For more information on the App component, see the App Component documentation.

Using Components

The @codedazur/fusion-ui package provides a set of pre-built components that you can use in your project.

app/page.tsx
import {
  Button,
  ButtonGroup,
  Card,
  Center,
  Icon,
  IconButton,
  Image,
  Stack,
} from "@codedazur/fusion-ui";
 
export default function Home() {
  return (
    <Center>
      <Card
        media={
          <Stack justify="flex-end" align="flex-end">
            <Image src="/images/logo.png" alt="Logo" aspectRatio="4:3" />
            <IconButton margin={300} icon={Icon.Favorite} />
          </Stack>
        }
        title="Hello, world!"
        actions={
          <ButtonGroup orientation="horizontal">
            <Button variant="primary">Continue</Button>
            <Button variant="secondary">Cancel</Button>
          </ButtonGroup>
        }
      />
    </Center>
  );
}
Note

For more information on the components, see the Component Reference documentation. To see the components in action, visit the Storybook .

Theming

By default, the App component will use Fusion’s included darkTheme. If you want, you can change this to something else. You can import a different theme from @codedazur/fusion-ui/style, or you can create your own.

app/layout.tsx
import { App } from "@codedazur/fusion-ui";
import { lightTheme } from "@codedazur/fusion-ui/style";
import { ReactNode } from "react";
 
export default function RootLayout(props: { children: ReactNode }) {
  return (
    <html lang="en">
      <App as="body" theme={lightTheme}>
        {props.children}
      </App>
    </html>
  );
}

To create your own theme, you will need to call Vanilla Extract’s createTheme function with a contract and a set of values. You will need to define every single value of that contract, which you can do explicitly, or by merging with an existing theme.

themes/my-theme.css.ts
import { lightTheme, semanticTokens } from "@codedazur/fusion-ui/style";
import { merge } from "deepmerge-ts";
import { createTheme } from "vanilla-extract";
 
/**
 * This custom theme for the `semanticTokens` contract takes all of the values
 * of the `lightTheme` and overrides some of them with custom values.
 */
export const myTheme = createTheme(
  semanticTokens,
  merge(lightTheme, {
    colors: {
      primary: {
        base: "#0066ff",
        onBase: "#ffffff",
      },
    },
  }),
);

Now that the theme is defined, you can use it in your application.

app/layout.tsx
import { App } from "@codedazur/fusion-ui";
import { ReactNode } from "react";
import { myTheme } from "../themes/my-theme.css";
 
export default function RootLayout(props: { children: ReactNode }) {
  return (
    <html lang="en">
      <App as="body" theme={myTheme}>
        {props.children}
      </App>
    </html>
  );
}

Besides customizing the semantic tokens like in the example above, you can also customize the primitive tokens and component tokens.

Note

For more information on working with themes, see the Theming guide.

Component Overrides

You can swap out entire component implementations using the ComponentProvider. In the example below, we’re overriding the Image component to render a grayscaled image. The Hero component within that subtree will now use our custom Image component.

app/page.tsx
import { App, ComponentProvider, Hero, Image } from "@codedazur/fusion-ui";
 
function GrayscaleImage(props: ImageProps) {
  return <Image {...props} style={{ filter: "grayscale(100%)" }} />;
}
 
function MyComponent() {
  return (
    <ComponentProvider
      components={{
        Image: GrayscaleImage,
      }}
    >
      <App>
        <Hero image={{ src: "https://picsum.photos/200/300" }} />
      </App>
    </ComponentProvider>
  );
}
Note

The implementations you provide need to be compatible with the original component’s spec. For more information, see the Component Overrides guide.

Last updated on
Sanity Integration