From 576aece31db1d38a49e4e4f8c7eaccd369bd9576 Mon Sep 17 00:00:00 2001 From: Alan Orth Date: Thu, 5 Sep 2024 13:11:10 +0300 Subject: [PATCH] README.md: use npm Use npm instead of yarn. Mostly a search and replace, minus some changes in terminology, for example "yarn add" vs "npm install". --- README.md | 84 +++++++++++++++++++++++++++---------------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index ebc24f8b91..f2d1cc046d 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ https://wiki.lyrasis.org/display/DSDOC7x/Installing+DSpace Quick start ----------- -**Ensure you're running [Node](https://nodejs.org) `v16.x` or `v18.x`, [npm](https://www.npmjs.com/) >= `v5.x` and [yarn](https://yarnpkg.com) == `v1.x`** +**Ensure you're running [Node](https://nodejs.org) `v16.x` or `v18.x`, [npm](https://www.npmjs.com/) >= `v5.x`** ```bash # clone the repo @@ -45,10 +45,10 @@ git clone https://github.com/DSpace/dspace-angular.git cd dspace-angular # install the local dependencies -yarn install +npm install # start the server -yarn start +npm start ``` Then go to [http://localhost:4000](http://localhost:4000) in your browser @@ -77,7 +77,7 @@ Table of Contents - [Recommended Editors/IDEs](#recommended-editorsides) - [Collaborating](#collaborating) - [File Structure](#file-structure) -- [Managing Dependencies (via yarn)](#managing-dependencies-via-yarn) +- [Managing Dependencies (via npm)](#managing-dependencies-via-npm) - [Frequently asked questions](#frequently-asked-questions) - [License](#license) @@ -89,15 +89,15 @@ You can find more information on the technologies used in this project (Angular. Requirements ------------ -- [Node.js](https://nodejs.org) and [yarn](https://yarnpkg.com) -- Ensure you're running node `v16.x` or `v18.x` and yarn == `v1.x` +- [Node.js](https://nodejs.org) +- Ensure you're running node `v16.x` or `v18.x` If you have [`nvm`](https://github.com/creationix/nvm#install-script) or [`nvm-windows`](https://github.com/coreybutler/nvm-windows) installed, which is highly recommended, you can run `nvm install --lts && nvm use` to install and start using the latest Node LTS. Installing ---------- -- `yarn install` to install the local dependencies +- `npm install` to install the local dependencies ### Configuring @@ -202,7 +202,7 @@ import { environment } from '../environment.ts'; Running the app --------------- -After you have installed all dependencies you can now run the app. Run `yarn run start:dev` to start a local server which will watch for changes, rebuild the code, and reload the server for you. You can visit it at `http://localhost:4000`. +After you have installed all dependencies you can now run the app. Run `npm run start:dev` to start a local server which will watch for changes, rebuild the code, and reload the server for you. You can visit it at `http://localhost:4000`. ### Running in production mode @@ -211,20 +211,20 @@ When building for production we're using Ahead of Time (AoT) compilation. With A To build the app for production and start the server (in one command) run: ```bash -yarn start +npm start ``` This will run the application in an instance of the Express server, which is included. If you only want to build for production, without starting, run: ```bash -yarn run build:prod +npm run build:prod ``` This will build the application and put the result in the `dist` folder. You can copy this folder to wherever you need it for your application server. If you will be using the built-in Express server, you'll also need a copy of the `node_modules` folder tucked inside your copy of `dist`. After building the app for production, it can be started by running: ```bash -yarn run serve:ssr +npm run serve:ssr ``` ### Running the application with Docker @@ -238,14 +238,14 @@ Cleaning -------- ```bash -# clean everything, including node_modules. You'll need to run yarn install again afterwards. -yarn run clean +# clean everything, including node_modules. You'll need to run npm install again afterwards. +npm run clean # clean files generated by the production build (.ngfactory files, css files, etc) -yarn run clean:prod +npm run clean:prod # cleans the distribution directory -yarn run clean:dist +npm run clean:dist ``` @@ -259,9 +259,9 @@ If you would like to contribute by testing a Pull Request (PR), here's how to do 1. Pull down the branch that the Pull Request was built from. Easy instructions for doing so can be found on the Pull Request itself. * Next to the "Merge" button, you'll see a link that says "command line instructions". * Click it, and follow "Step 1" of those instructions to checkout the pull down the PR branch. -2. `yarn run clean` (This resets your local dependencies to ensure you are up-to-date with this PR) -3. `yarn install` (Updates your local dependencies to those in the PR) -4. `yarn start` (Rebuilds the project, and deploys to localhost:4000, by default) +2. `npm run clean` (This resets your local dependencies to ensure you are up-to-date with this PR) +3. `npm install` (Updates your local dependencies to those in the PR) +4. `npm start` (Rebuilds the project, and deploys to localhost:4000, by default) 5. At this point, the code from the PR will be deployed to http://localhost:4000. Test it out, and ensure that it does what is described in the PR (or fixes the bug described in the ticket linked to the PR). Once you have tested the Pull Request, please add a comment and/or approval to the PR to let us know whether you found it to be successful (or not). Thanks! @@ -271,13 +271,13 @@ Once you have tested the Pull Request, please add a comment and/or approval to t Unit tests use the [Jasmine test framework](https://jasmine.github.io/), and are run via [Karma](https://karma-runner.github.io/). -You can find the Karma configuration file at the same level of this README file:`./karma.conf.js` If you are going to use a remote test environment you need to edit the `./karma.conf.js`. Follow the instructions you will find inside it. To executing tests whenever any file changes you can modify the 'autoWatch' option to 'true' and 'singleRun' option to 'false'. A coverage report is also available at: http://localhost:9876/ after you run: `yarn run coverage`. +You can find the Karma configuration file at the same level of this README file:`./karma.conf.js` If you are going to use a remote test environment you need to edit the `./karma.conf.js`. Follow the instructions you will find inside it. To executing tests whenever any file changes you can modify the 'autoWatch' option to 'true' and 'singleRun' option to 'false'. A coverage report is also available at: http://localhost:9876/ after you run: `npm run coverage`. The default browser is Google Chrome. Place your tests in the same location of the application source code files that they test, e.g. ending with `*.component.spec.ts` -and run: `yarn test` +and run: `npm test` If you run into odd test errors, see the Angular guide to debugging tests: https://angular.io/guide/test-debugging @@ -330,9 +330,9 @@ All E2E tests must be created under the `./cypress/integration/` folder, and mus * In the [Cypress Test Runner](https://docs.cypress.io/guides/core-concepts/test-runner), you'll Cypress automatically visit the page. This first test will succeed, as all you are doing is making sure the _page exists_. * From here, you can use the [Selector Playground](https://docs.cypress.io/guides/core-concepts/test-runner#Selector-Playground) in the Cypress Test Runner window to determine how to tell Cypress to interact with a specific HTML element on that page. * Most commands start by telling Cypress to [get()](https://docs.cypress.io/api/commands/get) a specific element, using a CSS or jQuery style selector - * It's generally best not to rely on attributes like `class` and `id` in tests, as those are likely to change later on. Instead, you can add a `data-test` attribute to makes it clear that it's required for a test. + * It's generally best not to rely on attributes like `class` and `id` in tests, as those are likely to change later on. Instead, you can add a `data-test` attribute to makes it clear that it's required for a test. * Cypress can then do actions like [click()](https://docs.cypress.io/api/commands/click) an element, or [type()](https://docs.cypress.io/api/commands/type) text in an input field, etc. - * When running with server-side rendering enabled, the client first receives HTML without the JS; only once the page is rendered client-side do some elements (e.g. a button that toggles a Bootstrap dropdown) become fully interactive. This can trip up Cypress in some cases as it may try to `click` or `type` in an element that's not fully loaded yet, causing tests to fail. + * When running with server-side rendering enabled, the client first receives HTML without the JS; only once the page is rendered client-side do some elements (e.g. a button that toggles a Bootstrap dropdown) become fully interactive. This can trip up Cypress in some cases as it may try to `click` or `type` in an element that's not fully loaded yet, causing tests to fail. * To work around this issue, define the attributes you use for Cypress selectors as `[attr.data-test]="'button' | ngBrowserOnly"`. This will only show the attribute in CSR HTML, forcing Cypress to wait until CSR is complete before interacting with the element. * Cypress can also validate that something occurs, using [should()](https://docs.cypress.io/api/commands/should) assertions. * Any time you save your test file, the Cypress Test Runner will reload & rerun it. This allows you can see your results quickly as you write the tests & correct any broken tests rapidly. @@ -357,14 +357,14 @@ Some UI specific configuration documentation is also found in the [`./docs`](doc To build the code documentation we use [TYPEDOC](http://typedoc.org). TYPEDOC is a documentation generator for TypeScript projects. It extracts information from properly formatted comments that can be written within the code files. Follow the instructions [here](http://typedoc.org/guides/doccomments/) to know how to make those comments. -Run:`yarn run docs` to produce the documentation that will be available in the 'doc' folder. +Run:`npm run docs` to produce the documentation that will be available in the 'doc' folder. Other commands -------------- There are many more commands in the `scripts` section of `package.json`. Most of these are executed by one of the commands mentioned above. -A command with a name that starts with `pre` or `post` will be executed automatically before or after the script with the matching name. e.g. if you type `yarn run start` the `prestart` script will run first, then the `start` script will trigger. +A command with a name that starts with `pre` or `post` will be executed automatically before or after the script with the matching name. e.g. if you type `npm run start` the `prestart` script will run first, then the `start` script will trigger. Recommended Editors/IDEs ------------------------ @@ -456,6 +456,7 @@ dspace-angular ├── LICENSES_THIRD_PARTY * ├── nodemon.json * Nodemon (https://nodemon.io/) configuration ├── package.json * This file describes the npm package for this project, its dependencies, scripts, etc. +├── package-lock.json * npm lockfile (https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json) ├── postcss.config.js * PostCSS (http://postcss.org/) configuration ├── README.md * This document ├── SECURITY.md * @@ -466,30 +467,29 @@ dspace-angular ├── tsconfig.spec.json * TypeScript config for tests ├── tsconfig.ts-node.json * TypeScript config for using ts-node directly ├── tslint.json * TSLint (https://palantir.github.io/tslint/) configuration -├── typedoc.json * TYPEDOC configuration -└── yarn.lock * Yarn lockfile (https://yarnpkg.com/en/docs/yarn-lock) +└── typedoc.json * TYPEDOC configuration ``` -Managing Dependencies (via yarn) +Managing Dependencies (via npm) ------------- -This project makes use of [`yarn`](https://yarnpkg.com/en/) to ensure that the exact same dependency versions are used every time you install it. +This project makes use of [`npm`](https://docs.npmjs.com/about-npm) to ensure that the exact same dependency versions are used every time you install it. -* `yarn` creates a [`yarn.lock`](https://yarnpkg.com/en/docs/yarn-lock) to track those versions. That file is updated automatically by whenever dependencies are added/updated/removed via yarn. -* **Adding new dependencies**: To install/add a new dependency (third party library), use [`yarn add`](https://yarnpkg.com/en/docs/cli/add). For example: `yarn add some-lib`. - * If you are adding a new build tool dependency (to `devDependencies`), use `yarn add some-lib --dev` -* **Upgrading existing dependencies**: To upgrade existing dependencies, you can use [`yarn upgrade`](https://yarnpkg.com/en/docs/cli/upgrade). For example: `yarn upgrade some-lib` or `yarn upgrade some-lib@version` -* **Removing dependencies**: If a dependency is no longer needed, or replaced, use [`yarn remove`](https://yarnpkg.com/en/docs/cli/remove) to remove it. +* `npm` creates a [`package-lock.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json) to track those versions. That file is updated automatically by whenever dependencies are added/updated/removed via npm. +* **Adding new dependencies**: To install/add a new dependency (third party library), use [`npm install`](https://docs.npmjs.com/cli/v10/commands/npm-install). For example: `npm install some-lib`. + * If you are adding a new build tool dependency (to `devDependencies`), use `npm install some-lib --save--dev` +* **Upgrading existing dependencies**: To upgrade existing dependencies, you can use [`npm update`](https://docs.npmjs.com/cli/v10/commands/npm-update). For example: `npm update some-lib` or `npm update some-lib@version` +* **Removing dependencies**: If a dependency is no longer needed, or replaced, use [`npm uninstall`](https://docs.npmjs.com/cli/v10/commands/npm-uninstall) to remove it. -As you can see above, using `yarn` commandline tools means that you should never need to modify the `package.json` manually. *We recommend always using `yarn` to keep dependencies updated / in sync.* +As you can see above, using `npm` commandline tools means that you should never need to modify the `package.json` manually. *We recommend always using `npm` to keep dependencies updated / in sync.* ### Adding Typings for libraries -If the library does not include typings, you can install them using yarn: +If the library does not include typings, you can install them using npm: ```bash -yarn add d3 -yarn add @types/d3 --dev +npm install d3 +npm install @types/d3 --save-dev ``` If the library doesn't have typings available at `@types/`, you can still use it by manually adding typings for it: @@ -528,12 +528,12 @@ Frequently asked questions - See [the official angular style guide](https://angular.io/styleguide) - Why is the size of my app larger in development? - The production build uses a whole host of techniques (ahead-of-time compilation, rollup to remove unreachable code, minification, etc.) to reduce the size, that aren't used during development in the intrest of build speed. -- node-pre-gyp ERR in yarn install (Windows) +- node-pre-gyp ERR in npm install (Windows) - install Python x86 version between 2.5 and 3.0 on windows. See [this issue](https://github.com/AngularClass/angular2-webpack-starter/issues/626) -- How do I handle merge conflicts in yarn.lock? - - first check out the yarn.lock file from the branch you're merging in to yours: e.g. `git checkout --theirs yarn.lock` - - now run `yarn install` again. Yarn will create a new lockfile that contains both sets of changes. - - then run `git add yarn.lock` to stage the lockfile for commit +- How do I handle merge conflicts in package-lock.json? + - first check out the package-lock.json file from the branch you're merging in to yours: e.g. `git checkout --theirs package-lock.json` + - now run `npm install` again. NPM will create a new lockfile that contains both sets of changes. + - then run `git add package-lock.json` to stage the lockfile for commit - and `git commit` to conclude the merge Getting Help