## 1. Project Overview & Quickstart (imsnif/CONTRIBUTING) # CONTRIBUTING Open-source repository imsnif/CONTRIBUTING ### Repository Details - **Repository:** [imsnif/CONTRIBUTING](https://github.com/imsnif/CONTRIBUTING) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (imsnif/website) ## File: README.md # Yarn Website This repo contains the source code for the Yarn website. In order to get started: ```sh $ git clone git@github.com:yarnpkg/website.git yarn-website $ cd yarn-website ``` You should ensure you have Yarn and [Bundler](http://bundler.io/) installed: ```sh $ gem install bundler ``` And then: ```sh $ make ``` Or: ```sh $ make install $ make serve ``` On Windows, `make` is not available, so you need to execute `bundle` and `jekyll` directly: ```sh bundle install bundle exec jekyll serve --incremental ``` --- **Special thanks to [Netlify](https://www.netlify.com/) for powering the website.** --- ## File: lang/en/docs/cli/add.md --- id: docs_cli_add guide: docs_cli layout: guide additional_reading_tags: ["dependencies"] --- {% include vars.html %} Installs a package and any packages that it depends on. ### Adding dependencies In general, a package is simply a folder with code and a `package.json` file that describes the contents. When you want to use another package, you first need to add it to your dependencies. This means running `yarn add [package-name]` to install it into your project. This will also update your `package.json` and your `yarn.lock` so that other developers working on the project will get the same dependencies as you when they run `yarn` or `yarn install`. Most packages will be installed from the [npm registry](https://www.npmjs.com/) and referred to by simply their package name. For example, `yarn add react` will install the [`react`](https://www.npmjs.com/package/react) package from the npm registry. You can specify versions using one of these: 1. `yarn add package-name` installs the "latest" version of the package. 2. `yarn add package-name@1.2.3` installs a specific version of a package from the registry. 3. `yarn add package-name@tag` installs a specific ["tag"]({{url_base}}/docs/cli/tag) (e.g. `beta`, `next`, or `latest`). You can also specify packages from different locations: 1. `yarn add package-name` installs the package from the [npm registry](https://www.npmjs.com/) unless you have specified another one in your `package.json`. 2. `yarn add file:/path/to/local/folder` installs a package that is on your local file system. This is useful to test out other packages of yours that haven't been published to the registry. 3. `yarn add file:/path/to/local/tarball.tgz` installs a package from a gzipped tarball which could be used to share a package before publishing it. 4. `yarn add ` installs a package from a remote git repository. 5. `yarn add #` installs a package from a remote git repository at specific git branch, git commit or git tag. 6. `yarn add https://my-project.org/package.tgz` installs a package from a remote gzipped tarball. ### Caveats If you have used a package manager like npm previously, you may be looking for how to add global dependencies. For the vast majority of packages it is considered a bad practice to have global dependencies because they are implicit. It is much better to add all of your dependencies locally so that they are explicit and anyone else using your project gets the same set of dependencies. If you are trying to use a CLI tool that has a `bin` you can access these in your `./node_modules/.bin` directory. You can also use the [`global`]({{url_base}}/docs/cli/global) command: ```sh yarn global add ``` ### Commands ##### `yarn add ` This will install one or more packages in your [`dependencies`]({{url_base}}/docs/dependency-types#toc-dependencies). ##### `yarn add [--dev/-D]` Using `--dev` or `-D` will install one or more packages in your [`devDependencies`]({{url_base}}/docs/dependency-types#toc-dev-dependencies). ##### `yarn add [--peer/-P]` Using `--peer` or `-P` will install one or more packages in your [`peerDependencies`]({{url_base}}/docs/dependency-types#toc-peer-dependencies). ##### `yarn add [--optional/-O]` Using `--optional` or `-O` will install one or more packages in your [`optionalDependencies`]({{url_base}}/docs/dependency-types#toc-optional-dependencies). ##### `yarn add [--exact/-E]` Using `--exact` or `-E` installs the packages as exact versions. The default is to use the most recent release with the same major version. For example, `yarn add foo@1.2.3` would accept version `1.9.1`, but `yarn add foo@1.2.3 --exact` would only accept version `1.2.3`. ##### `yarn add [--tilde/-T]` Using `--tilde` or `-T` installs the most recent release of the packages that have the same minor version. The default is to use the most recent release with the same major version. For example, `yarn add foo@1.2.3 --tilde` would accept `1.2.9` but not `1.3.0`. ##### `yarn add @npm:` This will install a package under a custom alias. Aliasing, allows multiple versions of the same dependency to be installed, each referenced via the _alias-package_ name given. For example, `yarn add my-foo@npm:foo` will install the package `foo` (at the latest version) in your [`dependencies`]({{url_base}}/docs/dependency-types#toc-dependencies) under the specified alias `my-foo`. Also, `yarn add my-foo@npm:foo@1.0.1` allows a specific version of `foo` to be installed. --- ## File: lang/en/docs/cli/autoclean.md --- id: docs_cli_autoclean guide: docs_cli layout: guide --- Cleans and removes unnecessary files from package dependencies. ##### `yarn autoclean [-I/--init] [-F/--force]` The `autoclean` command frees up space by removing unnecessary files and folders from dependencies. It reduces the number of files in your project's `node_modules` folder which is useful in an environment where packages are checked into version control directly. _Note: This command is considered for advanced use cases only. Unless you are experiencing issues with the amount of files that are installed as part of `node_modules` it is not recommended to use this command. It will permanently delete files in `node_modules` which could cause packages to stop working._ Autoclean functionality is **disabled** by default. To enable it, manually create a `.yarnclean` file, or run `yarn autoclean --init` to create the file with default entries. The `.yarnclean` file should be added to version control. When the `.yarnclean` file exists in a package, autoclean functionality will be enabled. The clean will be performed: * After an `install` * After an `add` * If `yarn autoclean --force` is run The clean is performed by reading each line of the `.yarnclean` file and using each as a glob pattern of files to delete. **Options:** `-I/--init` : Creates the `.yarnclean` file if it does not exist, and adds the default entries. This file should then be reviewed and edited to customize which files will be cleaned. If the file already exists, it will not be overwritten. `-F/--force` : If a `.yarnclean` file exists, run the clean process. If the file does not exist, do nothing. **Defaults:** When the `yarn autoclean --init` command is used to create a `.yarnclean` file, it will be pre-populated with a set of default items for deletion. This default list is a guess at what is likely not needed. It is impossible to predict all directories and files that are actually unnecessary for all existing and future NPM packages, so this default list may cause a package to no longer work. It is **highly recommended** that you manually review the default entries in `.yarnclean` and customize them to fit your needs. If you discover the autoclean process is deleting files that are needed for a package to work properly, then you should remove the corresponding entry from the `.yarnclean` file. **Example:** You decide all YAML and Markdown files in all your dependencies installed in `node_modules` can be safely deleted. You make a `.yarnclean` file containing: ``` *.yaml *.md ``` You then run `yarn install` or `yarn autoclean --force`. The clean process will delete all `*.yaml` and `*.md` files within `node_modules/` recursively (including nested transitive dependencies). --- ## File: lang/en/docs/cli/bin.md --- id: docs_cli_bin guide: docs_cli layout: guide --- {% include vars.html %} Displays the location of the yarn `bin` folder. ##### `yarn bin` `yarn bin` will print the folder where yarn will install executable files for your package. An example of an executable may be a script that you have defined for your package that can be executed via [`yarn run`]({{url_base}}/docs/cli/run). --- ## File: lang/en/docs/cli/cache.md --- id: docs_cli_cache guide: docs_cli layout: guide --- ##### `yarn cache list [--pattern]` Yarn stores every package in a global cache in your user directory on the file system. `yarn cache list` will print out every cached package. `yarn cache list --pattern ` will print out every cached package that matches the pattern provided. Examples: ```sh yarn cache list --pattern gulp yarn cache list --pattern "gulp|grunt" yarn cache list --pattern "gulp-(match|newer)" ``` ##### `yarn cache dir` Running `yarn cache dir` will print out the path where yarn's global cache is currently stored. ##### `yarn cache clean []` Running this command will clear the global cache. It will be populated again the next time `yarn` or `yarn install` is run. Additionally, you can specify one or more packages that you want to clean. ### Change the cache path for yarn Set `cache-folder` config value to configure the cache directory. ```sh yarn config set cache-folder ``` You can also specify the cache directory by flag `--cache-folder`: ```sh yarn --cache-folder ``` You can also specify the cache directory by environment variable `YARN_CACHE_FOLDER`: ```sh YARN_CACHE_FOLDER= yarn ``` --- ## File: lang/en/docs/cli/check.md --- id: docs_cli_check guide: docs_cli layout: guide --- ##### `yarn check` Verifies that versions of the package dependencies in the current project's `package.json` matches that of yarn's lock file. ##### `yarn check --integrity` Verifies that versions and hashed value of the package contents in the project's `package.json` matches that of yarn's lock file. This helps to verify that the package dependencies have not been altered. --- ## File: lang/en/docs/cli/config.md --- id: docs_cli_config guide: docs_cli layout: guide --- Manages the yarn configuration files. ##### `yarn config set [-g|--global]` Sets the config `key` to a certain `value`. Example: ```sh $ yarn config set init-license BSD-2-Clause yarn config vx.x.x success Set "init-license" to "BSD-2-Clause". ✨ Done in 0.05s. ``` ##### `yarn config get ` Echoes the value for a given `key` to `stdout`. Example: ```sh $ yarn config get init-license BSD-2-Clause ``` ##### `yarn config delete ` Deletes a given `key` from the config. Example: ```sh $ yarn config delete test-key yarn config vx.x.x success Deleted "test-key". ✨ Done in 0.06s. ``` ##### `yarn config list` Displays the current configuration. Example: ```sh $ yarn config list yarn config vx.x.x info yarn config { 'version-tag-prefix': 'v', 'version-git-tag': true, 'version-git-sign': false, 'version-git-message': 'v%s', 'init-version': '1.0.0', 'init-license': 'MIT', 'save-prefix': '^', 'ignore-scripts': false, 'ignore-optional': true, registry: 'https://registry.yarnpkg.com', 'user-agent': 'yarn/0.15.0 npm/? node/v6.2.1 darwin x64' } info npm config { registry: 'https://registry.npmjs.org/', '//localhost:4873/:_authToken': 'some-auth-token' } ✨ Done in 0.05s. ``` --- ## File: lang/en/docs/cli/create.md --- id: docs_cli_create guide: docs_cli layout: guide --- {% include vars.html %} Creates new projects from any `create-*` starter kits. ##### `yarn create []` This command is a shorthand that helps you do two things at once: * Install `create-` globally, or update the package to the latest version if it already exists * Run the executable located in the `bin` field of the starter kit’s `package.json`, forwarding any `` to it For example, `yarn create react-app my-app` is equivalent to: ```sh $ yarn global add create-react-app $ create-react-app my-app ``` For more information, check out the [relevant blog entry](https://yarnpkg.com/blog/2017/05/12/introducing-yarn/). --- ## File: lang/en/docs/cli/dedupe.md --- id: docs_cli_dedupe guide: docs_cli layout: guide --- {% include vars.html %} The dedupe command isn't necessary. `yarn install` will already dedupe. --- ## File: lang/en/docs/cli/generate-lock-entry.md --- id: docs_cli_generate_lock_entry guide: docs_cli layout: guide --- Generates a lock file entry. ##### `yarn generate-lock-entry` _Note: This command is considered for advanced use-cases and tooling only. It generates a lock file entry given the current `package.json` manifest file._ ```sh $ yarn generate-lock-entry # THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. # yarn lockfile v1 yarnpkg@0.14.0: version "0.14.0" dependencies: babel-plugin-transform-inline-imports-commonjs "^1.0.0" babel-runtime "^6.0.0" bytes "^2.4.0" [...] ```