HACKING.md

Contributing

Project info

Canonical react-components is developed with TypeScript, but built with babel and @babel/preset-typescript. Type declarations are generated post build with tsc.

Pull Requests

Pull request titles need to follow conventional commits specification, which will be used by semantic-release to determine if a release will be published on merging your pull request into the main branch. You can refer to this FAQ for details regarding rules for triggering a release.

Developing components with Storybook

You can run Storybook locally to develop new components. You may also need to validate that they work with other projects, in which case see the instructions below.

Run Storybook with dotrun:

dotrun

Or directly with Yarn:

yarn install
yarn docs

And remember to dotrun test and dotrun lint.

Using with another project that runs on yarn 3

Both projects will need to be running on the same machine/container.

In react-components run:

yarn clean
yarn install
yarn build
yarn build-watch

In your project run:

yarn clean
yarn install
yarn link path_to_react_components

At this point, you might get errors about mismatched versions of specific dependencies between react-components and your project. To fix these errors, change the versions of those dependencies in react-components to match the versions in your project. Once done, rerun the previously mentioned steps.

Finally, in your project, add the resolutions for react and react-dom to package.json. The added bit of code should be:

"resolutions": {
    "@canonical/react-components": "portal:path_to_react_components",
    "formik": "portal:path_to_react_components/node_modules/formik",
    "react": "portal:path_to_react_components/node_modules/react",
    "react-dom": "portal:path_to_react_components/node_modules/react-dom"
}

Note: Before pushing changes to @canonical/react-components, don't forget to change the mismatched versions of dependencies in react-components to the ones before the change.

Using with another project that runs on an older version of yarn

Both projects will need to be running on the same machine/container.

In react-components run:

dotrun link-package

You may want to watch and build files as you change them.

dotrun build-watch

This command links React to prevent multiple copies of React being loaded.

In the project you're working on:

dotrun clean
dotrun exec yarn link "@canonical/react-components"
dotrun exec yarn link "react"
dotrun exec yarn install
dotrun

If using a monorepo you'll need to run those commands at the top level (not inside a workspace).

You'll then need to start you project with yarn, not ./run.

Then when you're finished, in your project run:

dotrun exec yarn unlink react
dotrun exec yarn unlink "@canonical/react-components"

Then in react-components run:

dotrun unlink-package

Linking from Vite

When using yarn link from a project using Vite you may need to temporarily set the following option in your vite.config.ts:

resolve: {
  dedupe: ["react", "react-dom", "formik"],
  preserveSymlinks: true,
},

If you do not wish do use dotrun then replace dotrun in the command above. Note that you must use dotrun or yarn on one project you must use the same command on the other project so that they both link the same node modules.

Overriding SCSS variables

If your project overrides any Vanilla SCSS variables, you can pass them to react-components by using the additionalData option in your build configuration. This allows you to inject custom variable definitions before the component styles are processed.

With Vite

In your vite.config.ts:

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `
          $color-brand: #bada55;
          $breakpoint-large: 1234px;
        `,
      },
    },
  },
});

See Vite CSS preprocessorOptions for more information.

With Webpack

In your webpack configuration:

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              additionalData: `
                $color-brand: #bada55;
                $breakpoint-large: 1234px;
              `,
            },
          },
        ],
      },
    ],
  },
};

See Webpack documentation on sass-loader additionalData for more information.

Reading variables from SCSS file

This approach ensures that your custom variables take precedence over the default ones defined in the component library.

To avoid duplicating the variable definitions, consider creating a separate SCSS file (e.g., _settings.scss) and importing it in the additionalData option. Just make sure this file contains just variable definitions, without any other imports or styles.

// Read the file contents
const scssSettings = fs.readFileSync("templates/sass/_settings.scss", "utf-8").trim();

// ...

// and then in your Vite or Webpack configuration pass the file contents instead:
{
  // ...
  additionalData: scssSettings,
}

NOTE: As this is part of build configuration file, the changes to _settings.scss will require a rebuild of the project to take effect, and will not be hot-reloaded.

Developing integration tests with cypress

Running against a local storybook

Start storybook with:

PORT=<PORT> yarn docs

Start the interactive cypress environment with:

yarn cypress:open --env port=<PORT>

Running cypress tests in CI

PORT=<PORT> yarn test-cypress