MacawUI

Official React UI components kit for Saleor — an open-source GraphQL-first and Next.js ready e-commerce platform. You can find most of the elements used in the creation of Saleor's dashboard interface and use it to create Saleor Apps. Have a great time working on your projects and empowering your users. If you have any questions, feel free to let us know on GitHub Discussions.

Installation

npm i @saleor/macaw-ui

Note that this package still bundles the old version of MacawUI so it still depends on the following Material-UI v4 packages: @material-ui/core, @material-ui/icons and @material-ui/lab. If your project doesn't have them installed and you're not using npm v7 with automatically installed peer dependencies then you'll need to install them manually:

npm i @material-ui/core @material-ui/icons @material-ui/lab

Usage

You need to import the styles into your app. You can do it in your main entry point, for example index.tsx`:

import "@saleor/macaw-ui/next/style";

Next, you need to add the ThemeProvider to your app. It will provide the theme to the components:

import { ThemeProvider } from "@saleor/macaw-ui/next";

const App = () => (
  <ThemeProvider>
    <App />
  </ThemeProvider>
);

Usage with Next.js

As mentioned above, we still bundle the old version of MacawUI so you need to add the following to your next.config.js:

/** @type {import('next').NextConfig} */
module.exports = {
  experimental: {
    esmExternals: false,
  },
};

It tells Next.js not to use ESM exports for external modules. This is needed because MacawUI dependencies (Material-UI v4) are still using CommonJS exports.

If you need to render styles on the server we recommend that you use getCSSVariables helper to get the CSS variables that can be injected in _document.tsx:

import { getCSSVariables } from "@saleor/macaw-ui/next";
import Document, { Head, Html, Main, NextScript } from "next/document";

const css = getCSSVariables("defaultLight"); // or "defaultDark"

export default class AppDocument extends Document {
  render() {
    return (
      <Html style={css}>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

If you are using Next.js in version 13 and you got this error:

NonErrorEmittedError: (Emitted value instead of an instance of Error) ReferenceError: $RefreshReg$ is not defined

Try to change sprinkles imports from @saleor/macaw-ui/next to @saleor/macaw-ui/next/theme.

Reference

Usage with form libraries

React Hook Form

You need to wrap the MacawUI component with Controller. For example:

import { Input } from "@saleor/macaw-ui/next";

<Controller
  control={control}
  name="name-input"
  render={({ field }) => <Input {...field} />}
/>;

Usage with Sentry

Add following configuration to Sentry.Integrations.Breadcrumbs:

{
  dom: {
    serializeAttribute: ["macaw-ui-component"];
  }
}

Right now sentry will display MacawUI components names in breadcrumbs.

Development

To begin, you need to install dependencies:

pnpm install
cd legacy && npm install

Then, you can run the Storybook:

pnpm dev

You can run build in watch mode (useful for real-time development with e.g Dashboard):

pnpm watch

License

Distributed under the Creative Common Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/

Thanks

Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.

qunm00/macaw-ui