From 963860d916d54ce3a0b191eb51a83cf3023ab88b Mon Sep 17 00:00:00 2001 From: Aram <37216945+alimpens@users.noreply.github.com> Date: Thu, 25 Apr 2024 10:45:22 +0200 Subject: [PATCH] feat: Allow installing only the React or CSS package (#1206) Co-authored-by: Vincent Smedinga Co-authored-by: Ruben Sibon --- documentation/publishing.md | 35 ++++++++++++++++++++++++++++++++++- packages/css/package.json | 5 ++++- packages/react/README.md | 15 ++++++++------- packages/react/package.json | 1 + pnpm-lock.yaml | 9 ++++++++- 5 files changed, 55 insertions(+), 10 deletions(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 825e42d982..ee55c47109 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -58,8 +58,41 @@ This will cause a major version bump in both packages on release and add its des Release Please uses labels to determine the status of a release. A release PR gets the label `autorelease: pending` or `autorelease: triggered`. When running the action again, the PR with those labels gets released, and the labels should be removed. -However, due to GitHub API failures, it's possible that the label was not removed correctly upon a previous release and Release Please thinks that the previous release is still pending. +However, due to GitHub API failures, it’s possible that the label was not removed correctly upon a previous release and Release Please thinks that the previous release is still pending. Release Please will not create a new release PR if it thinks there is a pending release. To fix this, check whether any closed PRs still have the `autorelease: pending` or `autorelease: triggered` labels, and remove them. [See the Release Please docs for more information](https://github.com/googleapis/release-please?tab=readme-ov-file#release-please-bot-does-not-create-a-release-pr-why). + +## Dependencies between packages + +We’ve established dependencies between our packages for smoother installation. +For instance, our React package relies on our CSS package. +When you install our React package, the corresponding version of our CSS package is automatically included. + +Here’s the dependency structure: + +```mermaid +graph LR + RI["React Icons"] --> React + Tokens --> CSS + Assets --> CSS + CSS --> React +``` + +Managing these dependencies requires extra attention when publishing. +We use [PNPM’s workspace feature](https://pnpm.io/workspaces#publishing-workspace-packages) to define dependencies between our packages. +When we publish upstream packages like CSS and React, the latest specific versions of downstream packages (Tokens, Assets, and React Icons) get listed as dependencies. + +This setup works well when we update both CSS and React in a release. +However, issues arise if a release only updates Tokens and Assets without changes to CSS or React. +The latest version of CSS then depends on an older version of Tokens. + +To resolve this, we can manually let CSS depend on the latest version of Tokens. +We replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "x.y.z"` and run `pnpm i` to update the lockfile. +We then release a new version of our CSS package, with the correct peer dependency. + +After that, consider restoring the dynamic dependency (`workspace:*`) and updating the lockfile (`pnpm i`) accordingly. + +The most extreme case requires us to release a new version of Tokens or Assets only, then update and release CSS, then update and release React. +Although infrequent, this scenario might occur in the future. diff --git a/packages/css/package.json b/packages/css/package.json index c42e811705..21644a1000 100644 --- a/packages/css/package.json +++ b/packages/css/package.json @@ -19,7 +19,10 @@ "clean": "rimraf dist/" }, "devDependencies": { - "@amsterdam/design-system-tokens": "workspace:*", "sass": "1.75.0" + }, + "peerDependencies": { + "@amsterdam/design-system-tokens": "workspace:*", + "@amsterdam/design-system-assets": "workspace:*" } } diff --git a/packages/react/README.md b/packages/react/README.md index f2199a4085..ad65d42512 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -5,9 +5,8 @@ The `@amsterdam/design-system-react` package contains React implementations of various components. You can use this package in React apps. -The design tokens and css used in these components are published in separate npm packages, so don’t forget to install and include `@amsterdam/design-system-tokens` and `@amsterdam/design-system-css` too. - - +The design tokens and CSS used in these components are published in separate npm packages, +which are automatically installed when you install the React package. ## Stability of the components @@ -19,11 +18,13 @@ Make sure you specify the exact version as dependency, so you can schedule to up ## Getting started -Install the packages you need, for instance: +Install the React package: + +`npm install @amsterdam/design-system-react` -`npm install @amsterdam/design-system-react @amsterdam/design-system-tokens @amsterdam/design-system-assets @amsterdam/design-system-css` +This will automatically add separate packages containing our design tokens, assets, icons, and stylesheets. -Import the packages you need. +Import the components and stylesheets you need, for example: ```javascript import { Paragraph } from "@amsterdam/design-system-react"; @@ -43,7 +44,7 @@ export default App; For applications, the large text and ample white space of the theme can be counterproductive. That’s why there is a compact mode. -To use the compact mode, import the compact css **after** theme css, like so: +To use the compact mode, import the compact CSS **after** the theme CSS, like so: ```javascript import "@amsterdam/design-system-tokens/dist/index.css"; diff --git a/packages/react/package.json b/packages/react/package.json index d77b8276c5..fbf27f0880 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -72,6 +72,7 @@ "tslib": "2.6.2" }, "peerDependencies": { + "@amsterdam/design-system-css": "workspace:*", "react": "16 - 18", "react-dom": "16 - 18" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1202df0192..f9ca52f983 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -97,16 +97,23 @@ importers: version: 7.2.0 packages/css: - devDependencies: + dependencies: + '@amsterdam/design-system-assets': + specifier: workspace:* + version: link:../../proprietary/assets '@amsterdam/design-system-tokens': specifier: workspace:* version: link:../../proprietary/tokens + devDependencies: sass: specifier: 1.75.0 version: 1.75.0 packages/react: dependencies: + '@amsterdam/design-system-css': + specifier: workspace:* + version: link:../css '@amsterdam/design-system-react-icons': specifier: workspace:* version: link:../../proprietary/react-icons