4.1-yarn-link.md

Test local changes on your project, with yarn link

1. 🚨 Prerequisites
2. Yarn Link Steps

1. 🚨 Prerequisites

Accommodating for Shared Components peer dependencies

yarn link has known issues when linking packages whose peer dependencies require a single instance to be run on the host project (ex : styled-components)

Dependencies of linked packages are by default resolved from inside the Shared Components monorepo, and doing so spawns another instance of them in addition to the ones your project may already be using.

The solution

You need to tell your host project to always resolve these peer dependencies from inside your node_modules instead.

Add a resolve.alias webpack config, such as this one (which should cover most peer dependencies of Shared Components that are in this case):

module.exports = {
  //...
  resolve: {
    alias: {
      // circumvent yarn link not being able to properly resolve peer dependencies of linked packages - https://github.com/bnpp/shared-components/blob/master/documentation/how-to-contribute/4.1-yarn-link.md

     'styled-components': path.resolve(__dirname, 'node_modules/styled-components/'),
     'react': path.resolve(__dirname, 'node_modules/react/'),
     'react-dom': path.resolve(__dirname, 'node_modules/react-dom/'),
    }
  }
};

You can find more details about the WHY of this solution here.

---

symlinks option in webpack config

If resolve.symlinks is set to false in your webpack config, yarn link will probably fail.
You can simply remove this option from your config since it defaults to true.

---

If your project uses Babel version <=6

Shared Components uses a newer version of Babel (v7), which would make yarn link fail on your host project. To circumvent this issue, you need to exclude the Shared Components linked file to be transpiled with Babel, by adding in your Babel configuration:

module.exports = options => ({
  //...
  module: {
    rules: [
      {
        // "/shared-components/packages/" is to avoid transpiling Shared Components packages with Babel when they are "yarn link"'ed to this project, to avoid issues caused
        // by this project and Shared Components using different versions of Babel.
        exclude: [/\/shared-components\/packages\//]
      }]
   }
});

2. Yarn Link Steps

1. 🚨 Read the prerequisite above first
2. 🤔 Determine in what case you are.
   • Normal case: You want to locally test the changes of a single package, let's say Atoms, when Atoms is imported directly in your project.
   • Special case: You want to locally test the changes of one or more packages, when they are imported through other packages on your project.
     Example: watching the changes of Atoms and Molecules, when Atoms is imported in Molecules, imported in a Product in your project. (Atoms → Molecules → Product → Your host project)
3. 🔗 Create the link on Shared Components side
   • Normal case: cd packages/atoms && yarn link
   • Special case: link only the top-level package (the one imported in your project): cd packages/product && yarn link
4. 🔎 Run the package in build watch mode
   • Normal case: yarn build:watch
   • Special case: build:watch all the packages in the chain

   cd packages/atoms && yarn build:watch
   cd packages/molecules && yarn build:watch
   cd packages/product && yarn build:watch

5. 🔗 Link the package on your project side
   • Normal case: cd <my-host-project> && yarn link @shared-components/atoms
   • Special case: link only the top-level package: cd <my-host-project> && yarn link @shared-components/product
6. 🚀 Start your host project