Getting Started with Component Library

How to use

• Make sure you use MUI v5. We don't support MUI v4 and the two cannot be running simultaneously unfortunately.
• Make sure to install all peerDependencies, we actually need them 🕵️‍♀️
• We are using the ResizeObserver. Make sure, to have a polyfill or mock for that in place. You can take a look at the setupTest.ts file and the jest.config.js (especially the setupFiles key) to see how we do it in the component library itself.
• If you have an existing theme in your project, you need to pass that as a prop to a ThemeProvider and then import the theme provider from the component library called XenoTheme.Provider and put it inside the existing StyledEngineProvider, like this:

// index.tsx
import './console/utils/translation/i18n';
import { XenoTheme } from '@expat/xeno';
import { CssBaseline } from '@mui/material';
import React, { StrictMode } from 'react';
import ReactDOM from 'react-dom';

import * as CustomTheme from './console/theme'; // This is your custom, project-only theme
import { App } from './console/App';

const store = createECStore();

ReactDOM.render(
  <XenoTheme.Provider>
    <StyledEngineProvider injectFirst>
      {/* This is your existing theme*/}
      <ThemeProvider theme={CustomTheme.mainTheme}>
        <App />
      </ThemeProvider>
    </StyledEngineProvider>
  </XenoTheme.Provider>,
  document.getElementById('root')
);

Nested themes

We are using nested themes. Since the default merging method for nested themes is a shallow merge, make sure to check if things still look the same. Read more about merging here.

We recommend to set up a provider of the merged theme locally. You can then use this provider everywhere and be sure, that the theme merging is the same everywhere. The CustomThemeProvider could look something like this:

// theme.tsx

const mergeWithOuterTheme = (outerTheme: Theme) => merge({}, outerTheme, { colorWarningText: Colors.SoftOrange });

export const CustomThemeProvider: React.FC = ({ children }) => (
  <StyledEngineProvider injectFirst>
    <ThemeProvider theme={mergeWithOuterTheme}>{children}</ThemeProvider>
  </StyledEngineProvider>
);

Local development

To develop on your local machine, just run yarn storybook, and start hacking 💪

Local linking

You can also try these changes directly at the place you want to use it. Just run yarn link in the root directory of the component library. This will give a command to run in the place, where you use it. If not, try yarn link @expat/xeno. This will use the local build of the component library. Then you can just run yarn build:watch to serve an always up-to-date version of teh component library. Note: test may not work in the place you use the linked version.

Code generation

YOu can use hygen for code generation. We have provided you code generators to give you a head start when adding new components. To get started, run npx install -g hygen. Now you can run hygen react-component new Test to generate a component with the name Test (feel free to use any other name 😉). This will also add an export to the index.ts. Also, stories and tests will be generated for you.

If you want to add a new generator, you can use the generator template as a starting point.

Available Scripts

In the project directory, you can run:

yarn start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

yarn build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

yarn eject

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Learn More

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

Deployment

Currently, the deployment is done with the gcloud cli. You need to be a member of the CoP UX. To deploy, first build storybook using yarn build-storybook and then trigger the deployment via yarn deploy-prod or yarn deploy-dev.