Getting Started

How to setup and get started with Marigold.

To integrate Marigold into your React app, follow the steps outlined below. Marigold provides a wide range of pre-designed UI components. However, Marigold's components come with no styling by default. To ensure a perfect fit with your product's appearance, you must also install one of the predefined themes.

Please bear in mind that certain steps may vary depending on your specific setup. You can find examples for the most common setups down below.

Good to know!

Experience Marigold right away by trying it out in our interactive playground!

1. Installation

Begin by instaling the core Marigold package (@marigold/components) into your app using your preferred package manager. This package is always required, regardless of the theme you choose to apply later.

Execute the following command in your project's directory:

npm install @marigold/components --save

2. Theming

As mentioned earlier, Marigold components come without any styles by default. To customize their appearance, you can choose from the existing themes listed below:

  • b2b: Ideal for developing new standalone software applications.
  • core: Suitable for developing or refactoring components within the Reservix System.

Selecting a theme will enable you to seamlessly apply a consistent look and feel to all components, ensuring they harmonize with the rest of your app. Each theme comes as its own package:

  • @marigold/theme-b2b will give you the appearance for standalone software.
  • @marigold/theme-core will match the look and feel of the Reservix System.

Once you have decided on a theme, proceed to install it using your preferred package manager, similar to the way you installed the @marigold/components package earlier.

3. Tooling

Marigold effortlessly integrates with popular bundlers such as webpack, rollup, esbuild, and vite, as well as frameworks like Next.js, without requiring any additional configurations.

That being said, we strongly recommend adhering to the guidance provided by the React Team. If you are creating a new app or a site entirely with React, it is advisable to use a framework. You can find more details about this recommendation in the React docs.

Furthermore, if you are using TypeScript, ensure that you add @types/react and @types/react-dom to your project. Marigold's components are fully typed, enabling you to benefit from static type checking and IDE autocomplete features for enhanced development efficiency.

4. Bootstrapping

To set up Marigold in your project, you have two options based on the scale and needs of your app. Regardless of the chosen setup, it is essential to add the MarigoldProvider to your application's root. This ensures that components can access the theme and apply their corresponding styles.

Using the provided CSS file

The easiest way to start is by using the provided CSS file that comes with each theme. While this method allows for a quick start, it does not offer customization options beyond using the provided design tokens. This setup is sufficient for smaller and simpler applications.

/** * 1. Import the CSS file and theme */ import theme from '@marigold/theme-b2b'; import '@marigold/theme-b2b/styles.css'; /** * 2. Import the MarigoldProvider */ import { MarigoldProvider } from '@marigold/components'; /** * 3. Wrap your app into the MarigoldProvider * and pass it the selected theme */ export const App = () => ( <MarigoldProvider theme={theme}>{/* Your App */}}</MarigoldProvider> );

Using Tailwind CSS

However, if you want to maximize the benefits of Marigold, you should install Tailwind CSS alongside Marigold. This combination not only enables customization and extension of the selected theme but also allows you to take full advantage of Tailwind's features while staying true to our design system.

To set up Tailwind CSS, please refer to the official installation guide. Once you have completed the installation, add the chosen theme as a preset to the Tailwind CSS config, as shown below:

import { Config } from 'tailwindcss/types/config'; // If you are using another theme, change the name accordingly import { preset } from '@marigold/theme-b2b/preset'; const config: Config = { content: [ // Dont forget to add the glob for your app here ...preset.content, ], presets: [preset], }; export default config;

Please make sure that you have a postcss.config.js file with the following content in your project:

module.exports = { plugins: { tailwindcss: {}, autoprefixer: {}, }, };

This will set up TailwindCSS as a PostCSS plugin and works with common tools, like vite or next.js.

TypeScript Configuration

If you are using TypeScript, make sure to set the module resolution to 'nodenext' since the theme packages are using ESM.

After configuring Tailwind CSS and adding the preset, wrap your app with the MarigoldProvider. Unlike before, you no longer have to import the CSS file of the selected theme separately.

Tailwind CSS will automatically generate the required CSS for you. However, remember to import the generated CSS file somewhere in your project. Depending on your setup, this is typically done in the root file where you bootstrap React or, in case of Next.js in our root layout file.

/** * 1. Import the CSS file and theme */ /** * 2. Import the MarigoldProvider */ import { MarigoldProvider } from '@marigold/components'; import theme from '@marigold/theme-b2b'; /** * 3. Wrap your app into the MarigoldProvider * and pass it the selected theme */ export const App = () => ( <MarigoldProvider theme={theme}>{/* Your App */}}</MarigoldProvider> );

Adding Fonts

Certain themes, such as the B2B theme, are designed to utilize custom web fonts. To incorporate these fonts, you have two options:

  1. Use Font Source to add them.
  2. If you are using Next.js, take advantage of next/font, which not only takes care of loading the font but also optimizes the used fonts. You can find more information on loading custom web fonts in Next.js here.

To load the Inter font with Font Source when using with the B2B theme, you can follow the steps below:

First, add the font as a dependency to your project:

npm install @fontsource-variable/inter --save

Afterwards, import the package into your project.

// Supports weights 100-900 import '@fontsource-variable/inter';

Next Steps

Now that you've bootstrapped your app, you can dive into the documentation to explore the available components in detail. Additionally, you can read about our principles to understand the driving factors behind our decisions and the constraints associated with our approach.