From 095a67f06281de1fe7cd97ccd05269d8b16cdd70 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Thu, 1 Feb 2024 16:16:34 -0800 Subject: [PATCH 1/2] chore(angular, react, vue): update readmes for pnpm usage --- .github/CONTRIBUTING.md | 7 +++- packages/angular/README.md | 34 ++++++++++++++++++- packages/angular/test/README.md | 19 +++++------ packages/react-router/README.md | 50 +++++++++++++++++++++++++++- packages/react-router/test/README.md | 16 +++++---- packages/react/README.md | 47 ++++++++++++++++++++++++++ packages/react/test/README.md | 15 +++++---- packages/vue-router/README.md | 43 +++++++++++++++++++++--- packages/vue/README.md | 23 +++++++++---- packages/vue/test/README.md | 15 +++++---- 10 files changed, 225 insertions(+), 44 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 42434c6e1cd..ac4a1fb8b58 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -101,6 +101,7 @@ Before creating a pull request, please read our requirements that explains the m 5. Create a new branch from main for your change. 6. Navigate into the directory of the package you wish to modify (core, angular, etc.). 7. Run `pnpm install` to install dependencies for this package. + - If you prefer to install all dependencies (core, angular, etc.) at once, run `pnpm -r install` from the root of the repository. 8. Follow the steps for the specific package below. ### Core @@ -269,6 +270,9 @@ See [Ionic's E2E testing guide](../core/src/utils/test/playwright/docs/README.md 3. Make sure the build has finished before committing. If you made changes to the documentation, properties, methods, or anything else that requires an update to a generate file, this needs to be committed. 4. After the changes have been pushed, publish the branch and [create a pull request](#creating-a-pull-request). +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + ### Angular, React, and Vue #### Modifying Files @@ -281,7 +285,8 @@ See [Ionic's E2E testing guide](../core/src/utils/test/playwright/docs/README.md 2. Make your changes to the files. If the change is overly complex or out of the ordinary, add comments so we can understand the changes. 3. Run lint on the directory and make sure there are no errors. -4. Build the project. +4. Build the project with `pnpm build`. + - If you prefer to build all packages (core, angular, etc.) at once, run `pnpm -r build` from the root of the repository. 5. After the build is finished, commit the changes. Please follow the [commit message format](#commit-message-format) for every commit. 6. [Submit a Pull Request](#submit-pull-request) of your changes. diff --git a/packages/angular/README.md b/packages/angular/README.md index 0a1b2c488d7..d21baf441b1 100644 --- a/packages/angular/README.md +++ b/packages/angular/README.md @@ -21,7 +21,7 @@ Ionic Angular specific building blocks on top of [@ionic/core](https://www.npmjs ## Testing ng-add in ionic 1. Pull the latest from `main` -2. Build ionic/angular: `npm run build` +2. Build ionic/angular: `pnpm build` 3. Run `npm link` from `ionic/angular/dist` directory 4. Create a blank angular project @@ -72,3 +72,35 @@ Ionic developers can access this by importing from `@ionic/angular/standalone`. This is where the lazy loaded component implementations live. Ionic developers can access this by importing from `@ionic/angular`. + +## Building + +1. Install dependencies in `@ionic/core`: + +```shell +cd core && pnpm install +``` + +2. Build `@ionic/core`. This will generate Angular component bindings in the `packages/angular` directory: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +3. Install dependencies in `@ionic/angular`: + +```shell +cd packages/angular && pnpm install +``` + +4. Build `@ionic/angular`: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. diff --git a/packages/angular/test/README.md b/packages/angular/test/README.md index e5efdb1a0db..e626c6cd0a6 100644 --- a/packages/angular/test/README.md +++ b/packages/angular/test/README.md @@ -6,19 +6,16 @@ Ionic Framework supports multiple versions of Angular. As a result, we need to v The Angular test app supports syncing your locally built changes for validation. -1. Build the `core` and `packages/angular` directories using `npm run build`. -2. [Build the Angular test app](#test-app-build-structure). -3. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`). -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. +1. [Build](../README.md#building) the `core` and `packages/angular` projects using `pnpm build`. +2. Watch for changes made in `packages/angular` by using `pnpm build.watch`. +3. [Build the Angular test app](#test-app-build-structure). +4. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`). +5. Install dependencies using `pnpm install`. -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to [wipe or disable the application cache](#application-cache). +From here you can either build the application or start a local dev server. -## Application Cache - -Angular CLI creates a cache of several files on disk by default in the `.angular` directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the `.angular` cache is disabled by default in the test app projects. - -See https://angular.io/cli/cache for more information. +> [!NOTE] +> Making changes to the `test` app will require you to rebuild the app and restart the dev server. ### Disable Cache diff --git a/packages/react-router/README.md b/packages/react-router/README.md index 3f723796c6e..c4a5ad2eb21 100644 --- a/packages/react-router/README.md +++ b/packages/react-router/README.md @@ -1,2 +1,50 @@ -## @ionic/react-router (beta) +## @ionic/react-router +Routing integration for `@ionic/react` applications. + +## Building + +1. Install dependencies in `@ionic/core`: + +```shell +cd core && pnpm install +``` + +2. Build `@ionic/core`. This will generate React component bindings in the `packages/react` directory: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +3. Install dependencies in `@ionic/react`: + +```shell +cd packages/react && pnpm install +``` + +4. Build `@ionic/react`: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +5. Install dependencies in `@ionic/react-router`: + +```shell +cd packages/react-router && pnpm install +``` + +6. Build `@ionic/react-router`: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. diff --git a/packages/react-router/test/README.md b/packages/react-router/test/README.md index 22e912cedb1..b1213ac3a95 100644 --- a/packages/react-router/test/README.md +++ b/packages/react-router/test/README.md @@ -6,13 +6,17 @@ Ionic Framework supports multiple versions of React Router. As a result, we need The React test app supports syncing your locally built changes for validation. -1. Build the `@ionic/core`, `@ionic/react`, and `@ionic/react-router` projects using `npm run build`. -2. [Build the React test app](#test-app-build-structure). -3. Navigate to the built test app. -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. +1. [Build](../../README.md#building) the `core`, `packages/react`, and `packages/react-router` projects using `pnpm build`. +2. Watch for changes made in `packages/react-router` by using `pnpm build.watch`. +3. [Build the React test app](#test-app-build-structure). +4. Navigate to the built test app. +5. Install dependencies using `pnpm install`. + +From here you can either build the application or start a local dev server. + +> [!NOTE] +> Making changes to the `test` app will require you to rebuild the app and restart the dev server. -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. ## Test App Build Structure diff --git a/packages/react/README.md b/packages/react/README.md index 83119c93467..c7dab585410 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -4,6 +4,53 @@ These are React specific building blocks on top of [@ionic/core](https://www.npm To get started, install the Ionic CLI by running `npm i -g @ionic/cli`. Then, start a new Ionic React Project by running `ionic start myapp --type=react`. +## Building + +1. Install dependencies in `@ionic/core`: + +```shell +cd core && pnpm install +``` + +2. Build `@ionic/core`. This will generate React component bindings in the `packages/react` directory: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +3. Install dependencies in `@ionic/react`: + +```shell +cd packages/react && pnpm install +``` + +4. Build `@ionic/react`: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +5. Install dependencies in `@ionic/react-router`: + +```shell +cd packages/react-router && pnpm install +``` + +6. Build `@ionic/react-router`: + +```shell +pnpm build +``` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + ## Publishing a Native Application You can now make use of all of the ionic components in your React application. diff --git a/packages/react/test/README.md b/packages/react/test/README.md index e0b8efa3712..80dcf0eaa56 100644 --- a/packages/react/test/README.md +++ b/packages/react/test/README.md @@ -6,13 +6,16 @@ Ionic Framework supports multiple versions of React. As a result, we need to ver The React test app supports syncing your locally built changes for validation. -1. Build the `core`, `packages/react`, and `packages/react-router` directories using `npm run build`. -2. [Build the React test app](#test-app-build-structure). -3. Navigate to the built test app. -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. +1. [Build](../README.md#building) the `core`, `packages/react`, and `packages/react-router` projects using `pnpm build`. +2. Watch for changes made in `packages/react` by using `pnpm build.watch`. +3. [Build the React test app](#test-app-build-structure). +4. Navigate to the built test app. +5. Install dependencies using `pnpm install`. -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. +From here you can either build the application or start a local dev server. + +> [!NOTE] +> Making changes to the `test` app will require you to rebuild the app and restart the dev server. ## Test App Build Structure diff --git a/packages/vue-router/README.md b/packages/vue-router/README.md index 83cc23717bb..3e92a6007bc 100644 --- a/packages/vue-router/README.md +++ b/packages/vue-router/README.md @@ -4,22 +4,55 @@ Routing integration for `@ionic/vue` applications. ## Building -1. Install dependencies: +1. Install dependencies in `@ionic/core`: ```shell -npm install +cd core && pnpm install ``` -2. Run build script: +2. Build `@ionic/core`. This will generate Vue component bindings in the `packages/vue` directory: ```shell -npm run build +pnpm build ```` +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +3. Install dependencies in `@ionic/vue`: + +```shell +cd packages/vue && pnpm install +``` + +4. Build `@ionic/vue`: + +```shell +pnpm build +```` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + +5. Install dependencies in `@ionic/vue-router`: + +```shell +cd packages/vue-router && pnpm install +``` + +6. Build `@ionic/vue-router`: + +```shell +pnpm build +```` + +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + ## Tests * Tests are found in the `__tests__` directory and use Jest. -* Tests can be run using `npm run test.spec` +* Tests can be run using `pnpm test.spec` * Bug fix and feature PRs should have new tests verifying the PR functionality. ## Contributing diff --git a/packages/vue/README.md b/packages/vue/README.md index 2bd35bf6b0b..67f2daa90b3 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -7,43 +7,52 @@ Ionic Framework integration for Vue 3 apps. 1. Install dependencies in `@ionic/core`: ```shell -cd core && npm install +cd core && pnpm install ``` 2. Build `@ionic/core`. This will generate Vue component bindings in the `packages/vue` directory: ```shell -npm run build +pnpm build ```` +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + 3. Install dependencies in `@ionic/vue`: ```shell -cd packages/vue && npm install +cd packages/vue && pnpm install ``` 4. Build `@ionic/vue`: ```shell -npm run build +pnpm build ```` +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + 5. Install dependencies in `@ionic/vue-router`: ```shell -cd packages/vue-router && npm install +cd packages/vue-router && pnpm install ``` 6. Build `@ionic/vue-router`: ```shell -npm run build +pnpm build ```` +> [!WARNING] +> If you are receiving errors about missing packages, you may need to run `pnpm install --force` to force the installation of the missing packages. + ## Tests * E2E Tests are found in the `packages/vue/test/base/tests` directory and use Cypress. -* When making changes to `@ionic/vue` or `@ionic/vue-router` you can run `npm run sync` in the [test-app directory](test/README.md#syncing-local-changes) to ensure that the test application is using your built changes. Be sure to build in the `vue` and `vue-router` directories first. +* When making changes to `@ionic/vue` or `@ionic/vue-router` you can run `pnpm build.watch` in their root directories to ensure that the test application is using your latest changes. Be sure to build in the `vue` and `vue-router` directories first. * Tests can be run in headless mode by running `npm run cypress`. * If you want to open the Cypress test runner, you can run `node_modules/.bin/cypress open`. * Bug fix and feature PRs should have new tests verifying the PR functionality. diff --git a/packages/vue/test/README.md b/packages/vue/test/README.md index b124b491e77..ac744b09cbd 100644 --- a/packages/vue/test/README.md +++ b/packages/vue/test/README.md @@ -6,13 +6,16 @@ Ionic Framework supports multiple versions of Vue. As a result, we need to verif The Vue test app supports syncing your locally built changes for validation. -1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `npm run build`. -2. [Build the Vue test app](#test-app-build-structure). -3. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`). -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. +1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `pnpm build`. +2. Watch for changes made in `packages/vue` by using `pnpm build.watch`. +3. [Build the Vue test app](#test-app-build-structure). +4. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`). +5. Install dependencies using `pnpm install`. -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. +From here you can either build the application or start a local dev server. + +> [!NOTE] +> Making changes to the `test` app will require you to rebuild the app and restart the dev server. ## Test App Build Structure From 3c727e46219b6cfd1c017d4c9a48f9f4e0ba4ea9 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Thu, 1 Feb 2024 16:40:17 -0800 Subject: [PATCH 2/2] chore(angular): use latest version for test build example --- packages/angular/test/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/angular/test/README.md b/packages/angular/test/README.md index e626c6cd0a6..978777765ab 100644 --- a/packages/angular/test/README.md +++ b/packages/angular/test/README.md @@ -9,7 +9,7 @@ The Angular test app supports syncing your locally built changes for validation. 1. [Build](../README.md#building) the `core` and `packages/angular` projects using `pnpm build`. 2. Watch for changes made in `packages/angular` by using `pnpm build.watch`. 3. [Build the Angular test app](#test-app-build-structure). -4. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`). +4. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng17`). 5. Install dependencies using `pnpm install`. From here you can either build the application or start a local dev server. @@ -53,8 +53,8 @@ Unlike other test applications, these test apps are broken up into multiple dire Usage: ```shell -# Build a test app using apps/ng14 as a reference -./build.sh ng14 +# Build a test app using apps/ng17 as a reference +./build.sh ng17 ``` ## How to modify test apps