diff --git a/404.html b/404.html index 5c7cbfa4..cb2870af 100644 --- a/404.html +++ b/404.html @@ -6,13 +6,13 @@ Page Not Found | Rush - +
Rush StackShopBlogEvents
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/d98d853d.3513af17.js b/assets/js/d98d853d.3513af17.js new file mode 100644 index 00000000..d6996759 --- /dev/null +++ b/assets/js/d98d853d.3513af17.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkrushjs_io=self.webpackChunkrushjs_io||[]).push([[6339],{158:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>m});var a=n(6393);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),c=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=c(e.components);return a.createElement(l.Provider,{value:t},e.children)},p="mdxType",h={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),p=c(n),d=r,m=p["".concat(l,".").concat(d)]||p[d]||h[d]||o;return n?a.createElement(m,i(i({ref:t},u),{},{components:n})):a.createElement(m,i({ref:t},u))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,i=new Array(o);i[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[p]="string"==typeof e?e:r,i[1]=s;for(var c=2;c{n.r(t),n.d(t,{assets:()=>u,contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>c,toc:()=>p});var a=n(9122),r=n(2501),o=(n(6393),n(158)),i=["components"],s={title:"Enabling the build cache"},l=void 0,c={unversionedId:"pages/maintainer/build_cache",id:"pages/maintainer/build_cache",title:"Enabling the build cache",description:"Rush has always supported an incremental build analyzer that",source:"@site/docs/pages/maintainer/build_cache.md",sourceDirName:"pages/maintainer",slug:"/pages/maintainer/build_cache",permalink:"/pages/maintainer/build_cache",draft:!1,editUrl:"https://github.com/microsoft/rushstack-websites/tree/main/websites/rushjs.io/docs/pages/maintainer/build_cache.md",tags:[],version:"current",frontMatter:{title:"Enabling the build cache"},sidebar:"docsSidebar",previous:{title:"Deploying projects",permalink:"/pages/maintainer/deploying"},next:{title:"Enabling phased builds",permalink:"/pages/maintainer/phased_builds"}},u={},p=[{value:"Enabling the local disk cache",id:"enabling-the-local-disk-cache",level:2},{value:"Configuring project output folders",id:"configuring-project-output-folders",level:2},{value:"Configuring project inputs",id:"configuring-project-inputs",level:2},{value:"Testing the build cache",id:"testing-the-build-cache",level:2},{value:"Enabling cloud storage",id:"enabling-cloud-storage",level:2},{value:"User authentication",id:"user-authentication",level:2},{value:"CI setup",id:"ci-setup",level:2},{value:"Credentials",id:"credentials",level:3},{value:"Azure Storage",id:"azure-storage",level:4},{value:"AWS",id:"aws",level:4}],h={toc:p},d="wrapper";function m(e){var t=e.components,n=(0,r.Z)(e,i);return(0,o.kt)(d,(0,a.Z)({},h,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Rush has always supported an ",(0,o.kt)("a",{parentName:"p",href:"/pages/advanced/incremental_builds"},"incremental build")," analyzer that\nenables ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," to skip projects whose input files have not changed since the last build.\nIt can also be used with custom commands by enabling the ",(0,o.kt)("inlineCode",{parentName:"p"},"incremental")," flag in ",(0,o.kt)("strong",{parentName:"p"},"custom-commands.json"),".\nWe call this the ",(0,o.kt)("strong",{parentName:"p"},'"output preservation"')," strategy for incremental builds. Because the build output\nis not saved anywhere, a full rebuild is generally still required when checking out a different branch."),(0,o.kt)("p",null,"Rush's ",(0,o.kt)("strong",{parentName:"p"},"build cache")," improves on this by creating a tar archive of each project's build outputs.\nThe archive is cached so that later, if ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," can find a match in the cache, it can extract the archive\ninstead of building that project. This can provide dramatic speedups, for example reducing a 30 minute build time\nto 30 seconds. We call this the ",(0,o.kt)("strong",{parentName:"p"},'"cache restoration"')," strategy for incremental builds."),(0,o.kt)("p",null,"The build cache archives are stored in two places:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"In a cache folder on your local disk.")," This way you can switch between different branches without\nlosing your incremental build state. You can even configure a centralized folder to be shared between\nmultiple enlistments on your machine. The default location is ",(0,o.kt)("strong",{parentName:"p"},"common/temp/build-cache"),".")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"In a cloud-hosted storage container. (Optional)")," In a typical setup, the CI system would be configured to write\nto cloud storage, and individual users are granted read-only access. For example, each time a PR is merged into\nthe ",(0,o.kt)("inlineCode",{parentName:"p"},"main")," branch, the CI system builds that baseline and uploads it to cloud storage. Even for a user who\nis doing ",(0,o.kt)("inlineCode",{parentName:"p"},"git clone")," for the first time, their ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," will be very fast."))),(0,o.kt)("h2",{id:"enabling-the-local-disk-cache"},"Enabling the local disk cache"),(0,o.kt)("p",null,"The build cache feature is enabled using the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/build-cache_json"},"build-cache.json"),"\nconfig file. You can copy the template from the website or use ",(0,o.kt)("inlineCode",{parentName:"p"},"rush init")," to create this file."),(0,o.kt)("p",null,"To enable the basic local disk cache, add these two settings:"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"common/config/rush/build-cache.json")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js"},'{\n . . .\n /**\n * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.\n *\n * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.\n */\n "buildCacheEnabled": true,\n\n /**\n * (Required) Choose where project build outputs will be cached.\n *\n * Possible values: "local-only", "azure-blob-storage", "amazon-s3"\n */\n "cacheProvider": "local-only",\n\n . . .\n}\n')),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},(0,o.kt)("strong",{parentName:"p"},"Upgrade note:")," Early releases of this feature were enabled using the ",(0,o.kt)("inlineCode",{parentName:"p"},'"buildCache": true')," setting\nin ",(0,o.kt)("strong",{parentName:"p"},"experiments.json"),". This has been superseded by ",(0,o.kt)("inlineCode",{parentName:"p"},'"buildCacheEnabled"')," in ",(0,o.kt)("strong",{parentName:"p"},"build-cache.json"),".")),(0,o.kt)("h2",{id:"configuring-project-output-folders"},"Configuring project output folders"),(0,o.kt)("p",null,"With only this change, if you run ",(0,o.kt)("inlineCode",{parentName:"p"},"rush rebuild --verbose"),", you will see this warning:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"Project does not have a rush-project.json configuration file, or one provided by a rig,\nso it does not support caching.\n")),(0,o.kt)("p",null,"The build cache needs to know which folders should be stored in the tar archive. Those details vary between\ntoolchains, and are thus configured separately for each project using the\n",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/rush-project_json"},"rush-project.json")," config file."),(0,o.kt)("p",null,"For example:"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"<","your-project",">","/config/rush-project.json")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js"},'{\n . . .\n\n /**\n * Specify the folders where your toolchain writes its output files. If enabled, the Rush build cache will\n * restore these folders from the cache.\n *\n * The strings are folder names under the project root folder. These folders should not be tracked by Git.\n * They must not contain symlinks.\n */\n "projectOutputFolderNames": ["lib", "dist"]\n . . .\n}\n')),(0,o.kt)("h2",{id:"configuring-project-inputs"},"Configuring project inputs"),(0,o.kt)("p",null,"By default, the following inputs are incorporated into Rush's cache key. In other words, if any of these things\nchanges, then the project must be rebuilt:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},"the hash of the source files that are under the project's folder, ignoring any files excluded by ",(0,o.kt)("inlineCode",{parentName:"p"},".gitignore"))),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},"the hashes of source files under other workspace projects that are dependencies of the project ",(0,o.kt)("br",null),"\n(applies to ",(0,o.kt)("strong",{parentName:"p"},"cache restoration")," strategy but not ",(0,o.kt)("strong",{parentName:"p"},"output preservation")," strategy)")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},"the versions of all external NPM packages that your project depends on, including indirect dependencies")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},"the Rush command-line parameters used to perform the operation"))),(0,o.kt)("p",null,"These details can be customized using the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/rush-project_json"},"rush-project.json")," config file.\nFor example, you can include/exclude certain glob patterns, or specify environment variables that affect the\nbuild output. It's recommended to use a ",(0,o.kt)("a",{parentName:"p",href:"https://heft.rushstack.io/pages/intro/rig_packages/"},"rig package")," to avoid\nhaving to copy ",(0,o.kt)("strong",{parentName:"p"},"rush-project.json")," into every project folder."),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},(0,o.kt)("strong",{parentName:"p"},"Important:")," Configure these settings carefully. If a project inputs/outputs are not accurately specified,\nthen the build cache may produce incorrect or inconsistent results. For example, the restored output may\nbe missing some files. Or it may be different from what would be produced by a full rebuild. Such problems\ncan be difficult to reproduce and troubleshoot."),(0,o.kt)("p",{parentName:"blockquote"},"If you suspect that the Rush build cache may be misconfigured, try the\n",(0,o.kt)("a",{parentName:"p",href:"https://www.npmjs.com/package/rush-audit-cache-plugin"},"rush-audit-cache-plugin"),".\nIt monitors file writes during the build to identify inputs that are not part of your cache key.")),(0,o.kt)("h2",{id:"testing-the-build-cache"},"Testing the build cache"),(0,o.kt)("p",null,"Now you should see projects being cached as shown in this sample log output:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"rush build --verbose\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'. . .\n\n==[ example-project ]==============================================[ 1 of 5 ]==\n\nThis project was not found in the build cache.\n\nInvoking: heft test --clean\n\n. . .\n\nCaching build output folders: lib\n\nSuccessfully set cache entry.\n\n"example-project" completed successfully in 11.27 seconds.\n')),(0,o.kt)("p",null,"When we run the same command a second time, Rush extracts the archive instead of invoking the build task:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"rush build --verbose\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},". . .\n\n==[ example-project ]==============================================[ 1 of 5 ]==\n\nBuild cache hit.\n\nClearing cached folders: lib, dist\n\nSuccessfully restored output from the build cache.\n\nexample-project was restored from the build cache.\n")),(0,o.kt)("p",null,"Note that ",(0,o.kt)("inlineCode",{parentName:"p"},"rush rebuild")," will not read from cache, only ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," does. To disable writing from cache during ",(0,o.kt)("inlineCode",{parentName:"p"},"rush rebuild"),",\nset the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/environment_vars"},(0,o.kt)("inlineCode",{parentName:"a"},"RUSH_BUILD_CACHE_WRITE_ALLOWED"))," environment variable to ",(0,o.kt)("inlineCode",{parentName:"p"},"0"),"."),(0,o.kt)("p",null,"By default, the cached tar archives are stored under your ",(0,o.kt)("strong",{parentName:"p"},"common/temp/build-cache")," folder\n(and thus will be cleaned by ",(0,o.kt)("inlineCode",{parentName:"p"},"rush purge"),"). It is safe to delete these files."),(0,o.kt)("h2",{id:"enabling-cloud-storage"},"Enabling cloud storage"),(0,o.kt)("p",null,"Currently the ",(0,o.kt)("inlineCode",{parentName:"p"},"cacheProvider")," setting provides three choices:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},'"local-only"'),": no cloud storage; archives are only kept on a local disk folder"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},'"azure-blob-storage"'),": Microsoft Azure ",(0,o.kt)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us/azure/storage/blobs/"},"blob storage container")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},'"amazon-s3"'),": Amazon ",(0,o.kt)("a",{parentName:"li",href:"https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html"},"S3 bucket"))),(0,o.kt)("p",null,"(The above providers are ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/microsoft/rushstack/tree/main/rush-plugins"},"modeled as Rush plugins"),".\nCustom build cache storage providers can be implemented in the same way.)"),(0,o.kt)("p",null,"As one example, here's how to configure an Azure blob container:"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"common/config/rush/build-cache.json")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js"},'{\n . . .\n /**\n * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.\n *\n * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.\n */\n "buildCacheEnabled": true,\n\n /**\n * (Required) Choose where project build outputs will be cached.\n *\n * Possible values: "local-only", "azure-blob-storage", "amazon-s3"\n */\n "cacheProvider": "azure-blob-storage",\n\n /**\n * Use this configuration with "cacheProvider"="azure-blob-storage"\n */\n "azureBlobStorageConfiguration": {\n /**\n * (Required) The name of the the Azure storage account to use for build cache.\n */\n "storageAccountName": "example",\n\n /**\n * The name of the container in the Azure storage account to use for build cache.\n */\n "storageContainerName": "my-container"\n\n /**\n * If set to true, allow writing to the cache. Defaults to false.\n */\n "isCacheWriteAllowed": false\n\n . . .\n')),(0,o.kt)("p",null,"Note that we have set ",(0,o.kt)("inlineCode",{parentName:"p"},'"isCacheWriteAllowed": false')," to prevent regular users from writing to the container.\n(Later, we will use an environment variable to override this for our CI job.)"),(0,o.kt)("h2",{id:"user-authentication"},"User authentication"),(0,o.kt)("p",null,"If security is not a priority for your repo, you can simplify user setup by configuring your storage container\nto allow unauthenticated anonymous access. The container is accessed via an HTTPS URL containing randomized\nhashes which are difficult to guess without access to your Git repo. This provides rudimentary\n",(0,o.kt)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Security_through_obscurity"},"security through obscurity"),"."),(0,o.kt)("p",null,"A more security-conscious organization however will prefer to require authentication even for read-only access.\nRush provides a ",(0,o.kt)("a",{parentName:"p",href:"/pages/commands/rush_update-cloud-credentials"},"rush update-cloud-credentials"),"\ncommand to make this easy for users to set up:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"rush update-cloud-credentials --interactive\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'Rush Multi-Project Build Tool 5.45.6 (unmanaged) - https://rushjs.io\nNode.js version is 12.20.1 (LTS)\n\n\nStarting "rush update-cloud-credentials"\n\n \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n \u2551 To sign in, use a web browser to open the page \u2551\n \u2551 https://microsoft.com/devicelogin and enter the code XAYBQEGRK \u2551\n \u2551 to authenticate. \u2551\n \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n')),(0,o.kt)("p",null,"The credentials are stored in the user's home directory under ",(0,o.kt)("inlineCode",{parentName:"p"},"~/.rush-user/credentials.json"),"."),(0,o.kt)("h2",{id:"ci-setup"},"CI setup"),(0,o.kt)("p",null,"In a typical configuration, users have read-only access and the cache is populated by an automation account;\nfor example, a CI job that builds your ",(0,o.kt)("inlineCode",{parentName:"p"},"main")," branch after each PR is merged. In our example above, the\n",(0,o.kt)("inlineCode",{parentName:"p"},'"isCacheWriteAllowed": false')," setting is what prevents users from writing to the cache. The CI job can\noverride this by setting the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/environment_vars"},"RUSH_BUILD_CACHE_WRITE_ALLOWED"),"\nenvironment variable, and by providing credentials for the CI environment in the\n",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/environment_vars"},"RUSH_BUILD_CACHE_CREDENTIAL")," environment variable."),(0,o.kt)("h3",{id:"credentials"},"Credentials"),(0,o.kt)("h4",{id:"azure-storage"},"Azure Storage"),(0,o.kt)("p",null,"For Azure Blob Storage, ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," must be a SAS token serialized as query parameters.\nSee ",(0,o.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview"},"this article")," for details\nabout SAS tokens. You can obtain a SAS token via the ",(0,o.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?tabs=azure-portal"},"Settings > Access keys"),"\npage for your storage account."),(0,o.kt)("h4",{id:"aws"},"AWS"),(0,o.kt)("p",null,"For Amazon S3, ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," will be your AWS Access Key ID and AWS Secret Access Key separated by a colon,\nsuch as: ",(0,o.kt)("inlineCode",{parentName:"p"},":"),". You can also pass temporary session tokens required when assuming an IAM role: ",(0,o.kt)("inlineCode",{parentName:"p"},"::"),"."),(0,o.kt)("p",null,"If ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," is not set, the build cache will attempt to read the environment vars ",(0,o.kt)("inlineCode",{parentName:"p"},"AWS_ACCESS_KEY_ID"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"AWS_SECRET_ACCESS_KEY"),", and ",(0,o.kt)("inlineCode",{parentName:"p"},"AWS_SESSION_TOKEN")," that\nare commonly set via the AWS CLI or other CI tooling. However, ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," will always take precedence if it exists."),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},"The build cache feature is still under development. Feedback is welcome!"),(0,o.kt)("p",{parentName:"blockquote"},"Some relevant GitHub issues to follow:"),(0,o.kt)("ul",{parentName:"blockquote"},(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2393"},"Build cache feature #2393")," - the original feature spec"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2642"},"Build Cache: split apart RUSH_BUILD_CACHE_WRITE_CREDENTIAL #2642")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2618"},"Allow project config to specify non-build-related files #2618")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2622"},'"tar" exited with code 1 while attempting to create the cache entry #2622')))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/d98d853d.a6d59eab.js b/assets/js/d98d853d.a6d59eab.js deleted file mode 100644 index ba604db8..00000000 --- a/assets/js/d98d853d.a6d59eab.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkrushjs_io=self.webpackChunkrushjs_io||[]).push([[6339],{158:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>m});var a=n(6393);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),c=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=c(e.components);return a.createElement(l.Provider,{value:t},e.children)},p="mdxType",h={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),p=c(n),d=r,m=p["".concat(l,".").concat(d)]||p[d]||h[d]||o;return n?a.createElement(m,i(i({ref:t},u),{},{components:n})):a.createElement(m,i({ref:t},u))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,i=new Array(o);i[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[p]="string"==typeof e?e:r,i[1]=s;for(var c=2;c{n.r(t),n.d(t,{assets:()=>u,contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>c,toc:()=>p});var a=n(9122),r=n(2501),o=(n(6393),n(158)),i=["components"],s={title:"Enabling the build cache"},l=void 0,c={unversionedId:"pages/maintainer/build_cache",id:"pages/maintainer/build_cache",title:"Enabling the build cache",description:"Rush has always supported an incremental build analyzer that",source:"@site/docs/pages/maintainer/build_cache.md",sourceDirName:"pages/maintainer",slug:"/pages/maintainer/build_cache",permalink:"/pages/maintainer/build_cache",draft:!1,editUrl:"https://github.com/microsoft/rushstack-websites/tree/main/websites/rushjs.io/docs/pages/maintainer/build_cache.md",tags:[],version:"current",frontMatter:{title:"Enabling the build cache"},sidebar:"docsSidebar",previous:{title:"Deploying projects",permalink:"/pages/maintainer/deploying"},next:{title:"Enabling phased builds",permalink:"/pages/maintainer/phased_builds"}},u={},p=[{value:"Enabling the local disk cache",id:"enabling-the-local-disk-cache",level:2},{value:"Configuring project output folders",id:"configuring-project-output-folders",level:2},{value:"Testing the build cache",id:"testing-the-build-cache",level:2},{value:"Enabling cloud storage",id:"enabling-cloud-storage",level:2},{value:"User authentication",id:"user-authentication",level:2},{value:"CI setup",id:"ci-setup",level:2},{value:"Credentials",id:"credentials",level:3},{value:"Azure Storage",id:"azure-storage",level:4},{value:"AWS",id:"aws",level:4}],h={toc:p},d="wrapper";function m(e){var t=e.components,n=(0,r.Z)(e,i);return(0,o.kt)(d,(0,a.Z)({},h,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Rush has always supported an ",(0,o.kt)("a",{parentName:"p",href:"/pages/advanced/incremental_builds"},"incremental build")," analyzer that\nenables ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," to skip projects whose input files have not changed since the last build.\nWe call this the ",(0,o.kt)("strong",{parentName:"p"},'"output preservation"')," strategy for incremental builds. It can also be used with custom commands\nby enabling the ",(0,o.kt)("inlineCode",{parentName:"p"},"incremental")," flag in ",(0,o.kt)("strong",{parentName:"p"},"custom-commands.json"),"."),(0,o.kt)("p",null,"However, the build output is not saved anywhere, so generally a full rebuild is still required when checking out\na different branch. Rush's ",(0,o.kt)("strong",{parentName:"p"},"build cache")," improves on this by creating a tar archive of each project's build outputs.\nThe archive is cached so that later, if ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," can find a match in the cache, it can extract the archive\ninstead of building that project. This can provide dramatic speedups, for example reducing a 30 minute build time\nto 30 seconds. The cache key is a hash of the source files and NPM dependencies, following the\n",(0,o.kt)("a",{parentName:"p",href:"/pages/advanced/incremental_builds"},"same basic rules")," as the incremental analyzer. We call this the\n",(0,o.kt)("strong",{parentName:"p"},'"cache restoration"')," strategy for incremental builds."),(0,o.kt)("p",null,"The build cache archives are stored in two places:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"In a cache folder on your local disk.")," This way you can switch between different branches without\nlosing your incremental build state. You can even configure a centralized folder to be shared between\nmultiple enlistments on your machine. The default location is ",(0,o.kt)("strong",{parentName:"p"},"common/temp/build-cache"),".")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("strong",{parentName:"p"},"In a cloud-hosted storage container. (Optional)")," In a typical setup, the CI system would be configured to write\nto cloud storage, and individual users are granted read-only access. For example, each time a PR is merged into\nthe ",(0,o.kt)("inlineCode",{parentName:"p"},"main")," branch, the CI system builds that baseline and uploads it to cloud storage. Even for a user who\nis doing ",(0,o.kt)("inlineCode",{parentName:"p"},"git clone")," for the first time, their ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," will be very fast."))),(0,o.kt)("h2",{id:"enabling-the-local-disk-cache"},"Enabling the local disk cache"),(0,o.kt)("p",null,"The build cache feature is enabled using the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/build-cache_json"},"build-cache.json"),"\nconfig file. You can copy the template from the website or use ",(0,o.kt)("inlineCode",{parentName:"p"},"rush init")," to create this file."),(0,o.kt)("p",null,"To enable the basic local disk cache, add these two settings:"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"common/config/rush/build-cache.json")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js"},'{\n . . .\n /**\n * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.\n *\n * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.\n */\n "buildCacheEnabled": true,\n\n /**\n * (Required) Choose where project build outputs will be cached.\n *\n * Possible values: "local-only", "azure-blob-storage", "amazon-s3"\n */\n "cacheProvider": "local-only",\n\n . . .\n}\n')),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},(0,o.kt)("strong",{parentName:"p"},"Upgrade note:")," Early releases of this feature were enabled using the ",(0,o.kt)("inlineCode",{parentName:"p"},'"buildCache": true')," setting\nin ",(0,o.kt)("strong",{parentName:"p"},"experiments.json"),". This has been superseded by ",(0,o.kt)("inlineCode",{parentName:"p"},'"buildCacheEnabled"')," in ",(0,o.kt)("strong",{parentName:"p"},"build-cache.json"),".")),(0,o.kt)("h2",{id:"configuring-project-output-folders"},"Configuring project output folders"),(0,o.kt)("p",null,"With only this change, if you run ",(0,o.kt)("inlineCode",{parentName:"p"},"rush rebuild --verbose"),", you will see this warning:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"Project does not have a rush-project.json configuration file, or one provided by a rig,\nso it does not support caching.\n")),(0,o.kt)("p",null,"The build cache needs to know which folders should be stored in the tar archive. Those details vary between\ntoolchains, and are thus configured separately for each project using the\n",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/rush-project_json"},"rush-project.json")," config file."),(0,o.kt)("p",null,"For example:"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"<","your-project",">","/config/rush-project.json")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js"},'{\n . . .\n\n /**\n * Specify the folders where your toolchain writes its output files. If enabled, the Rush build cache will\n * restore these folders from the cache.\n *\n * The strings are folder names under the project root folder. These folders should not be tracked by Git.\n * They must not contain symlinks.\n */\n "projectOutputFolderNames": ["lib", "dist"]\n . . .\n}\n')),(0,o.kt)("p",null,"The cache key by default will consider your project's inputs to be the source files under the project folder\nthat are not excluded by ",(0,o.kt)("inlineCode",{parentName:"p"},".gitignore"),"; the details can be customized using\nthe ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/rush-project_json"},"rush-project.json")," config file."),(0,o.kt)("p",null,"It's recommended to use a ",(0,o.kt)("a",{parentName:"p",href:"https://rushstack.io/pages/heft/rig_packages/"},"rig package")," to avoid having\nto copy this file into each project folder."),(0,o.kt)("h2",{id:"testing-the-build-cache"},"Testing the build cache"),(0,o.kt)("p",null,"Now you should see projects being cached as shown in this sample log output:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"rush build --verbose\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'. . .\n\n==[ example-project ]==============================================[ 1 of 5 ]==\n\nThis project was not found in the build cache.\n\nInvoking: heft test --clean\n\n. . .\n\nCaching build output folders: lib\n\nSuccessfully set cache entry.\n\n"example-project" completed successfully in 11.27 seconds.\n')),(0,o.kt)("p",null,"When we run the same command a second time, Rush extracts the archive instead of invoking the build task:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"rush build --verbose\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},". . .\n\n==[ example-project ]==============================================[ 1 of 5 ]==\n\nBuild cache hit.\n\nClearing cached folders: lib, dist\n\nSuccessfully restored output from the build cache.\n\nexample-project was restored from the build cache.\n")),(0,o.kt)("p",null,"Note that ",(0,o.kt)("inlineCode",{parentName:"p"},"rush rebuild")," will not read from cache, only ",(0,o.kt)("inlineCode",{parentName:"p"},"rush build")," does. To disable writing from cache during ",(0,o.kt)("inlineCode",{parentName:"p"},"rush rebuild"),",\nset the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/environment_vars"},(0,o.kt)("inlineCode",{parentName:"a"},"RUSH_BUILD_CACHE_WRITE_ALLOWED"))," environment variable to ",(0,o.kt)("inlineCode",{parentName:"p"},"0"),"."),(0,o.kt)("p",null,"By default, the cached tar archives are stored under your ",(0,o.kt)("strong",{parentName:"p"},"common/temp/build-cache")," folder\n(and thus will be cleaned by ",(0,o.kt)("inlineCode",{parentName:"p"},"rush purge"),"). It is safe to delete these files."),(0,o.kt)("h2",{id:"enabling-cloud-storage"},"Enabling cloud storage"),(0,o.kt)("p",null,"Currently the ",(0,o.kt)("inlineCode",{parentName:"p"},"cacheProvider")," setting provides three choices:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},'"local-only"'),": no cloud storage; archives are only kept on a local disk folder"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},'"azure-blob-storage"'),": Microsoft Azure ",(0,o.kt)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us/azure/storage/blobs/"},"blob storage container")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},'"amazon-s3"'),": Amazon ",(0,o.kt)("a",{parentName:"li",href:"https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html"},"S3 bucket"))),(0,o.kt)("p",null,"(The above providers are ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/microsoft/rushstack/tree/main/rush-plugins"},"modeled as Rush plugins"),".\nCustom build cache storage providers can be implemented in the same way.)"),(0,o.kt)("p",null,"As one example, here's how to configure an Azure blob container:"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"common/config/rush/build-cache.json")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js"},'{\n . . .\n /**\n * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.\n *\n * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.\n */\n "buildCacheEnabled": true,\n\n /**\n * (Required) Choose where project build outputs will be cached.\n *\n * Possible values: "local-only", "azure-blob-storage", "amazon-s3"\n */\n "cacheProvider": "azure-blob-storage",\n\n /**\n * Use this configuration with "cacheProvider"="azure-blob-storage"\n */\n "azureBlobStorageConfiguration": {\n /**\n * (Required) The name of the the Azure storage account to use for build cache.\n */\n "storageAccountName": "example",\n\n /**\n * The name of the container in the Azure storage account to use for build cache.\n */\n "storageContainerName": "my-container"\n\n /**\n * If set to true, allow writing to the cache. Defaults to false.\n */\n "isCacheWriteAllowed": false\n\n . . .\n')),(0,o.kt)("p",null,"Note that we have set ",(0,o.kt)("inlineCode",{parentName:"p"},'"isCacheWriteAllowed": false')," to prevent regular users from writing to the container.\n(Later, we will use an environment variable to override this for our CI job.)"),(0,o.kt)("h2",{id:"user-authentication"},"User authentication"),(0,o.kt)("p",null,"If security is not a priority for your repo, you can simplify user setup by configuring your storage container\nto allow unauthenticated anonymous access. The container is accessed via an HTTPS URL containing randomized\nhashes which are difficult to guess without access to your Git repo. This provides rudimentary\n",(0,o.kt)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Security_through_obscurity"},"security through obscurity"),"."),(0,o.kt)("p",null,"A more security-conscious organization however will prefer to require authentication even for read-only access.\nRush provides a ",(0,o.kt)("a",{parentName:"p",href:"/pages/commands/rush_update-cloud-credentials"},"rush update-cloud-credentials"),"\ncommand to make this easy for users to set up:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"rush update-cloud-credentials --interactive\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'Rush Multi-Project Build Tool 5.45.6 (unmanaged) - https://rushjs.io\nNode.js version is 12.20.1 (LTS)\n\n\nStarting "rush update-cloud-credentials"\n\n \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n \u2551 To sign in, use a web browser to open the page \u2551\n \u2551 https://microsoft.com/devicelogin and enter the code XAYBQEGRK \u2551\n \u2551 to authenticate. \u2551\n \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n')),(0,o.kt)("p",null,"The credentials are stored in the user's home directory under ",(0,o.kt)("inlineCode",{parentName:"p"},"~/.rush-user/credentials.json"),"."),(0,o.kt)("h2",{id:"ci-setup"},"CI setup"),(0,o.kt)("p",null,"In a typical configuration, users have read-only access and the cache is populated by an automation account;\nfor example, a CI job that builds your ",(0,o.kt)("inlineCode",{parentName:"p"},"main")," branch after each PR is merged. In our example above, the\n",(0,o.kt)("inlineCode",{parentName:"p"},'"isCacheWriteAllowed": false')," setting is what prevents users from writing to the cache. The CI job can\noverride this by setting the ",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/environment_vars"},"RUSH_BUILD_CACHE_WRITE_ALLOWED"),"\nenvironment variable, and by providing credentials for the CI environment in the\n",(0,o.kt)("a",{parentName:"p",href:"/pages/configs/environment_vars"},"RUSH_BUILD_CACHE_CREDENTIAL")," environment variable."),(0,o.kt)("h3",{id:"credentials"},"Credentials"),(0,o.kt)("h4",{id:"azure-storage"},"Azure Storage"),(0,o.kt)("p",null,"For Azure Blob Storage, ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," must be a SAS token serialized as query parameters.\nSee ",(0,o.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview"},"this article")," for details\nabout SAS tokens. You can obtain a SAS token via the ",(0,o.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?tabs=azure-portal"},"Settings > Access keys"),"\npage for your storage account."),(0,o.kt)("h4",{id:"aws"},"AWS"),(0,o.kt)("p",null,"For Amazon S3, ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," will be your AWS Access Key ID and AWS Secret Access Key separated by a colon,\nsuch as: ",(0,o.kt)("inlineCode",{parentName:"p"},":"),". You can also pass temporary session tokens required when assuming an IAM role: ",(0,o.kt)("inlineCode",{parentName:"p"},"::"),"."),(0,o.kt)("p",null,"If ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," is not set, the build cache will attempt to read the environment vars ",(0,o.kt)("inlineCode",{parentName:"p"},"AWS_ACCESS_KEY_ID"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"AWS_SECRET_ACCESS_KEY"),", and ",(0,o.kt)("inlineCode",{parentName:"p"},"AWS_SESSION_TOKEN")," that\nare commonly set via the AWS CLI or other CI tooling. However, ",(0,o.kt)("inlineCode",{parentName:"p"},"RUSH_BUILD_CACHE_CREDENTIAL")," will always take precedence if it exists."),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},"The build cache feature is still under development. Feedback is welcome!"),(0,o.kt)("p",{parentName:"blockquote"},"Some relevant GitHub issues to follow:"),(0,o.kt)("ul",{parentName:"blockquote"},(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2393"},"Build cache feature #2393")," - the original feature spec"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2642"},"Build Cache: split apart RUSH_BUILD_CACHE_WRITE_CREDENTIAL #2642")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2618"},"Allow project config to specify non-build-related files #2618")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/microsoft/rushstack/issues/2622"},'"tar" exited with code 1 while attempting to create the cache entry #2622')))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.428f368b.js b/assets/js/runtime~main.b1e683a4.js similarity index 99% rename from assets/js/runtime~main.428f368b.js rename to assets/js/runtime~main.b1e683a4.js index fc8fbd29..761a578d 100644 --- a/assets/js/runtime~main.428f368b.js +++ b/assets/js/runtime~main.b1e683a4.js @@ -1 +1 @@ -(()=>{"use strict";var e,a,c,d,f,b={},t={};function r(e){var a=t[e];if(void 0!==a)return a.exports;var c=t[e]={exports:{}};return b[e].call(c.exports,c,c.exports,r),c.exports}r.m=b,e=[],r.O=(a,c,d,f)=>{if(!c){var b=1/0;for(i=0;i=f)&&Object.keys(r.O).every((e=>r.O[e](c[o])))?c.splice(o--,1):(t=!1,f0&&e[i-1][2]>f;i--)e[i]=e[i-1];e[i]=[c,d,f]},r.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return r.d(a,{a:a}),a},c=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,r.t=function(e,d){if(1&d&&(e=this(e)),8&d)return e;if("object"==typeof e&&e){if(4&d&&e.__esModule)return e;if(16&d&&"function"==typeof e.then)return e}var f=Object.create(null);r.r(f);var b={};a=a||[null,c({}),c([]),c(c)];for(var t=2&d&&e;"object"==typeof t&&!~a.indexOf(t);t=c(t))Object.getOwnPropertyNames(t).forEach((a=>b[a]=()=>e[a]));return b.default=()=>e,r.d(f,b),f},r.d=(e,a)=>{for(var c in a)r.o(a,c)&&!r.o(e,c)&&Object.defineProperty(e,c,{enumerable:!0,get:a[c]})},r.f={},r.e=e=>Promise.all(Object.keys(r.f).reduce(((a,c)=>(r.f[c](e,a),a)),[])),r.u=e=>"assets/js/"+({53:"935f2afb",328:"235044f7",404:"4438d6ba",471:"0684aa34",514:"90ddd12c",528:"0621135e",554:"d0002971",607:"cd7aa8bf",647:"e3035796",769:"577e77e8",887:"3e2d6682",1044:"0765952b",1122:"846c8d6e",1299:"04c3341c",1322:"a8f877c2",1400:"df160fbc",1442:"a0380121",1815:"5e6284ec",1949:"282c1a37",2140:"233c0c3f",2377:"1dc5c5b7",2440:"7ccd1f8a",2563:"2ed09d84",2570:"02ccd5d4",2583:"e4f5d984",2692:"223e0a36",2722:"eef550e9",2751:"7bc9a246",2823:"7b619af1",3034:"3d9b5d3d",3060:"c9322d33",3173:"fc5d18da",3224:"33a22dbe",3237:"1df93b7f",3523:"68b67c52",3566:"a3435be8",3904:"e541189a",3951:"3020617b",4044:"28dd16ce",4070:"c4f4e2a2",4199:"75321ab6",4288:"06aed492",4290:"d1ff4259",4315:"5b152299",4599:"6d08bb7e",4656:"571dcc93",4668:"dd2d64b6",4696:"c1874168",4708:"35c43f5f",4723:"6a5786be",4794:"e439323c",4973:"a6ae31b5",5244:"62a372f1",5333:"182eac2e",5418:"1c28e8c2",5584:"5aaad5b7",5659:"bd6bf340",5711:"a483313a",5964:"3579650a",6016:"d9ccc361",6073:"ad372154",6078:"6b59883c",6165:"e33f9b2e",6202:"cbd0bb2d",6218:"d8d12fe7",6225:"30925530",6339:"d98d853d",6557:"8edc8e08",6640:"0fc792b0",6746:"10a14b75",6969:"6ae68ea7",7029:"95a336c6",7194:"a5720c04",7357:"9949baf9",7467:"04cbcf03",7603:"aa9a0c9f",7651:"ebea99ed",7722:"2970f5d1",7918:"17896441",7920:"1a4e3797",8149:"fc35d859",8179:"8f311749",8246:"f5155a44",8277:"063a13ec",8400:"d88be1c1",8413:"3ac5f93e",8649:"f653bd9f",8661:"438f83e3",8764:"65cd7bc2",8791:"bad14213",8848:"f5b5f31d",8922:"57a267e5",9066:"0c7c0fa8",9122:"7bc8bbc0",9184:"dd413e20",9190:"dbf9ac6b",9329:"44c7a5f9",9361:"b93162f9",9514:"1be78505",9624:"5d4477f0",9672:"9279c390",9798:"74b61b4b",9871:"2aaefaac"}[e]||e)+"."+{53:"d71d98d5",328:"94b13d2d",404:"d6a552db",471:"50e168df",514:"1b808413",528:"1f067c3e",554:"564cf252",607:"427d6564",647:"f3cb050b",769:"ab0738a9",887:"ccd5672e",1044:"8aef515e",1122:"d671f878",1299:"2ca7703a",1322:"f4783669",1400:"e50f0b92",1442:"a092dc8a",1815:"77ac0eb1",1949:"9c34ba06",2140:"f67ff391",2377:"f10a3e9e",2440:"f6c0ebf0",2563:"e9a19000",2570:"aefa393c",2583:"5bdf0329",2692:"f63335a1",2722:"82bef283",2751:"25626dac",2823:"e5e644ad",2832:"0d9a94f2",2928:"9d23e8f2",3034:"1f146f9b",3060:"22fc8ded",3173:"e01e4d51",3224:"b08b75f1",3237:"00c2849c",3523:"98deeedc",3566:"bd85f904",3904:"f5e75793",3951:"5c3423f6",4044:"25c239fd",4070:"37176b3e",4199:"08c274dd",4288:"368d8cbc",4290:"5289cd18",4315:"b8c4c9ed",4391:"e2e60112",4599:"8218d3fc",4656:"79876acc",4668:"d880c294",4696:"80259771",4708:"aa3a3524",4723:"ff329ad1",4794:"c3fd771e",4973:"e0eb258f",5244:"e82a43b4",5333:"03ad7749",5418:"2c08385f",5502:"09e1c67b",5584:"c5d210b5",5659:"882ac1c7",5711:"8eb870ce",5964:"ab415ac8",6016:"d0c63308",6073:"1595ca27",6078:"812ea7a5",6165:"275a8594",6202:"eb5cbc86",6218:"0f488f2d",6225:"9e14104c",6339:"a6d59eab",6557:"e232ced2",6640:"ca609e18",6746:"2dbf61cc",6969:"53123f99",7029:"2cbd9d5c",7194:"78ab0997",7357:"1bbd2974",7467:"2ae81311",7603:"2e08e802",7651:"3d609d2d",7722:"26908a52",7918:"781e8e87",7920:"d74d357c",8149:"a8a4fc62",8179:"3923df19",8246:"f9f0bbb3",8277:"bd9e0590",8400:"9d165d89",8413:"9c9d7999",8649:"cf6e00d7",8661:"8ba2dab9",8764:"2d6fa7f0",8791:"68cd0730",8848:"d4d3b20a",8922:"d9558ac8",8988:"5a29583b",9042:"eabad492",9066:"9a39ac46",9122:"257c2150",9184:"712be8e4",9190:"d272aba7",9329:"06bc77c4",9361:"49447d6b",9485:"879ad254",9514:"8ffd2c13",9624:"80d9e9ca",9672:"8dd00097",9798:"ddc57431",9871:"48443af5",9970:"6f0174d1"}[e]+".js",r.miniCssF=e=>{},r.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),r.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),d={},f="rushjs.io:",r.l=(e,a,c,b)=>{if(d[e])d[e].push(a);else{var t,o;if(void 0!==c)for(var n=document.getElementsByTagName("script"),i=0;i{t.onerror=t.onload=null,clearTimeout(s);var f=d[e];if(delete d[e],t.parentNode&&t.parentNode.removeChild(t),f&&f.forEach((e=>e(c))),a)return a(c)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:t}),12e4);t.onerror=l.bind(null,t.onerror),t.onload=l.bind(null,t.onload),o&&document.head.appendChild(t)}},r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.p="/",r.gca=function(e){return e={17896441:"7918",30925530:"6225","935f2afb":"53","235044f7":"328","4438d6ba":"404","0684aa34":"471","90ddd12c":"514","0621135e":"528",d0002971:"554",cd7aa8bf:"607",e3035796:"647","577e77e8":"769","3e2d6682":"887","0765952b":"1044","846c8d6e":"1122","04c3341c":"1299",a8f877c2:"1322",df160fbc:"1400",a0380121:"1442","5e6284ec":"1815","282c1a37":"1949","233c0c3f":"2140","1dc5c5b7":"2377","7ccd1f8a":"2440","2ed09d84":"2563","02ccd5d4":"2570",e4f5d984:"2583","223e0a36":"2692",eef550e9:"2722","7bc9a246":"2751","7b619af1":"2823","3d9b5d3d":"3034",c9322d33:"3060",fc5d18da:"3173","33a22dbe":"3224","1df93b7f":"3237","68b67c52":"3523",a3435be8:"3566",e541189a:"3904","3020617b":"3951","28dd16ce":"4044",c4f4e2a2:"4070","75321ab6":"4199","06aed492":"4288",d1ff4259:"4290","5b152299":"4315","6d08bb7e":"4599","571dcc93":"4656",dd2d64b6:"4668",c1874168:"4696","35c43f5f":"4708","6a5786be":"4723",e439323c:"4794",a6ae31b5:"4973","62a372f1":"5244","182eac2e":"5333","1c28e8c2":"5418","5aaad5b7":"5584",bd6bf340:"5659",a483313a:"5711","3579650a":"5964",d9ccc361:"6016",ad372154:"6073","6b59883c":"6078",e33f9b2e:"6165",cbd0bb2d:"6202",d8d12fe7:"6218",d98d853d:"6339","8edc8e08":"6557","0fc792b0":"6640","10a14b75":"6746","6ae68ea7":"6969","95a336c6":"7029",a5720c04:"7194","9949baf9":"7357","04cbcf03":"7467",aa9a0c9f:"7603",ebea99ed:"7651","2970f5d1":"7722","1a4e3797":"7920",fc35d859:"8149","8f311749":"8179",f5155a44:"8246","063a13ec":"8277",d88be1c1:"8400","3ac5f93e":"8413",f653bd9f:"8649","438f83e3":"8661","65cd7bc2":"8764",bad14213:"8791",f5b5f31d:"8848","57a267e5":"8922","0c7c0fa8":"9066","7bc8bbc0":"9122",dd413e20:"9184",dbf9ac6b:"9190","44c7a5f9":"9329",b93162f9:"9361","1be78505":"9514","5d4477f0":"9624","9279c390":"9672","74b61b4b":"9798","2aaefaac":"9871"}[e]||e,r.p+r.u(e)},(()=>{var e={1303:0,532:0};r.f.j=(a,c)=>{var d=r.o(e,a)?e[a]:void 0;if(0!==d)if(d)c.push(d[2]);else if(/^(1303|532)$/.test(a))e[a]=0;else{var f=new Promise(((c,f)=>d=e[a]=[c,f]));c.push(d[2]=f);var b=r.p+r.u(a),t=new Error;r.l(b,(c=>{if(r.o(e,a)&&(0!==(d=e[a])&&(e[a]=void 0),d)){var f=c&&("load"===c.type?"missing":c.type),b=c&&c.target&&c.target.src;t.message="Loading chunk "+a+" failed.\n("+f+": "+b+")",t.name="ChunkLoadError",t.type=f,t.request=b,d[1](t)}}),"chunk-"+a,a)}},r.O.j=a=>0===e[a];var a=(a,c)=>{var d,f,[b,t,o]=c,n=0;if(b.some((a=>0!==e[a]))){for(d in t)r.o(t,d)&&(r.m[d]=t[d]);if(o)var i=o(r)}for(a&&a(c);n{"use strict";var e,a,c,d,f,b={},t={};function r(e){var a=t[e];if(void 0!==a)return a.exports;var c=t[e]={exports:{}};return b[e].call(c.exports,c,c.exports,r),c.exports}r.m=b,e=[],r.O=(a,c,d,f)=>{if(!c){var b=1/0;for(i=0;i=f)&&Object.keys(r.O).every((e=>r.O[e](c[o])))?c.splice(o--,1):(t=!1,f0&&e[i-1][2]>f;i--)e[i]=e[i-1];e[i]=[c,d,f]},r.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return r.d(a,{a:a}),a},c=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,r.t=function(e,d){if(1&d&&(e=this(e)),8&d)return e;if("object"==typeof e&&e){if(4&d&&e.__esModule)return e;if(16&d&&"function"==typeof e.then)return e}var f=Object.create(null);r.r(f);var b={};a=a||[null,c({}),c([]),c(c)];for(var t=2&d&&e;"object"==typeof t&&!~a.indexOf(t);t=c(t))Object.getOwnPropertyNames(t).forEach((a=>b[a]=()=>e[a]));return b.default=()=>e,r.d(f,b),f},r.d=(e,a)=>{for(var c in a)r.o(a,c)&&!r.o(e,c)&&Object.defineProperty(e,c,{enumerable:!0,get:a[c]})},r.f={},r.e=e=>Promise.all(Object.keys(r.f).reduce(((a,c)=>(r.f[c](e,a),a)),[])),r.u=e=>"assets/js/"+({53:"935f2afb",328:"235044f7",404:"4438d6ba",471:"0684aa34",514:"90ddd12c",528:"0621135e",554:"d0002971",607:"cd7aa8bf",647:"e3035796",769:"577e77e8",887:"3e2d6682",1044:"0765952b",1122:"846c8d6e",1299:"04c3341c",1322:"a8f877c2",1400:"df160fbc",1442:"a0380121",1815:"5e6284ec",1949:"282c1a37",2140:"233c0c3f",2377:"1dc5c5b7",2440:"7ccd1f8a",2563:"2ed09d84",2570:"02ccd5d4",2583:"e4f5d984",2692:"223e0a36",2722:"eef550e9",2751:"7bc9a246",2823:"7b619af1",3034:"3d9b5d3d",3060:"c9322d33",3173:"fc5d18da",3224:"33a22dbe",3237:"1df93b7f",3523:"68b67c52",3566:"a3435be8",3904:"e541189a",3951:"3020617b",4044:"28dd16ce",4070:"c4f4e2a2",4199:"75321ab6",4288:"06aed492",4290:"d1ff4259",4315:"5b152299",4599:"6d08bb7e",4656:"571dcc93",4668:"dd2d64b6",4696:"c1874168",4708:"35c43f5f",4723:"6a5786be",4794:"e439323c",4973:"a6ae31b5",5244:"62a372f1",5333:"182eac2e",5418:"1c28e8c2",5584:"5aaad5b7",5659:"bd6bf340",5711:"a483313a",5964:"3579650a",6016:"d9ccc361",6073:"ad372154",6078:"6b59883c",6165:"e33f9b2e",6202:"cbd0bb2d",6218:"d8d12fe7",6225:"30925530",6339:"d98d853d",6557:"8edc8e08",6640:"0fc792b0",6746:"10a14b75",6969:"6ae68ea7",7029:"95a336c6",7194:"a5720c04",7357:"9949baf9",7467:"04cbcf03",7603:"aa9a0c9f",7651:"ebea99ed",7722:"2970f5d1",7918:"17896441",7920:"1a4e3797",8149:"fc35d859",8179:"8f311749",8246:"f5155a44",8277:"063a13ec",8400:"d88be1c1",8413:"3ac5f93e",8649:"f653bd9f",8661:"438f83e3",8764:"65cd7bc2",8791:"bad14213",8848:"f5b5f31d",8922:"57a267e5",9066:"0c7c0fa8",9122:"7bc8bbc0",9184:"dd413e20",9190:"dbf9ac6b",9329:"44c7a5f9",9361:"b93162f9",9514:"1be78505",9624:"5d4477f0",9672:"9279c390",9798:"74b61b4b",9871:"2aaefaac"}[e]||e)+"."+{53:"d71d98d5",328:"94b13d2d",404:"d6a552db",471:"50e168df",514:"1b808413",528:"1f067c3e",554:"564cf252",607:"427d6564",647:"f3cb050b",769:"ab0738a9",887:"ccd5672e",1044:"8aef515e",1122:"d671f878",1299:"2ca7703a",1322:"f4783669",1400:"e50f0b92",1442:"a092dc8a",1815:"77ac0eb1",1949:"9c34ba06",2140:"f67ff391",2377:"f10a3e9e",2440:"f6c0ebf0",2563:"e9a19000",2570:"aefa393c",2583:"5bdf0329",2692:"f63335a1",2722:"82bef283",2751:"25626dac",2823:"e5e644ad",2832:"0d9a94f2",2928:"9d23e8f2",3034:"1f146f9b",3060:"22fc8ded",3173:"e01e4d51",3224:"b08b75f1",3237:"00c2849c",3523:"98deeedc",3566:"bd85f904",3904:"f5e75793",3951:"5c3423f6",4044:"25c239fd",4070:"37176b3e",4199:"08c274dd",4288:"368d8cbc",4290:"5289cd18",4315:"b8c4c9ed",4391:"e2e60112",4599:"8218d3fc",4656:"79876acc",4668:"d880c294",4696:"80259771",4708:"aa3a3524",4723:"ff329ad1",4794:"c3fd771e",4973:"e0eb258f",5244:"e82a43b4",5333:"03ad7749",5418:"2c08385f",5502:"09e1c67b",5584:"c5d210b5",5659:"882ac1c7",5711:"8eb870ce",5964:"ab415ac8",6016:"d0c63308",6073:"1595ca27",6078:"812ea7a5",6165:"275a8594",6202:"eb5cbc86",6218:"0f488f2d",6225:"9e14104c",6339:"3513af17",6557:"e232ced2",6640:"ca609e18",6746:"2dbf61cc",6969:"53123f99",7029:"2cbd9d5c",7194:"78ab0997",7357:"1bbd2974",7467:"2ae81311",7603:"2e08e802",7651:"3d609d2d",7722:"26908a52",7918:"781e8e87",7920:"d74d357c",8149:"a8a4fc62",8179:"3923df19",8246:"f9f0bbb3",8277:"bd9e0590",8400:"9d165d89",8413:"9c9d7999",8649:"cf6e00d7",8661:"8ba2dab9",8764:"2d6fa7f0",8791:"68cd0730",8848:"d4d3b20a",8922:"d9558ac8",8988:"5a29583b",9042:"eabad492",9066:"9a39ac46",9122:"257c2150",9184:"712be8e4",9190:"d272aba7",9329:"06bc77c4",9361:"49447d6b",9485:"879ad254",9514:"8ffd2c13",9624:"80d9e9ca",9672:"8dd00097",9798:"ddc57431",9871:"48443af5",9970:"6f0174d1"}[e]+".js",r.miniCssF=e=>{},r.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),r.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),d={},f="rushjs.io:",r.l=(e,a,c,b)=>{if(d[e])d[e].push(a);else{var t,o;if(void 0!==c)for(var n=document.getElementsByTagName("script"),i=0;i{t.onerror=t.onload=null,clearTimeout(s);var f=d[e];if(delete d[e],t.parentNode&&t.parentNode.removeChild(t),f&&f.forEach((e=>e(c))),a)return a(c)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:t}),12e4);t.onerror=l.bind(null,t.onerror),t.onload=l.bind(null,t.onload),o&&document.head.appendChild(t)}},r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.p="/",r.gca=function(e){return e={17896441:"7918",30925530:"6225","935f2afb":"53","235044f7":"328","4438d6ba":"404","0684aa34":"471","90ddd12c":"514","0621135e":"528",d0002971:"554",cd7aa8bf:"607",e3035796:"647","577e77e8":"769","3e2d6682":"887","0765952b":"1044","846c8d6e":"1122","04c3341c":"1299",a8f877c2:"1322",df160fbc:"1400",a0380121:"1442","5e6284ec":"1815","282c1a37":"1949","233c0c3f":"2140","1dc5c5b7":"2377","7ccd1f8a":"2440","2ed09d84":"2563","02ccd5d4":"2570",e4f5d984:"2583","223e0a36":"2692",eef550e9:"2722","7bc9a246":"2751","7b619af1":"2823","3d9b5d3d":"3034",c9322d33:"3060",fc5d18da:"3173","33a22dbe":"3224","1df93b7f":"3237","68b67c52":"3523",a3435be8:"3566",e541189a:"3904","3020617b":"3951","28dd16ce":"4044",c4f4e2a2:"4070","75321ab6":"4199","06aed492":"4288",d1ff4259:"4290","5b152299":"4315","6d08bb7e":"4599","571dcc93":"4656",dd2d64b6:"4668",c1874168:"4696","35c43f5f":"4708","6a5786be":"4723",e439323c:"4794",a6ae31b5:"4973","62a372f1":"5244","182eac2e":"5333","1c28e8c2":"5418","5aaad5b7":"5584",bd6bf340:"5659",a483313a:"5711","3579650a":"5964",d9ccc361:"6016",ad372154:"6073","6b59883c":"6078",e33f9b2e:"6165",cbd0bb2d:"6202",d8d12fe7:"6218",d98d853d:"6339","8edc8e08":"6557","0fc792b0":"6640","10a14b75":"6746","6ae68ea7":"6969","95a336c6":"7029",a5720c04:"7194","9949baf9":"7357","04cbcf03":"7467",aa9a0c9f:"7603",ebea99ed:"7651","2970f5d1":"7722","1a4e3797":"7920",fc35d859:"8149","8f311749":"8179",f5155a44:"8246","063a13ec":"8277",d88be1c1:"8400","3ac5f93e":"8413",f653bd9f:"8649","438f83e3":"8661","65cd7bc2":"8764",bad14213:"8791",f5b5f31d:"8848","57a267e5":"8922","0c7c0fa8":"9066","7bc8bbc0":"9122",dd413e20:"9184",dbf9ac6b:"9190","44c7a5f9":"9329",b93162f9:"9361","1be78505":"9514","5d4477f0":"9624","9279c390":"9672","74b61b4b":"9798","2aaefaac":"9871"}[e]||e,r.p+r.u(e)},(()=>{var e={1303:0,532:0};r.f.j=(a,c)=>{var d=r.o(e,a)?e[a]:void 0;if(0!==d)if(d)c.push(d[2]);else if(/^(1303|532)$/.test(a))e[a]=0;else{var f=new Promise(((c,f)=>d=e[a]=[c,f]));c.push(d[2]=f);var b=r.p+r.u(a),t=new Error;r.l(b,(c=>{if(r.o(e,a)&&(0!==(d=e[a])&&(e[a]=void 0),d)){var f=c&&("load"===c.type?"missing":c.type),b=c&&c.target&&c.target.src;t.message="Loading chunk "+a+" failed.\n("+f+": "+b+")",t.name="ChunkLoadError",t.type=f,t.request=b,d[1](t)}}),"chunk-"+a,a)}},r.O.j=a=>0===e[a];var a=(a,c)=>{var d,f,[b,t,o]=c,n=0;if(b.some((a=>0!==e[a]))){for(d in t)r.o(t,d)&&(r.m[d]=t[d]);if(o)var i=o(r)}for(a&&a(c);nRush - +
Rush StackShopBlogEvents

Rush: a scalable monorepo manager for the web

Rush makes life easier for JavaScript developers who build and publish many packages from a common Git repo. If you're looking to break up your giant application into smaller pieces, and you already realized why it doesn't work to put each package in a separate repo... then Rush is for you!

monorepo diagram
monorepo diagram

The Rush difference

These days many different tools can run "npm install" and "npm run build" in 20 different folders. What's so great about Rush?

Git repositories

Ready for large repos

Rush is built by professional engineers who maintain large production monorepos. Our job is to provide the best developer experience for our colleagues, not to convert you into a customer for a paid consulting or hosting service. The repositories we maintain contain hundreds of apps with many years of Git history. To manage this scale, Rush offers parallel builds, subset builds, incremental builds, and distributed builds.

large team

Designed for large teams

Rush provides many mechanisms for onboarding newcomers and coordinating collaboration between teams. Repo policies allow new package dependencies to be reviewed before they are accepted. Rush can enforce consistent dependency versions across your repo. Different subsets of projects can publish separately with lockstep or independent versioning strategies.

NPM phantom dependency

Reliable NPM installations

Rush's installation model leverages the PNPM package manager to eliminate the phantom dependencies and NPM doppelgangers that frustrate large scale installations. You can visualize and troubleshoot version conflicts using our Lockfile Explorer companion tool.

motorbike and tricycle

Easy to administer

When you maintain a large repo, you don't want developers opening support tickets that can't be reproduced on any other computer. Rush helps to ensure that installs and builds are completely deterministic. Even the Rush engine version is automatically installed according to your Git branch. If you define custom commands or options, they are strictly validated and documented as part of Rush's command-line help.

army knife

Turnkey solution

Tired of cobbling together your developer experience from multiple tools that never seem to integrate properly? Rush is a unified orchestrator that can install, link, build, generate change logs, publish, and bump versions. These features are designed to integrate with the broader Rush Stack suite of tools and practices.

free price tag

Open model

The Rush software is free and open source. Community contributions are welcome! We're also open-minded about your toolchain: In a Rush repo, each project folder remains fully self-contained, individually installable, and easy to relocate if needed. Relatively little effort is required to enable/disable Rush for a given set of projects.

Who's using Rush?

Azure SDK logo
Azure SDK
HBO Max logo
HBO Max
OneDrive logo
OneDrive
SharePoint logo
SharePoint
Office 365 Small Business logo
Office 365 Small Business
Windows Store logo
Windows Store
Office Web Apps logo
Office Web Apps
SimplrJS react-forms logo
SimplrJS react-forms
Telia Company logo
Telia Company
Welbi logo
Welbi
Wix logo
Wix
© 2023 Microsoft
- + \ No newline at end of file diff --git a/link/pnpm-issue-5132/index.html b/link/pnpm-issue-5132/index.html index 408d1e89..8ad37154 100644 --- a/link/pnpm-issue-5132/index.html +++ b/link/pnpm-issue-5132/index.html @@ -6,13 +6,13 @@ pnpm-issue-5132 | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/link/upgrading/index.html b/link/upgrading/index.html index 5d2592e4..a3c6410c 100644 --- a/link/upgrading/index.html +++ b/link/upgrading/index.html @@ -6,13 +6,13 @@ upgrading | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/api/index.html b/pages/advanced/api/index.html index e3c9a16c..27a83986 100644 --- a/pages/advanced/api/index.html +++ b/pages/advanced/api/index.html @@ -6,13 +6,13 @@ api | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/compatibility_db/index.html b/pages/advanced/compatibility_db/index.html index ecf2cd9e..79a66492 100644 --- a/pages/advanced/compatibility_db/index.html +++ b/pages/advanced/compatibility_db/index.html @@ -6,13 +6,13 @@ PNPM Compatibility DB | Rush - +
Rush StackShopBlogEvents

PNPM Compatibility DB

Both Yarn and PNPM support a feature called the Compatibility DB, which is a public database of package.json fixups. These fixups solve known issues that the official maintainer of an NPM package may be unwilling to solve. (The best practice would be to avoid such packages, but often that is impractical.) Compatibility DB fixups are similar to user-authored rules found in .pnpmfile.cjs. They are maintained with the @yarnpkg/extensions package.

PNPM's feature protects small projects from common pitfalls, but the approach has some downsides for a large monorepo:

  • Hidden magic: The fixups are bundled into the PNPM binary. When trying to coordinate complex cross-project version dependencies, it is awkward for key inputs to be in a file with no Git diff, not even viewable in the GitHub website.
  • Unnecessary coupling: Different versions of the @yarnpkg/extensions rules are bundled into different PNPM releases. This may cause churn the lockfile when upgrading or downgrading the package manager.
  • Applied last: The fixups are applied after .pnpmfile.cjs. This means the fixed up versions aren't visible to the user's own transformations or logging, and .pnpmfile.cjs is no longer the final authority about version choices.

To avoid these issues, rush install and rush update always disable the Compatibility DB feature when invoking PNPM.

Details:

  • Compatibility DB is implemented by PNPM versions >= 6.32.12, >= 7.0.1 (but not 7.0.0)
  • The ignore-compatibility-db switch is implemented in newer PNPM releases: >= 6.34.0 <7.0.01 and >= 7.9.0
  • Compatibility DB is disabled by Rush versions >= 5.76.0 if possible...
  • ..otherwise, if the switch is missing, Rush prints a warning recommending to upgrade PNPM

The Compatibility DB fixes are useful. To apply them in your Rush repo, it's recommended to copy these settings into a proper Git-tracked file such as .pnpmfile.cjs.

💡 Feature idea: Propose an automated mechanism for syncing @yarnpkg/extensions into a Git-tracked file under common/config/rush.

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/config_files/index.html b/pages/advanced/config_files/index.html index 0ff3b43b..a9de7414 100644 --- a/pages/advanced/config_files/index.html +++ b/pages/advanced/config_files/index.html @@ -6,13 +6,13 @@ config_files | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/incremental_builds/index.html b/pages/advanced/incremental_builds/index.html index 8241f434..549db710 100644 --- a/pages/advanced/incremental_builds/index.html +++ b/pages/advanced/incremental_builds/index.html @@ -6,7 +6,7 @@ Incremental builds | Rush - + @@ -59,7 +59,7 @@ color of a button control, or some text in an error message.

The --changed-projects-only flag tells Rush to build only those projects where a file was changed:

rush build --only B

We'd invoke it like this:

# This command will rebuild B (but ignore the effects for C and D)
rush build --changed-projects-only

The --changed-projects-only is "unsafe" because errors might be encountered if the downstream projects actually did need to be rebuilt. This parameter saves time by assuming that you know better than Rush about what really needs to be built. If that assumption is incorrect, you can always do rush build to get back to a good state.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/installation_variants/index.html b/pages/advanced/installation_variants/index.html index dea39a7c..3c00b070 100644 --- a/pages/advanced/installation_variants/index.html +++ b/pages/advanced/installation_variants/index.html @@ -6,7 +6,7 @@ Installation variants | Rush - + @@ -39,7 +39,7 @@ state by running rush install without the --variant option. We call this the "default variant", because it's the same default behavior as a repo that didn't define any variants:

# Restore the original state by omitting "--variant":
rush install

Tip: If you forget which variant is active, you can look in the common/temp/current-variant.json file. If you open this file in a text editor, you should see a line like this:

{
 "variant": "old-widget-sdk"
}
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/npm_doppelgangers/index.html b/pages/advanced/npm_doppelgangers/index.html index 69ea649b..960f1d3b 100644 --- a/pages/advanced/npm_doppelgangers/index.html +++ b/pages/advanced/npm_doppelgangers/index.html @@ -6,7 +6,7 @@ NPM doppelgangers | Rush - + @@ -53,7 +53,7 @@ unfortunately doppelgangers are still possible for any indirect dependencies. Whereas if you use PNPM with Rush, the doppelganger problem is fully solved (because PNPM's installation model accurately simulates a true directed acyclic graph).

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/phantom_deps/index.html b/pages/advanced/phantom_deps/index.html index 9ef638ea..82e47317 100644 --- a/pages/advanced/phantom_deps/index.html +++ b/pages/advanced/phantom_deps/index.html @@ -6,7 +6,7 @@ Phantom dependencies | Rush - + @@ -81,7 +81,7 @@ sometimes find node_modules folders that aren't even under your Git working directory!

How Rush helps: Rush's got you covered. The rush install command scans all potential parent folders and issues a warning if any phantom node_modules folders are found.

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/pinned_versions/index.html b/pages/advanced/pinned_versions/index.html index 063c4683..603e6b0e 100644 --- a/pages/advanced/pinned_versions/index.html +++ b/pages/advanced/pinned_versions/index.html @@ -6,13 +6,13 @@ pinned_versions | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/preferred_versions/index.html b/pages/advanced/preferred_versions/index.html index 91c6a5d5..e2b58123 100644 --- a/pages/advanced/preferred_versions/index.html +++ b/pages/advanced/preferred_versions/index.html @@ -6,7 +6,7 @@ Preferred versions | Rush - + @@ -19,7 +19,7 @@ ranges. If you're encountering installation errors involving peer dependencies, we recommend to disable this behavior by setting implicitlyPreferredVersions to false in the common/config/rush/common-versions.json config file.

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/rush_files_and_folders/index.html b/pages/advanced/rush_files_and_folders/index.html index 9e042784..c39dd500 100644 --- a/pages/advanced/rush_files_and_folders/index.html +++ b/pages/advanced/rush_files_and_folders/index.html @@ -6,13 +6,13 @@ Rush files and folders | Rush - +
Rush StackShopBlogEvents

Rush files and folders

Every Rush monorepo has a standard folder structure that is created by rush init and validated by rush update.

Configuration files​

Folder pathWhat it does
rush.jsonThe main configuration file for Rush
common/config/rush/.npmrcIf you need custom settings for "npm install" (e.g. NPM registry mappings), put them in this file. Rush will copy this file into the common/temp/ folder.
common/config/rush/.npmrc-publishUsed instead of .npmrc for publishing operations.
common/config/artifactory.jsonConfiguration for Rush integration with JFrog Artifactory services.
common/config/build-cache.jsonConfiguration for Rush's Build cache
common/config/rush/command-line.jsonUsed to define custom commands.
common/config/rush/common-versions.jsonUsed to specify versions that affect all projects in a repo.
common/config/rush/deploy.jsonUsed to define profiles for the rush deploy command
common/config/rush/experiments.jsonEnables experimental features of Rush
common/config/rush/npm-shrinkwrap.jsonThe shrinkwrap file when your package manager is NPM. This is the common shrinkwrap file that applies to all projects in the Rush repo. For more information, see "What is this "shrinkwrap file" in the Everyday commands section.
common/config/rush/rush-plugins.jsonSpecifies Rush plugins to be loaded for the monorepo.
common/config/rush/pnpm-lock.yamlThe shrinkwrap file when your package manager is PNPM.
common/config/rush/yarn.lockThe shrinkwrap file when your package manager is Yarn.
common/config/rush/browser-approved-packages.jsonUsed by the approvedPackagesPolicy setting from rush.json
common/config/rush/nonbrowser-approved-packages.jsonUsed by the approvedPackagesPolicy setting from rush.json
common/config/rush/pnpm-config.jsonConfiguration specific to the PNPM package manager
common/config/rush/version-policies.jsonDefines the rush version and rush publish workflows.

Standard Rush folders​

Folder pathWhat it does
common/autoinstallers/...Autoinstaller projects are created under this folder
common/changes/...Stores change files created by the rush change command and consumed by the rush version command.
common/deploy/...The rush init-deploy creates deployment configurations under this folder.
common/git-hooks/...Rush's git hook scripts are defined here
common/pnpm-patches/...The rush-pnpm commit-patch command stores package patch files under this folder
common/scripts/install-run-rush.jsCI bootstrap script for invoking rush. The rush update generates this file, which should be committed to Git. See Enabling CI builds for details.
common/scripts/install-run-rush-pnpm.jsCI bootstrap script for invoking rush-pnpm.
common/scripts/install-run-rushx.jsCI bootstrap script for invoking rushx.
common/scripts/install-run.jsCI bootstrap script for invoking arbitrary NPM packages.

Temporary files created by Rush​

Folder pathWhat it does
common/temp/build-cache/...Default storage location for Rush's Build cache
common/temp/install-run/...Storage for the install-run.js and install-run-rush.js scripts. See Enabling CI builds.
common/temp/node_modules/...The installed packages. This is a plain old npm install output, with no symlinks in this tree.
common/temp/npm-cache/...A local NPM cache will be created here. Rush does not use the global NPM cache due to its concurrency problems.
common/temp/npm-local/...If the NPM package manager is selected, this is a symlink to Rush's global install of the version specified in rush.json.
common/temp/npm-tmp/...Temporary files created by NPM during installation.
common/temp/patches/...The rush-pnpm patch command creates patch files under this temporary folder (which rush-pnpm commit-patch will copy to common/pnpm-patches)
common/temp/pnpm-local/...If the PNPM package manager is selected, this is a symlink to Rush's global install of the version specified in rush.json.
common/temp/pnpm-store/...If the PNPM package manager is selected, this is the default location of the PNPM store. (It can be redirected using the RUSH_PNPM_STORE_PATH environment variable.)
common/temp/projects/...Synthetic projects referenced by common/temp/package.json.
common/temp/rush-recycler/...Used to speed up recursive deletes.
common/temp/telemetry/...Stores telemetry output saved by Rush when telemetryEnabled=true in rush.json
common/temp/yarn-local/...If the Yarn package manager is selected, this is a symlink to Rush's global install of the version specified in rush.json.
common/temp/last-install.flagDon't worry about this file. It tracks the timestamp of the last successful rush install.
common/temp/package.jsonThe common package definition.
common/temp/repo-state.jsonGenerated by the preventManualShrinkwrapChanges setting from pnpm-config.json
common/temp/rush-link.jsonDon't worry about this file. It is created whenever you run rush link, and read by later commands such as "rush build".
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/advanced/watch_mode/index.html b/pages/advanced/watch_mode/index.html index 17b202ee..294d36a3 100644 --- a/pages/advanced/watch_mode/index.html +++ b/pages/advanced/watch_mode/index.html @@ -6,7 +6,7 @@ Using watch mode | Rush - + @@ -40,7 +40,7 @@ helpful:

  • @telia/rush-select is an interactive dashboard for monitoring Rush projects and selecting what to rebuild.

  • rush-dev-watcher is a simple but useful script from Daniel Imfeld that performs an initial build and then launches multiple watchers.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/best_practices/change_logs/index.html b/pages/best_practices/change_logs/index.html index 5ecbf69e..742ef990 100644 --- a/pages/best_practices/change_logs/index.html +++ b/pages/best_practices/change_logs/index.html @@ -6,13 +6,13 @@ Authoring change logs | Rush - +
Rush StackShopBlogEvents

Authoring change logs

When publishing an NPM package, it is common practice to include a CHANGELOG.md file to inform your consumers about bug fixes, new features, and changed or removed functionality. Rush automates this using the rush change command. This command should be run once you are ready to merge your PR, after all your changes have been committed to the branch. It analyzes the changes in your branch and (when necessary) prompts you to write human-readable descriptions of your changes.

The way in which you phrase your description is important. You don't want to be overly concise or specific, you don't want to reveal private information, and you want the description to be as helpful as possible. We recommend to err on the side of readability. Ask yourself:

  • "How is my change relevant to a third-party developer?"
  • "Could it break them?"
  • "Does it fix a bug that's been annoying them?"
  • "Is it a new feature for them to try?"

In some workflows, a human editor will review the change logs before they are published, however everyone should do their best to ensure that the content is clear and professional.

  • Use the present simple tense using the imperative ("command") mood.

  • Write from the perspective of an external audience who may be unfamiliar with implementation details of your package

  • Focus on scenario outcomes ("Searching now supports wildcards") instead of code changes ("Added regular expression support to SearchHelper class")

  • Start with a verb. These verbs are recommended:

    • Add - when you introduce or expose a new feature, property, class, UI, etc.
    • Remove - when you fully removed something and it can no longer be used.
    • Deprecate - when you plan on removing something, but it is still accessible.
    • Fix an issue with/where... - when you fixed a bug.
    • Improve - when you made an existing thing better.
    • Update - when you refresh something, but don't necessarily make it better.
    • Upgrade - when upgrading the version of a dependency.
    • Initial/Beta release of ... - when releasing a brand-new feature.

  • Don't use the word bug. Use issue instead.

  • Don't use shorthand words or acronyms, unless they are widely recognized (e.g. "HTTP")

  • Use correct spelling and grammar. The CHANGELOG.md is part of your package's published documentation.

  • When referring to public API changes, use the () suffix to indicate a function name, e.g. setSomethingOnWebpart()

  • When referring to public API changes, use backticks (` `) around class and property names.

  • When documenting an upgrade, indicate the old and new version. For example: "Upgraded widget-library from 1.0.2 to 2.0.1"

  • If fixing a GitHub issue, consider adding the issue URL in parentheses.

  • Don't add a trailing period unless you have two or more sentences.

Example Change Log Messages​

Here are some hypothetical change log messages that might be provided to rush change:

  • Add "buttonColor" to the button manifest schema
  • Remove support for older mobile web browsers as described in the README.md
  • Deprecate the doSomething() API function. Use doSomethingBetter() instead.
  • Fix an issue where "ExampleWidget" API did not handle dates correctly
  • Improve the diagnostic logging when running in advanced mode
  • Upgrade from React 15 to React 16
  • Initial release of the flexible panels feature
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush-pnpm/index.html b/pages/commands/rush-pnpm/index.html index e058569b..f3dd2b1b 100644 --- a/pages/commands/rush-pnpm/index.html +++ b/pages/commands/rush-pnpm/index.html @@ -6,7 +6,7 @@ rush-pnpm | Rush - + @@ -18,7 +18,7 @@ incompatible with Rush's enhancements.

To avoid these problems, use rush-pnpm in your Rush repo wherever you would normally use pnpm. The @microsoft/rush NPM package includes the rush-pnpm binary, which is a drop-in replacement for the pnpm command. It provides the following features:

  • sets up the correct context/environment so that PNPM commands work correctly
  • reports an error for operations that are known to be incompatible with Rush
  • reports a warning for operations that may be unsafe with Rush
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_add/index.html b/pages/commands/rush_add/index.html index fd567fbe..b054e109 100644 --- a/pages/commands/rush_add/index.html +++ b/pages/commands/rush_add/index.html @@ -6,13 +6,13 @@ rush add | Rush - +
Rush StackShopBlogEvents

rush add

usage: rush add [-h] -p PACKAGE [--exact] [--caret] [--dev] [-m] [-s] [--all]

Adds specified package(s) to the dependencies of the current project (as
determined by the current working directory) and then runs "rush update". If
no version is specified, a version will be automatically detected (typically
either the latest version or a version that won't break the
"ensureConsistentVersions" policy). If a version range (or a workspace range)
is specified, the latest version in the range will be used. The version will
be automatically prepended with a tilde, unless the "--exact" or "--caret"
flags are used. The "--make-consistent" flag can be used to update all
packages with the dependency.

Optional arguments:
  -h, --help            Show this help message and exit.
  -p PACKAGE, --package PACKAGE
                        (Required) The name of the package which should be
                        added as a dependency. A SemVer version specifier can
                        be appended after an "@" sign. WARNING: Symbol
                        characters are usually interpreted by your shell, so
                        it's recommended to use quotes. For example, write
                        "rush add --package "example@^1.2.3"" instead of
                        "rush add --package example@^1.2.3". To add multiple
                        packages, write "rush add --package foo --package
                        bar".
  --exact               If specified, the SemVer specifier added to the
                        package.json will be an exact version (e.g. without
                        tilde or caret).
  --caret               If specified, the SemVer specifier added to the
                        package.json will be a prepended with a "caret"
                        specifier ("^").
  --dev                 If specified, the package will be added to the
                        "devDependencies" section of the package.json
  -m, --make-consistent
                        If specified, other packages with this dependency
                        will have their package.json files updated to use the
                        same version of the dependency.
  -s, --skip-update     If specified, the "rush update" command will not be
                        run after updating the package.json files.
  --all                 If specified, the dependency will be added to all
                        projects.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_build/index.html b/pages/commands/rush_build/index.html index 71639904..ed35b993 100644 --- a/pages/commands/rush_build/index.html +++ b/pages/commands/rush_build/index.html @@ -6,13 +6,13 @@ rush build | Rush - +
Rush StackShopBlogEvents

rush build

usage: rush build [-h] [-p COUNT] [--timeline] [-t PROJECT] [-T PROJECT]
                  [-f PROJECT] [-o PROJECT] [-i PROJECT] [-I PROJECT]
                  [--to-version-policy VERSION_POLICY_NAME]
                  [--from-version-policy VERSION_POLICY_NAME] [-v] [-c]
                  [--ignore-hooks]


This command is similar to "rush rebuild", except that "rush build" performs
an incremental build. In other words, it only builds projects whose source
files have changed since the last successful build. The analysis requires a
Git working tree, and only considers source files that are tracked by Git and
whose path is under the project folder. (For more details about this
algorithm, see the documentation for the "package-deps-hash" NPM package.)
The incremental build state is tracked in a per-project folder called ".
rush/temp" which should NOT be added to Git. The build command is tracked by
the "arguments" field in the "package-deps_build.json" file contained
therein; a full rebuild is forced whenever the command has changed (e.g.
"--production" or not).

Optional arguments:
  -h, --help            Show this help message and exit.
  -p COUNT, --parallelism COUNT
                        Specifies the maximum number of concurrent processes
                        to launch during a build. The COUNT should be a
                        positive integer, a percentage value (eg. "50%") or
                        the word "max" to specify a count that is equal to
                        the number of CPU cores. If this parameter is omitted,
                         then the default value depends on the operating
                        system and number of CPU cores. This parameter may
                        alternatively be specified via the RUSH_PARALLELISM
                        environment variable.
  --timeline            After the build is complete, print additional
                        statistics and CPU usage information, including an
                        ASCII chart of the start and stop times for each
                        operation.
  -t PROJECT, --to PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to" parameter expands
                        this selection to include PROJECT and all its
                        dependencies. "." can be used as shorthand for the
                        project in the current working directory. For details,
                         refer to the website article "Selecting subsets of
                        projects".
  -T PROJECT, --to-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to-except" parameter
                        expands this selection to include all dependencies of
                        PROJECT, but not PROJECT itself. "." can be used as
                        shorthand for the project in the current working
                        directory. For details, refer to the website article
                        "Selecting subsets of projects".
  -f PROJECT, --from PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--from" parameter expands
                        this selection to include PROJECT and all projects
                        that depend on it, plus all dependencies of this set.
                        "." can be used as shorthand for the project in the
                        current working directory. For details, refer to the
                        website article "Selecting subsets of projects".
  -o PROJECT, --only PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--only" parameter expands
                        this selection to include PROJECT; its dependencies
                        are not added. "." can be used as shorthand for the
                        project in the current working directory. Note that
                        this parameter is "unsafe" as it may produce a
                        selection that excludes some dependencies. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  -i PROJECT, --impacted-by PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by" parameter
                        expands this selection to include PROJECT and any
                        projects that depend on PROJECT (and thus might be
                        broken by changes to PROJECT). "." can be used as
                        shorthand for the project in the current working
                        directory. Note that this parameter is "unsafe" as it
                        may produce a selection that excludes some
                        dependencies. For details, refer to the website
                        article "Selecting subsets of projects".
  -I PROJECT, --impacted-by-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by-except"
                        parameter works the same as "--impacted-by" except
                        that PROJECT itself is not added to the selection. ".
                        " can be used as shorthand for the project in the
                        current working directory. Note that this parameter
                        is "unsafe" as it may produce a selection that
                        excludes some dependencies. For details, refer to the
                        website article "Selecting subsets of projects".
  --to-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--to-version-policy"
                        parameter is equivalent to specifying "--to" for each
                        of the projects belonging to VERSION_POLICY_NAME. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  --from-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--from-version-policy"
                        parameter is equivalent to specifying "--from" for
                        each of the projects belonging to VERSION_POLICY_NAME.
                         For details, refer to the website article "Selecting
                        subsets of projects".
  -v, --verbose         Display the logs during the build, rather than just
                        displaying the build status summary
  -c, --changed-projects-only
                        Normally the incremental build logic will rebuild
                        changed projects as well as any projects that
                        directly or indirectly depend on a changed project.
                        Specify "--changed-projects-only" to ignore dependent
                        projects, only rebuilding those projects whose files
                        were changed. Note that this parameter is "unsafe";
                        it is up to the developer to ensure that the ignored
                        projects are okay to ignore.
  --ignore-hooks        Skips execution of the "eventHooks" scripts defined
                        in rush.json. Make sure you know what you are
                        skipping.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_change/index.html b/pages/commands/rush_change/index.html index d9b8c8e9..ea273a67 100644 --- a/pages/commands/rush_change/index.html +++ b/pages/commands/rush_change/index.html @@ -6,13 +6,13 @@ rush change | Rush - +
Rush StackShopBlogEvents

rush change

usage: rush change [-h] [-v] [--no-fetch] [-b BRANCH] [--overwrite]
                   [--email EMAIL] [--bulk] [--message MESSAGE]
                   [--bump-type {major,minor,patch,none}]


Asks a series of questions and then generates a <branchname>-<timestamp>.json
file in the common folder. The `publish` command will consume these files and
perform the proper version bumps. Note these changes will eventually be
published in a changelog.md file in each package. The possible types of
changes are: MAJOR - these are breaking changes that are not backwards
compatible. Examples are: renaming a public class, adding/removing a
non-optional parameter from a public API, or renaming an variable or function
that is exported. MINOR - these are changes that are backwards compatible
(but not forwards compatible). Examples are: adding a new public API or
adding an optional parameter to a public API PATCH - these are changes that
are backwards and forwards compatible. Examples are: Modifying a private API
or fixing a bug in the logic of how an existing API works. NONE - these are
changes that are backwards and forwards compatible and don't require an
immediate release. Examples are: Modifying dev tooling configuration like
eslint. HOTFIX (EXPERIMENTAL) - these are changes that are hotfixes targeting
a specific older version of the package. When a hotfix change is added, other
changes will not be able to increment the version number. Enable this feature
by setting 'hotfixChangeEnabled' in your rush.json.

Optional arguments:
  -h, --help            Show this help message and exit.
  -v, --verify          Verify the change file has been generated and that it
                        is a valid JSON file
  --no-fetch            Skips fetching the baseline branch before running
                        "git diff" to detect changes.
  -b BRANCH, --target-branch BRANCH
                        If this parameter is specified, compare the checked
                        out branch with the specified branch to determine
                        which projects were changed. If this parameter is not
                        specified, the checked out branch is compared against
                        the "main" branch.
  --overwrite           If a changefile already exists, overwrite without
                        prompting (or erroring in --bulk mode).
  --email EMAIL         The email address to use in changefiles. If this
                        parameter is not provided, the email address will be
                        detected or prompted for in interactive mode.
  --bulk                If this flag is specified, apply the same change
                        message and bump type to all changed projects. The
                        --message and the --bump-type parameters must be
                        specified if the --bulk parameter is specified
  --message MESSAGE     The message to apply to all changed projects if the
                        --bulk flag is provided.
  --bump-type {major,minor,patch,none}
                        The bump type to apply to all changed projects if the
                        --bulk flag is provided.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_check/index.html b/pages/commands/rush_check/index.html index 4e418785..b06c254a 100644 --- a/pages/commands/rush_check/index.html +++ b/pages/commands/rush_check/index.html @@ -6,13 +6,13 @@ rush check | Rush - +
Rush StackShopBlogEvents

rush check

usage: rush check [-h] [--variant VARIANT] [--json] [--verbose]

Checks each project's package.json files and ensures that all dependencies
are of the same version throughout the repository.

Optional arguments:
  -h, --help         Show this help message and exit.
  --variant VARIANT  Run command using a variant installation configuration.
                     This parameter may alternatively be specified via the
                     RUSH_VARIANT environment variable.
  --json             If this flag is specified, output will be in JSON format.
  --verbose          If this flag is specified, long lists of package names
                     will not be truncated. This has no effect if the --json
                     flag is also specified.
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_deploy/index.html b/pages/commands/rush_deploy/index.html index d7d4c15f..3def67d1 100644 --- a/pages/commands/rush_deploy/index.html +++ b/pages/commands/rush_deploy/index.html @@ -6,13 +6,13 @@ rush deploy | Rush - +
Rush StackShopBlogEvents

rush deploy

usage: rush deploy [-h] [-p PROJECT_NAME] [-s SCENARIO_NAME] [--overwrite]
                   [-t PATH] [--create-archive ARCHIVE_PATH]


After building the repo, "rush deploy" can be used to prepare a deployment by
copying a subset of Rush projects and their dependencies to a target folder,
which can then be uploaded to a production server. The "rush deploy" behavior
is specified by a scenario config file that must be created first, using the
"rush init-deploy" command.

Optional arguments:
  -h, --help            Show this help message and exit.
  -p PROJECT_NAME, --project PROJECT_NAME
                        Specifies the name of the main Rush project to be
                        deployed. It must appear in the
                        "deploymentProjectNames" setting in the deployment
                        config file.
  -s SCENARIO_NAME, --scenario SCENARIO_NAME
                        By default, the deployment configuration is specified
                        in "common/config/rush/deploy.json". You can use
                        "--scenario" to specify an alternate name. The name
                        must be lowercase and separated by dashes. For
                        example, if SCENARIO_NAME is "web", then the config
                        file would be "common/config/rush/deploy-web.json".
  --overwrite           By default, deployment will fail if the target folder
                        is not empty. SPECIFYING THIS FLAG WILL RECURSIVELY
                        DELETE EXISTING CONTENTS OF THE TARGET FOLDER.
  -t PATH, --target-folder PATH
                        By default, files are deployed to the "common/deploy"
                        folder inside the Rush repo. Use this parameter to
                        specify a different location. WARNING: USE CAUTION
                        WHEN COMBINING WITH "--overwrite". This parameter may
                        alternatively be specified via the
                        RUSH_DEPLOY_TARGET_FOLDER environment variable.
  --create-archive ARCHIVE_PATH
                        If specified, after the deployment has been prepared,
                        "rush deploy" will create an archive containing the
                        contents of the target folder. The newly created
                        archive file will be placed according to the
                        designated path, relative to the target folder.
                        Supported file extensions: .zip

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_init-autoinstaller/index.html b/pages/commands/rush_init-autoinstaller/index.html index dec0b18e..a5788e05 100644 --- a/pages/commands/rush_init-autoinstaller/index.html +++ b/pages/commands/rush_init-autoinstaller/index.html @@ -6,13 +6,13 @@ rush init-autoinstaller | Rush - +
Rush StackShopBlogEvents

rush init-autoinstaller

usage: rush init-autoinstaller [-h] --name AUTOINSTALLER_NAME

Use this command to initialize a new autoinstaller folder. Autoinstallers
provide a way to manage a set of related dependencies that are used for
scripting scenarios outside of the usual "rush install" context. See the
command-line.json documentation for an example.

Optional arguments:
  -h, --help            Show this help message and exit.
  --name AUTOINSTALLER_NAME
                        Specifies the name of the autoinstaller folder, which
                        must conform to the naming rules for NPM packages.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_init-deploy/index.html b/pages/commands/rush_init-deploy/index.html index c882921f..2df51a6d 100644 --- a/pages/commands/rush_init-deploy/index.html +++ b/pages/commands/rush_init-deploy/index.html @@ -6,13 +6,13 @@ rush init-deploy | Rush - +
Rush StackShopBlogEvents

rush init-deploy

usage: rush init-deploy [-h] -p PROJECT_NAME [-s SCENARIO]

Use this command to initialize a new scenario config file for use with "rush
deploy". The default filename is common/config/rush/deploy.json. However, if
you need to manage multiple deployments with different settings, you can use
use "--scenario" to create additional config files.

Optional arguments:
  -h, --help            Show this help message and exit.
  -p PROJECT_NAME, --project PROJECT_NAME
                        Specifies the name of the main Rush project to be
                        deployed in this scenario. It will be added to the
                        "deploymentProjectNames" setting.
  -s SCENARIO, --scenario SCENARIO
                        By default, the deployment configuration will be
                        written to "common/config/rush/deploy.json". You can
                        use "--scenario" to specify an alternate name. The
                        name must be lowercase and separated by dashes. For
                        example, if the name is "web", then the config file
                        would be "common/config/rush/deploy-web.json".

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_init/index.html b/pages/commands/rush_init/index.html index 817f6b62..b3067815 100644 --- a/pages/commands/rush_init/index.html +++ b/pages/commands/rush_init/index.html @@ -6,13 +6,13 @@ rush init | Rush - +
Rush StackShopBlogEvents

rush init

usage: rush init [-h] [--overwrite-existing] [--rush-example-repo]

When invoked in an empty folder, this command provisions a standard set of
config file templates to start managing projects using Rush.

Optional arguments:
  -h, --help            Show this help message and exit.
  --overwrite-existing  By default "rush init" will not overwrite existing
                        config files. Specify this switch to override that.
                        This can be useful when upgrading your repo to a
                        newer release of Rush. WARNING: USE WITH CARE!
  --rush-example-repo   When copying the template config files, this
                        uncomments fragments that are used by the
                        "rush-example" GitHub repo, which is a sample
                        monorepo that illustrates many Rush features. This
                        option is primarily intended for maintaining that
                        example.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_install/index.html b/pages/commands/rush_install/index.html index 82aea3e3..d6c100ff 100644 --- a/pages/commands/rush_install/index.html +++ b/pages/commands/rush_install/index.html @@ -6,13 +6,13 @@ rush install | Rush - +
Rush StackShopBlogEvents

rush install

usage: rush install [-h] [-p] [--bypass-policy] [--no-link]
                    [--network-concurrency COUNT] [--debug-package-manager]
                    [--max-install-attempts NUMBER] [--ignore-hooks]
                    [--variant VARIANT] [-t PROJECT] [-T PROJECT] [-f PROJECT]
                    [-o PROJECT] [-i PROJECT] [-I PROJECT]
                    [--to-version-policy VERSION_POLICY_NAME]
                    [--from-version-policy VERSION_POLICY_NAME] [--check-only]


The "rush install" command installs package dependencies for all your
projects, based on the shrinkwrap file that is created/updated using "rush
update". (This "shrinkwrap" file stores a central inventory of all
dependencies and versions for projects in your repo. It is found in the
"common/config/rush" folder.) If the shrinkwrap file is missing or outdated
(e.g. because project package.json files have changed), "rush install" will
fail and tell you to run "rush update" instead. This read-only nature is the
main feature: Continuous integration builds should use "rush install" instead
of "rush update" to catch developers who forgot to commit their shrinkwrap
changes. Cautious people can also use "rush install" if they want to avoid
accidentally updating their shrinkwrap file.

Optional arguments:
  -h, --help            Show this help message and exit.
  -p, --purge           Perform "rush purge" before starting the installation
  --bypass-policy       Overrides enforcement of the "gitPolicy" rules from
                        rush.json (use honorably!)
  --no-link             If "--no-link" is specified, then project symlinks
                        will NOT be created after the installation completes.
                        You will need to run "rush link" manually. This flag
                        is useful for automated builds that want to report
                        stages individually or perform extra operations in
                        between the two stages. This flag is not supported
                        when using workspaces.
  --network-concurrency COUNT
                        If specified, limits the maximum number of concurrent
                        network requests. This is useful when troubleshooting
                        network failures.
  --debug-package-manager
                        Activates verbose logging for the package manager.
                        You will probably want to pipe the output of Rush to
                        a file when using this command.
  --max-install-attempts NUMBER
                        Overrides the default maximum number of install
                        attempts. The default value is 1.
  --ignore-hooks        Skips execution of the "eventHooks" scripts defined
                        in rush.json. Make sure you know what you are
                        skipping.
  --variant VARIANT     Run command using a variant installation
                        configuration. This parameter may alternatively be
                        specified via the RUSH_VARIANT environment variable.
  -t PROJECT, --to PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to" parameter expands
                        this selection to include PROJECT and all its
                        dependencies. "." can be used as shorthand for the
                        project in the current working directory. For details,
                         refer to the website article "Selecting subsets of
                        projects".
  -T PROJECT, --to-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to-except" parameter
                        expands this selection to include all dependencies of
                        PROJECT, but not PROJECT itself. "." can be used as
                        shorthand for the project in the current working
                        directory. For details, refer to the website article
                        "Selecting subsets of projects".
  -f PROJECT, --from PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--from" parameter expands
                        this selection to include PROJECT and all projects
                        that depend on it, plus all dependencies of this set.
                        "." can be used as shorthand for the project in the
                        current working directory. For details, refer to the
                        website article "Selecting subsets of projects".
  -o PROJECT, --only PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--only" parameter expands
                        this selection to include PROJECT; its dependencies
                        are not added. "." can be used as shorthand for the
                        project in the current working directory. Note that
                        this parameter is "unsafe" as it may produce a
                        selection that excludes some dependencies. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  -i PROJECT, --impacted-by PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by" parameter
                        expands this selection to include PROJECT and any
                        projects that depend on PROJECT (and thus might be
                        broken by changes to PROJECT). "." can be used as
                        shorthand for the project in the current working
                        directory. Note that this parameter is "unsafe" as it
                        may produce a selection that excludes some
                        dependencies. For details, refer to the website
                        article "Selecting subsets of projects".
  -I PROJECT, --impacted-by-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by-except"
                        parameter works the same as "--impacted-by" except
                        that PROJECT itself is not added to the selection. ".
                        " can be used as shorthand for the project in the
                        current working directory. Note that this parameter
                        is "unsafe" as it may produce a selection that
                        excludes some dependencies. For details, refer to the
                        website article "Selecting subsets of projects".
  --to-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--to-version-policy"
                        parameter is equivalent to specifying "--to" for each
                        of the projects belonging to VERSION_POLICY_NAME. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  --from-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--from-version-policy"
                        parameter is equivalent to specifying "--from" for
                        each of the projects belonging to VERSION_POLICY_NAME.
                         For details, refer to the website article "Selecting
                        subsets of projects".
  --check-only          Only check the validity of the shrinkwrap file
                        without performing an install.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_link/index.html b/pages/commands/rush_link/index.html index 14c6a9a2..0e011fbd 100644 --- a/pages/commands/rush_link/index.html +++ b/pages/commands/rush_link/index.html @@ -6,13 +6,13 @@ rush link | Rush - +
Rush StackShopBlogEvents

rush link

usage: rush link [-h] [-f]

Create node_modules symlinks for all projects. This operation is normally
performed automatically as part of "rush install" or "rush update". You
should only need to use "rush link" if you performed "rush unlink" for some
reason, or if you specified the "--no-link" option for "rush install" or
"rush update".

Optional arguments:
  -h, --help   Show this help message and exit.
  -f, --force  Deletes and recreates all links, even if the filesystem state
               seems to indicate that this is unnecessary.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_list/index.html b/pages/commands/rush_list/index.html index ebecdf9d..39b39c0b 100644 --- a/pages/commands/rush_list/index.html +++ b/pages/commands/rush_list/index.html @@ -6,13 +6,13 @@ rush list | Rush - +
Rush StackShopBlogEvents

rush list

usage: rush list [-h] [-v] [-p] [--full-path] [--detailed] [--json]
                 [-t PROJECT] [-T PROJECT] [-f PROJECT] [-o PROJECT]
                 [-i PROJECT] [-I PROJECT]
                 [--to-version-policy VERSION_POLICY_NAME]
                 [--from-version-policy VERSION_POLICY_NAME]


List package names, and optionally version (--version) and path (--path) or
full path (--full-path), for projects in the current rush config.

Optional arguments:
  -h, --help            Show this help message and exit.
  -v, --version         If this flag is specified, the project version will
                        be displayed in a column along with the package name.
  -p, --path            If this flag is specified, the project path will be
                        displayed in a column along with the package name.
  --full-path           If this flag is specified, the project full path will
                        be displayed in a column along with the package name.
  --detailed            For the non --json view, if this flag is specified,
                        include path (-p), version (-v) columns along with
                        the project's applicable: versionPolicy,
                        versionPolicyName, shouldPublish, reviewPolicy, and
                        tags fields.
  --json                If this flag is specified, output will be in JSON
                        format.
  -t PROJECT, --to PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to" parameter expands
                        this selection to include PROJECT and all its
                        dependencies. "." can be used as shorthand for the
                        project in the current working directory. For details,
                         refer to the website article "Selecting subsets of
                        projects".
  -T PROJECT, --to-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to-except" parameter
                        expands this selection to include all dependencies of
                        PROJECT, but not PROJECT itself. "." can be used as
                        shorthand for the project in the current working
                        directory. For details, refer to the website article
                        "Selecting subsets of projects".
  -f PROJECT, --from PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--from" parameter expands
                        this selection to include PROJECT and all projects
                        that depend on it, plus all dependencies of this set.
                        "." can be used as shorthand for the project in the
                        current working directory. For details, refer to the
                        website article "Selecting subsets of projects".
  -o PROJECT, --only PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--only" parameter expands
                        this selection to include PROJECT; its dependencies
                        are not added. "." can be used as shorthand for the
                        project in the current working directory. Note that
                        this parameter is "unsafe" as it may produce a
                        selection that excludes some dependencies. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  -i PROJECT, --impacted-by PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by" parameter
                        expands this selection to include PROJECT and any
                        projects that depend on PROJECT (and thus might be
                        broken by changes to PROJECT). "." can be used as
                        shorthand for the project in the current working
                        directory. Note that this parameter is "unsafe" as it
                        may produce a selection that excludes some
                        dependencies. For details, refer to the website
                        article "Selecting subsets of projects".
  -I PROJECT, --impacted-by-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by-except"
                        parameter works the same as "--impacted-by" except
                        that PROJECT itself is not added to the selection. ".
                        " can be used as shorthand for the project in the
                        current working directory. Note that this parameter
                        is "unsafe" as it may produce a selection that
                        excludes some dependencies. For details, refer to the
                        website article "Selecting subsets of projects".
  --to-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--to-version-policy"
                        parameter is equivalent to specifying "--to" for each
                        of the projects belonging to VERSION_POLICY_NAME. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  --from-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--from-version-policy"
                        parameter is equivalent to specifying "--from" for
                        each of the projects belonging to VERSION_POLICY_NAME.
                         For details, refer to the website article "Selecting
                        subsets of projects".
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_publish/index.html b/pages/commands/rush_publish/index.html index ddfa3ea2..2b61121d 100644 --- a/pages/commands/rush_publish/index.html +++ b/pages/commands/rush_publish/index.html @@ -6,13 +6,13 @@ rush publish | Rush - +
Rush StackShopBlogEvents

rush publish

usage: rush publish [-h] [-a] [-b BRANCH] [-p] [--add-commit-details]
                    [--regenerate-changelogs] [-r REGISTRY] [-n TOKEN]
                    [-t TAG] [--set-access-level {public,restricted}] [--pack]
                    [--release-folder FOLDER] [--include-all]
                    [--version-policy POLICY] [--prerelease-name NAME]
                    [--partial-prerelease] [--suffix SUFFIX] [--force]
                    [--apply-git-tags-on-pack] [-c COMMIT_ID]
                    [--ignore-git-hooks]


Reads and processes package publishing change requests generated by "rush
change". This will perform a read-only operation by default, printing
operations executed to the console. To commit changes and publish packages,
you must use the --commit flag and/or the --publish flag.

Optional arguments:
  -h, --help            Show this help message and exit.
  -a, --apply           If this flag is specified, the change requests will
                        be applied to package.json files.
  -b BRANCH, --target-branch BRANCH
                        If this flag is specified, applied changes and
                        deleted change requests will be committed and merged
                        into the target branch.
  -p, --publish         If this flag is specified, applied changes will be
                        published to the NPM registry.
  --add-commit-details  Adds commit author and hash to the changelog.json
                        files for each change.
  --regenerate-changelogs
                        Regenerates all changelog files based on the current
                        JSON content.
  -r REGISTRY, --registry REGISTRY
                        Publishes to a specified NPM registry. If this is
                        specified, it will prevent the current commit will
                        not be tagged.
  -n TOKEN, --npm-auth-token TOKEN
                        (DEPRECATED) Specifies the authentication token to
                        use during publishing. This parameter is deprecated
                        because command line parameters may be readable by
                        unrelated processes on a lab machine. Instead, a
                        safer practice is to pass the token via an
                        environment variable and reference it from your
                        common/config/rush/.npmrc-publish file.
  -t TAG, --tag TAG     The tag option to pass to npm publish. By default NPM
                        will publish using the 'latest' tag, even if the
                        package is older than the current latest, so in
                        publishing workflows for older releases, providing a
                        tag is important. When hotfix changes are made, this
                        parameter defaults to 'hotfix'.
  --set-access-level {public,restricted}
                        By default, when Rush invokes "npm publish" it will
                        publish scoped packages with an access level of
                        "restricted". Scoped packages can be published with
                        an access level of "public" by specifying that value
                        for this flag with the initial publication. NPM
                        always publishes unscoped packages with an access
                        level of "public". For more information, see the NPM
                        documentation for the "--access" option of "npm
                        publish".
  --pack                Packs projects into tarballs instead of publishing to
                        npm repository. It can only be used when
                        --include-all is specified. If this flag is specified,
                         NPM registry related parameters will be ignored.
  --release-folder FOLDER
                        This parameter is used with --pack parameter to
                        provide customized location for the tarballs instead
                        of the default value.
  --include-all         If this flag is specified, all packages with
                        shouldPublish=true in rush.json or with a specified
                        version policy will be published if their version is
                        newer than published version.
  --version-policy POLICY
                        Version policy name. Only projects with this version
                        policy will be published if used with --include-all.
  --prerelease-name NAME
                        Bump up to a prerelease version with the provided
                        prerelease name. Cannot be used with --suffix
  --partial-prerelease  Used with --prerelease-name. Only bump packages to a
                        prerelease version if they have changes.
  --suffix SUFFIX       Append a suffix to all changed versions. Cannot be
                        used with --prerelease-name.
  --force               If this flag is specified with --publish, packages
                        will be published with --force on npm
  --apply-git-tags-on-pack
                        If specified with --publish and --pack, git tags will
                        be applied for packages as if a publish was being run
                        without --pack.
  -c COMMIT_ID, --commit COMMIT_ID
                        Used in conjunction with git tagging -- apply git
                        tags at the commit hash specified. If not provided,
                        the current HEAD will be tagged.
  --ignore-git-hooks    Skips execution of all git hooks. Make sure you know
                        what you are skipping.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_purge/index.html b/pages/commands/rush_purge/index.html index 0c696329..8674529d 100644 --- a/pages/commands/rush_purge/index.html +++ b/pages/commands/rush_purge/index.html @@ -6,13 +6,13 @@ rush purge | Rush - +
Rush StackShopBlogEvents

rush purge

usage: rush purge [-h] [--unsafe]

The "rush purge" command is used to delete temporary files created by Rush.
This is useful if you are having problems and suspect that cache files may be
corrupt.

Optional arguments:
  -h, --help  Show this help message and exit.
  --unsafe    (UNSAFE!) Also delete shared files such as the package manager
              instances stored in the ".rush" folder in the user's home
              directory. This is a more aggressive fix that is NOT SAFE to
              run in a live environment because it will cause other
              concurrent Rush processes to fail.
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_rebuild/index.html b/pages/commands/rush_rebuild/index.html index f6de1121..eb22937f 100644 --- a/pages/commands/rush_rebuild/index.html +++ b/pages/commands/rush_rebuild/index.html @@ -6,13 +6,13 @@ rush rebuild | Rush - +
Rush StackShopBlogEvents

rush rebuild

usage: rush rebuild [-h] [-p COUNT] [--timeline] [-t PROJECT] [-T PROJECT]
                    [-f PROJECT] [-o PROJECT] [-i PROJECT] [-I PROJECT]
                    [--to-version-policy VERSION_POLICY_NAME]
                    [--from-version-policy VERSION_POLICY_NAME] [-v]
                    [--ignore-hooks]


This command assumes that the package.json file for each project contains a
"scripts" entry for "npm run build" that performs a full clean build. Rush
invokes this script to build each project that is registered in rush.json.
Projects are built in parallel where possible, but always respecting the
dependency graph for locally linked projects. The number of simultaneous
processes will be based on the number of machine cores unless overridden by
the --parallelism flag. (For an incremental build, see "rush build" instead
of "rush rebuild".)

Optional arguments:
  -h, --help            Show this help message and exit.
  -p COUNT, --parallelism COUNT
                        Specifies the maximum number of concurrent processes
                        to launch during a build. The COUNT should be a
                        positive integer, a percentage value (eg. "50%") or
                        the word "max" to specify a count that is equal to
                        the number of CPU cores. If this parameter is omitted,
                         then the default value depends on the operating
                        system and number of CPU cores. This parameter may
                        alternatively be specified via the RUSH_PARALLELISM
                        environment variable.
  --timeline            After the build is complete, print additional
                        statistics and CPU usage information, including an
                        ASCII chart of the start and stop times for each
                        operation.
  -t PROJECT, --to PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to" parameter expands
                        this selection to include PROJECT and all its
                        dependencies. "." can be used as shorthand for the
                        project in the current working directory. For details,
                         refer to the website article "Selecting subsets of
                        projects".
  -T PROJECT, --to-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--to-except" parameter
                        expands this selection to include all dependencies of
                        PROJECT, but not PROJECT itself. "." can be used as
                        shorthand for the project in the current working
                        directory. For details, refer to the website article
                        "Selecting subsets of projects".
  -f PROJECT, --from PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--from" parameter expands
                        this selection to include PROJECT and all projects
                        that depend on it, plus all dependencies of this set.
                        "." can be used as shorthand for the project in the
                        current working directory. For details, refer to the
                        website article "Selecting subsets of projects".
  -o PROJECT, --only PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--only" parameter expands
                        this selection to include PROJECT; its dependencies
                        are not added. "." can be used as shorthand for the
                        project in the current working directory. Note that
                        this parameter is "unsafe" as it may produce a
                        selection that excludes some dependencies. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  -i PROJECT, --impacted-by PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by" parameter
                        expands this selection to include PROJECT and any
                        projects that depend on PROJECT (and thus might be
                        broken by changes to PROJECT). "." can be used as
                        shorthand for the project in the current working
                        directory. Note that this parameter is "unsafe" as it
                        may produce a selection that excludes some
                        dependencies. For details, refer to the website
                        article "Selecting subsets of projects".
  -I PROJECT, --impacted-by-except PROJECT
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. Each "--impacted-by-except"
                        parameter works the same as "--impacted-by" except
                        that PROJECT itself is not added to the selection. ".
                        " can be used as shorthand for the project in the
                        current working directory. Note that this parameter
                        is "unsafe" as it may produce a selection that
                        excludes some dependencies. For details, refer to the
                        website article "Selecting subsets of projects".
  --to-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--to-version-policy"
                        parameter is equivalent to specifying "--to" for each
                        of the projects belonging to VERSION_POLICY_NAME. For
                        details, refer to the website article "Selecting
                        subsets of projects".
  --from-version-policy VERSION_POLICY_NAME
                        Normally all projects in the monorepo will be
                        processed; adding this parameter will instead select
                        a subset of projects. The "--from-version-policy"
                        parameter is equivalent to specifying "--from" for
                        each of the projects belonging to VERSION_POLICY_NAME.
                         For details, refer to the website article "Selecting
                        subsets of projects".
  -v, --verbose         Display the logs during the build, rather than just
                        displaying the build status summary
  --ignore-hooks        Skips execution of the "eventHooks" scripts defined
                        in rush.json. Make sure you know what you are
                        skipping.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_remove/index.html b/pages/commands/rush_remove/index.html index db00a8ab..96fa6597 100644 --- a/pages/commands/rush_remove/index.html +++ b/pages/commands/rush_remove/index.html @@ -6,13 +6,13 @@ rush remove | Rush - +
Rush StackShopBlogEvents

rush remove

usage: rush remove [-h] [-s] -p PACKAGE [--all]

Removes specified package(s) from the dependencies of the current project (as
determined by the current working directory) and then runs "rush update".

Optional arguments:
  -h, --help            Show this help message and exit.
  -s, --skip-update     If specified, the "rush update" command will not be
                        run after updating the package.json files.
  -p PACKAGE, --package PACKAGE
                        The name of the package which should be removed. To
                        remove multiple packages, run "rush remove --package
                        foo --package bar".
  --all                 If specified, the dependency will be removed from all
                        projects that declare it.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_scan/index.html b/pages/commands/rush_scan/index.html index 758d0345..a678a9f4 100644 --- a/pages/commands/rush_scan/index.html +++ b/pages/commands/rush_scan/index.html @@ -6,13 +6,13 @@ rush scan | Rush - +
Rush StackShopBlogEvents

rush scan

usage: rush scan [-h] [--json] [--all]

The Node.js module system allows a project to import NPM packages without
explicitly declaring them as dependencies in the package.json file. Such
"phantom dependencies" can cause problems. Rush and PNPM use symlinks
specifically to protect against phantom dependencies. These protections may
cause runtime errors for existing projects when they are first migrated into
a Rush monorepo. The "rush scan" command is a handy tool for fixing these
errors. It scans the "./src" and "./lib" folders for import syntaxes such as
"import __ from '__'", "require('__')", and "System.import('__'). It prints a
report of the referenced packages. This heuristic is not perfect, but it can
save a lot of time when migrating projects.

Optional arguments:
  -h, --help  Show this help message and exit.
  --json      If this flag is specified, output will be in JSON format.
  --all       If this flag is specified, output will list all detected
              dependencies.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_setup/index.html b/pages/commands/rush_setup/index.html index 7cc51c70..44f291ee 100644 --- a/pages/commands/rush_setup/index.html +++ b/pages/commands/rush_setup/index.html @@ -6,13 +6,13 @@ rush setup | Rush - +
Rush StackShopBlogEvents

rush setup

usage: rush setup [-h]

(EXPERIMENTAL) Invoke this command before working in a new repo to ensure
that any required prerequisites are installed and permissions are configured.
The initial implementation configures the NPM registry credentials. More
features will be added later.

Optional arguments:
  -h, --help  Show this help message and exit.
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_tab-complete/index.html b/pages/commands/rush_tab-complete/index.html index dacce442..c22ee656 100644 --- a/pages/commands/rush_tab-complete/index.html +++ b/pages/commands/rush_tab-complete/index.html @@ -6,13 +6,13 @@ rush tab-complete | Rush - +
Rush StackShopBlogEvents

rush tab-complete

usage: rush tab-complete [-h] [--word WORD] [--position INDEX]

Provides tab completion.

Optional arguments:
  -h, --help        Show this help message and exit.
  --word WORD       The word to complete. The default value is "".
  --position INDEX  The position in the word to be completed. The default
                    value is 0.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_unlink/index.html b/pages/commands/rush_unlink/index.html index 05ddd9ec..cd8c9896 100644 --- a/pages/commands/rush_unlink/index.html +++ b/pages/commands/rush_unlink/index.html @@ -6,13 +6,13 @@ rush unlink | Rush - +
Rush StackShopBlogEvents

rush unlink

usage: rush unlink [-h]

This removes the symlinks created by the "rush link" command. This is useful
for cleaning a repo using "git clean" without accidentally deleting source
files, or for using standard NPM commands on a project.

Optional arguments:
  -h, --help  Show this help message and exit.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_update-autoinstaller/index.html b/pages/commands/rush_update-autoinstaller/index.html index f7483f3a..d12c476f 100644 --- a/pages/commands/rush_update-autoinstaller/index.html +++ b/pages/commands/rush_update-autoinstaller/index.html @@ -6,13 +6,13 @@ rush update-autoinstaller | Rush - +
Rush StackShopBlogEvents

rush update-autoinstaller

usage: rush update-autoinstaller [-h] --name AUTOINSTALLER_NAME

Use this command to regenerate the shrinkwrap file for an autoinstaller
folder.

Optional arguments:
  -h, --help            Show this help message and exit.
  --name AUTOINSTALLER_NAME
                        Specifies the name of the autoinstaller, which must
                        be one of the folders under common/autoinstallers.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_update-cloud-credentials/index.html b/pages/commands/rush_update-cloud-credentials/index.html index 70fb8498..05332374 100644 --- a/pages/commands/rush_update-cloud-credentials/index.html +++ b/pages/commands/rush_update-cloud-credentials/index.html @@ -6,13 +6,13 @@ rush update-cloud-credentials | Rush - +
Rush StackShopBlogEvents

rush update-cloud-credentials

usage: rush update-cloud-credentials [-h] [-i]
                                     [--credential CREDENTIAL_STRING] [-d]


(EXPERIMENTAL) If the build caching feature is configured, this command
facilitates updating the credentials used by a cloud-based provider.

Optional arguments:
  -h, --help            Show this help message and exit.
  -i, --interactive     Run the credential update operation in interactive
                        mode, if supported by the provider.
  --credential CREDENTIAL_STRING
                        A static credential, to be cached.
  -d, --delete          If specified, delete stored credentials.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_update/index.html b/pages/commands/rush_update/index.html index 0b84cea2..8319b66d 100644 --- a/pages/commands/rush_update/index.html +++ b/pages/commands/rush_update/index.html @@ -6,13 +6,13 @@ rush update | Rush - +
Rush StackShopBlogEvents

rush update

usage: rush update [-h] [-p] [--bypass-policy] [--no-link]
                   [--network-concurrency COUNT] [--debug-package-manager]
                   [--max-install-attempts NUMBER] [--ignore-hooks]
                   [--variant VARIANT] [--full] [--recheck]


The "rush update" command installs the dependencies described in your package.
json files, and updates the shrinkwrap file as needed. (This "shrinkwrap"
file stores a central inventory of all dependencies and versions for projects
in your repo. It is found in the "common/config/rush" folder.) Note that Rush
always performs a single install for all projects in your repo. You should
run "rush update" whenever you start working in a Rush repo, after you pull
from Git, and after you modify a package.json file. If there is nothing to do,
 "rush update" is instantaneous. NOTE: In certain cases "rush install" should
be used instead of "rush update" -- for details, see the command help for
"rush install".

Optional arguments:
  -h, --help            Show this help message and exit.
  -p, --purge           Perform "rush purge" before starting the installation
  --bypass-policy       Overrides enforcement of the "gitPolicy" rules from
                        rush.json (use honorably!)
  --no-link             If "--no-link" is specified, then project symlinks
                        will NOT be created after the installation completes.
                        You will need to run "rush link" manually. This flag
                        is useful for automated builds that want to report
                        stages individually or perform extra operations in
                        between the two stages. This flag is not supported
                        when using workspaces.
  --network-concurrency COUNT
                        If specified, limits the maximum number of concurrent
                        network requests. This is useful when troubleshooting
                        network failures.
  --debug-package-manager
                        Activates verbose logging for the package manager.
                        You will probably want to pipe the output of Rush to
                        a file when using this command.
  --max-install-attempts NUMBER
                        Overrides the default maximum number of install
                        attempts. The default value is 1.
  --ignore-hooks        Skips execution of the "eventHooks" scripts defined
                        in rush.json. Make sure you know what you are
                        skipping.
  --variant VARIANT     Run command using a variant installation
                        configuration. This parameter may alternatively be
                        specified via the RUSH_VARIANT environment variable.
  --full                Normally "rush update" tries to preserve your
                        existing installed versions and only makes the
                        minimum updates needed to satisfy the package.json
                        files. This conservative approach prevents your PR
                        from getting involved with package updates that are
                        unrelated to your work. Use "--full" when you really
                        want to update all dependencies to the latest
                        SemVer-compatible version. This should be done
                        periodically by a person or robot whose role is to
                        deal with potential upgrade regressions.
  --recheck             If the shrinkwrap file appears to already satisfy the
                        package.json files, then "rush update" will skip
                        invoking the package manager at all. In certain
                        situations this heuristic may be inaccurate. Use the
                        "--recheck" flag to force the package manager to
                        process the shrinkwrap file. This will also update
                        your shrinkwrap file with Rush's fixups. (To minimize
                        shrinkwrap churn, these fixups are normally performed
                        only in the temporary folder.)

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_upgrade-interactive/index.html b/pages/commands/rush_upgrade-interactive/index.html index e9bd5b60..0ebc83ef 100644 --- a/pages/commands/rush_upgrade-interactive/index.html +++ b/pages/commands/rush_upgrade-interactive/index.html @@ -6,13 +6,13 @@ rush upgrade-interactive | Rush - +
Rush StackShopBlogEvents

rush upgrade-interactive

usage: rush upgrade-interactive [-h] [--make-consistent] [-s]

Provide an interactive way to upgrade your dependencies. Running the command
will open an interactive prompt that will ask you which projects and which
dependencies you would like to upgrade. It will then update your package.json
files, and run "rush update" for you. If you are using
ensureConsistentVersions policy, upgrade-interactive will update all packages
which use the dependencies that you are upgrading and match their SemVer
range if provided. If ensureConsistentVersions is not enabled,
upgrade-interactive will only update the dependency in the package you
specify. This can be overriden by using the --make-consistent flag.

Optional arguments:
  -h, --help         Show this help message and exit.
  --make-consistent  When upgrading dependencies from a single project, also
                     upgrade dependencies from other projects.
  -s, --skip-update  If specified, the "rush update" command will not be run
                     after updating the package.json files.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rush_version/index.html b/pages/commands/rush_version/index.html index f21f73ea..ba98ca0b 100644 --- a/pages/commands/rush_version/index.html +++ b/pages/commands/rush_version/index.html @@ -6,13 +6,13 @@ rush version | Rush - +
Rush StackShopBlogEvents

rush version

usage: rush version [-h] [-b BRANCH] [--ensure-version-policy]
                    [--override-version NEW_VERSION] [--bump]
                    [--bypass-policy] [--version-policy POLICY]
                    [--override-bump BUMPTYPE] [--override-prerelease-id ID]
                    [--ignore-git-hooks]


use this "rush version" command to ensure version policies and bump versions.

Optional arguments:
  -h, --help            Show this help message and exit.
  -b BRANCH, --target-branch BRANCH
                        If this flag is specified, changes will be committed
                        and merged into the target branch.
  --ensure-version-policy
                        Updates package versions if needed to satisfy version
                        policies.
  --override-version NEW_VERSION
                        Override the version in the specified
                        --version-policy. This setting only works for
                        lock-step version policy and when
                        --ensure-version-policy is specified.
  --bump                Bumps package version based on version policies.
  --bypass-policy       Overrides "gitPolicy" enforcement (use honorably!)
  --version-policy POLICY
                        The name of the version policy
  --override-bump BUMPTYPE
                        Overrides the bump type in the version-policy.json
                        for the specified version policy. Valid BUMPTYPE
                        values include: prerelease, patch, preminor, minor,
                        major. This setting only works for lock-step version
                        policy in bump action.
  --override-prerelease-id ID
                        Overrides the prerelease identifier in the version
                        value of version-policy.json for the specified
                        version policy. This setting only works for lock-step
                        version policy. This setting increases to new
                        prerelease id when "--bump" is provided but only
                        replaces the prerelease name when
                        "--ensure-version-policy" is provided.
  --ignore-git-hooks    Skips execution of all git hooks. Make sure you know
                        what you are skipping.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/commands/rushx/index.html b/pages/commands/rushx/index.html index 9927f140..90ba0c40 100644 --- a/pages/commands/rushx/index.html +++ b/pages/commands/rushx/index.html @@ -6,7 +6,7 @@ rushx | Rush - + @@ -15,7 +15,7 @@ "scripts" section of the package.json file for an individual project. Any additional CLI parameters are passed only to that shell script without any validation.

Consider this very simple example project:

<my project>/package.json

{
  "name": "my-project",
  "version": "0.0.0",
  "scripts": {
    "build": "rm -Rf lib && tsc",
    "test": "jest"
  }
}

If you invoke rushx alone, it will simply display the available commands:

usage: rushx [-h]
       rushx [-q/--quiet] <command> ...

Optional arguments:
  -h, --help            Show this help message and exit.
  -q, --quiet           Hide rushx startup information.

Project commands for my-project:
  build: "rm -Rf lib && tsc"
  test:  "jest"

If you invoke rushx build, then it would run rm -Rf lib && tsc. If you add a parameter such as rushx build --verbose, it is blindly appended to the end of the string: rm -Rf lib && tsc --verbose.

rush vs rushx​

It's easy to confuse these two commands:

  • rush invokes a generic operation that affects the entire repo ("global commands") or else affects multiple projects ("bulk commands"). Such commands should be carefully designed. Rush enforces that their parameters must be validated and documented.
  • rushx performs custom operations for one single project. Although some of these are used to implement bulk commands, many of them will be helper scripts that are understood only by the developers of that particular project. Rush does not rigorously validate these commands.

Why use "rushx" instead of "pnpm run" or "npx"?​

The rushx command has similar functionality as pnpm run or npx, but with some additional benefits:

  • Ensures deterministic tooling by using the Rush version selector
  • Prepares the shell environment based on Rush's configuration
  • Implements additional validations
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/artifactory_json/index.html b/pages/configs/artifactory_json/index.html index 6f64200d..ce5452f5 100644 --- a/pages/configs/artifactory_json/index.html +++ b/pages/configs/artifactory_json/index.html @@ -6,14 +6,14 @@ artifactory.json | Rush - +
Rush StackShopBlogEvents

artifactory.json

This is the template that rush init generates for artifactory.json:

common/config/rush/artifactory.json

/**
 * This configuration file manages Rush integration with JFrog Artifactory services.
 * More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/artifactory.schema.json",

  "packageRegistry": {
    /**
     * (Required) Set this to "true" to enable Rush to manage tokens for an Artifactory NPM registry.
     * When enabled, "rush install" will automatically detect when the user's ~/.npmrc
     * authentication token is missing or expired.  And "rush setup" will prompt the user to
     * renew their token.
     *
     * The default value is false.
     */
    "enabled": false,

    /**
     * (Required) Specify the URL of your NPM registry.  This is the same URL that appears in
     * your .npmrc file.  It should look something like this example:
     *
     *   https://your-company.jfrog.io/your-project/api/npm/npm-private/
     */
    "registryUrl": "",

    /**
     * A list of custom strings that "rush setup" should add to the user's ~/.npmrc file at the time
     * when the token is updated.  This could be used for example to configure the company registry
     * to be used whenever NPM is invoked as a standalone command (but it's not needed for Rush
     * operations like "rush add" and "rush install", which get their mappings from the monorepo's
     * common/config/rush/.npmrc file).
     *
     * NOTE: The ~/.npmrc settings are global for the user account on a given machine, so be careful
     * about adding settings that may interfere with other work outside the monorepo.
     */
    "userNpmrcLinesToAdd": [
      // "@example:registry=https://your-company.jfrog.io/your-project/api/npm/npm-private/"
    ],

    /**
     * (Required) Specifies the URL of the Artifactory control panel where the user can generate
     * an API key.  This URL is printed after the "visitWebsite" message.
     * It should look something like this example:  https://your-company.jfrog.io/
     * Specify an empty string to suppress this line entirely.
     */
    "artifactoryWebsiteUrl": "",

    /**
     * Uncomment this line to specify the type of credential to save in the user's ~/.npmrc file.
     * The default is "password", which means the user's API token will be traded in for an
     * npm password specific to that registry. Optionally you can specify "authToken", which
     * will save the user's API token as credentials instead.
     */
    // "credentialType": "password",

    /**
     * These settings allow the "rush setup" interactive prompts to be customized, for
     * example with messages specific to your team or configuration.  Specify an empty string
     * to suppress that message entirely.
     */
    "messageOverrides": {
      /**
       * Overrides the message that normally says:
       * "This monorepo consumes packages from an Artifactory private NPM registry."
       */
      // "introduction": "",

      /**
       * Overrides the message that normally says:
       * "Please contact the repository maintainers for help with setting up an Artifactory user account."
       */
      // "obtainAnAccount": "",

      /**
       * Overrides the message that normally says:
       * "Please open this URL in your web browser:"
       *
       * The "artifactoryWebsiteUrl" string is printed after this message.
       */
      // "visitWebsite": "",

      /**
       * Overrides the message that normally says:
       * "Your user name appears in the upper-right corner of the JFrog website."
       */
      // "locateUserName": "",

      /**
       * Overrides the message that normally says:
       * "Click 'Edit Profile' on the JFrog website.  Click the 'Generate API Key'
       * button if you haven't already done so previously."
       */
      // "locateApiKey": ""

      /**
       * Overrides the message that normally prompts:
       * "What is your Artifactory user name?"
       */
      // "userNamePrompt": ""

      /**
       * Overrides the message that normally prompts:
       * "What is your Artifactory API key?"
       */
      // "apiKeyPrompt": ""
    }
  }
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/build-cache_json/index.html b/pages/configs/build-cache_json/index.html index 067472b7..0af0b823 100644 --- a/pages/configs/build-cache_json/index.html +++ b/pages/configs/build-cache_json/index.html @@ -6,14 +6,14 @@ build-cache.json | Rush - +
Rush StackShopBlogEvents

build-cache.json

This is the template that rush init generates for build-cache.json:

common/config/rush/build-cache.json

/**
 * This configuration file manages Rush's build cache feature.
 * More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/build-cache.schema.json",

  /**
   * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.
   *
   * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.
   */
  "buildCacheEnabled": false,

  /**
   * (Required) Choose where project build outputs will be cached.
   *
   * Possible values: "local-only", "azure-blob-storage", "amazon-s3"
   */
  "cacheProvider": "local-only",

  /**
   * Setting this property overrides the cache entry ID.  If this property is set, it must contain
   * a [hash] token.
   *
   * Other available tokens:
   *  - [projectName]
   *  - [projectName:normalize]
   *  - [phaseName]
   *  - [phaseName:normalize]
   *  - [phaseName:trimPrefix]
   */
  // "cacheEntryNamePattern": "[projectName:normalize]-[phaseName:normalize]-[hash]"

  /**
   * Use this configuration with "cacheProvider"="azure-blob-storage"
   */
  "azureBlobStorageConfiguration": {
    /**
     * (Required) The name of the the Azure storage account to use for build cache.
     */
    // "storageAccountName": "example",

    /**
     * (Required) The name of the container in the Azure storage account to use for build cache.
     */
    // "storageContainerName": "my-container",

    /**
     * The Azure environment the storage account exists in. Defaults to AzurePublicCloud.
     *
     * Possible values: "AzurePublicCloud", "AzureChina", "AzureGermany", "AzureGovernment"
     */
    // "azureEnvironment": "AzurePublicCloud",

    /**
     * An optional prefix for cache item blob names.
     */
    // "blobPrefix": "my-prefix",

    /**
     * If set to true, allow writing to the cache. Defaults to false.
     */
    // "isCacheWriteAllowed": true
  },

  /**
   * Use this configuration with "cacheProvider"="amazon-s3"
   */
  "amazonS3Configuration": {
    /**
     * (Required unless s3Endpoint is specified) The name of the bucket to use for build cache.
     * Example: "my-bucket"
     */
    // "s3Bucket": "my-bucket",

    /**
     * (Required unless s3Bucket is specified) The Amazon S3 endpoint of the bucket to use for build cache.
     * This should not include any path; use the s3Prefix to set the path.
     * Examples: "my-bucket.s3.us-east-2.amazonaws.com" or "http://localhost:9000"
     */
    // "s3Endpoint": "https://my-bucket.s3.us-east-2.amazonaws.com",

    /**
     * (Required) The Amazon S3 region of the bucket to use for build cache.
     * Example: "us-east-1"
     */
    // "s3Region": "us-east-1",

    /**
     * An optional prefix ("folder") for cache items. It should not start with "/".
     */
    // "s3Prefix": "my-prefix",

    /**
     * If set to true, allow writing to the cache. Defaults to false.
     */
    // "isCacheWriteAllowed": true
  }
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/cobuild_json/index.html b/pages/configs/cobuild_json/index.html index 0a5f567a..e05490c5 100644 --- a/pages/configs/cobuild_json/index.html +++ b/pages/configs/cobuild_json/index.html @@ -6,14 +6,14 @@ cobuild.json (experimental) | Rush - +
Rush StackShopBlogEvents

cobuild.json (experimental)

This is the template that rush init generates for the cobuild feature.

common/config/rush/cobuild.json

/**
 * This configuration file manages Rush's cobuild feature.
 * More documentation is available on the Rush website: https://rushjs.io
 */
 {
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/cobuild.schema.json",

  /**
   * (Required) EXPERIMENTAL - Set this to true to enable the cobuild feature.
   * RUSH_COBUILD_CONTEXT_ID should always be specified as an environment variable with an non-empty string,
   * otherwise the cobuild feature will be disabled.
   */
  "cobuildFeatureEnabled": false,

  /**
   * (Required) Choose where cobuild lock will be acquired.
   *
   * The lock provider is registered by the rush plugins.
   * For example, @rushstack/rush-redis-cobuild-plugin registers the "redis" lock provider.
   */
  "cobuildLockProvider": "redis"
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/command-line_json/index.html b/pages/configs/command-line_json/index.html index 950ac361..774f75d9 100644 --- a/pages/configs/command-line_json/index.html +++ b/pages/configs/command-line_json/index.html @@ -6,14 +6,14 @@ command-line.json | Rush - +
Rush StackShopBlogEvents

command-line.json

This is the template that rush init generates for command-line.json:

common/config/rush/command-line.json

/**
 * This configuration file defines custom commands for the "rush" command-line.
 * More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/command-line.schema.json",

  /**
   * Custom "commands" introduce new verbs for the command-line.  To see the help for these
   * example commands, try "rush --help", "rush my-bulk-command --help", or
   * "rush my-global-command --help".
   */
  "commands": [
    // {
    //   /**
    //    * (Required) Determines the type of custom command.
    //    * Rush's "bulk" commands are invoked separately for each project.  By default, the command will run for
    //    * every project in the repo, according to the dependency graph (similar to how "rush build" works).
    //    * The set of projects can be restricted e.g. using the "--to" or "--from" parameters.
    //    */
    //   "commandKind": "bulk",
    //
    //   /**
    //    * (Required) The name that will be typed as part of the command line.  This is also the name
    //    * of the "scripts" hook in the project's package.json file (if "shellCommand" is not specified).
    //    *
    //    * The name should be comprised of lower case words separated by hyphens or colons. The name should include an
    //    * English verb (e.g. "deploy"). Use a hyphen to separate words (e.g. "upload-docs"). A group of related commands
    //    * can be prefixed with a colon (e.g. "docs:generate", "docs:deploy", "docs:serve", etc).
    //    *
    //    * Note that if the "rebuild" command is overridden here, it becomes separated from the "build" command
    //    * and will call the "rebuild" script instead of the "build" script.
    //    */
    //   "name": "my-bulk-command",
    //
    //   /**
    //    * (Required) A short summary of the custom command to be shown when printing command line
    //    * help, e.g. "rush --help".
    //    */
    //   "summary": "Example bulk custom command",
    //
    //   /**
    //    * A detailed description of the command to be shown when printing command line
    //    * help (e.g. "rush --help my-command").
    //    * If omitted, the "summary" text will be shown instead.
    //    *
    //    * Whenever you introduce commands/parameters, taking a little time to write meaningful
    //    * documentation can make a big difference for the developer experience in your repo.
    //    */
    //   "description": "This is an example custom command that runs separately for each project",
    //
    //   /**
    //    * By default, Rush operations acquire a lock file which prevents multiple commands from executing simultaneously
    //    * in the same repo folder.  (For example, it would be a mistake to run "rush install" and "rush build" at the
    //    * same time.)  If your command makes sense to run concurrently with other operations,
    //    * set "safeForSimultaneousRushProcesses" to true to disable this protection.
    //    *
    //    * In particular, this is needed for custom scripts that invoke other Rush commands.
    //    */
    //   "safeForSimultaneousRushProcesses": false,
    //
    //   /**
    //    * (Optional) If the `shellCommand` field is set for a bulk command, Rush will invoke it for each
    //    * selected project; otherwise, Rush will invoke the package.json `"scripts"` entry matching Rush command name.
    //    *
    //    * The string is the path to a script that will be invoked using the OS shell. The working directory will be
    //    * the folder that contains rush.json.  If custom parameters are associated with this command, their
    //    * values will be appended to the end of this string.
    //    */
    //   // "shellCommand": "node common/scripts/my-bulk-command.js",
    //
    //   /**
    //    * (Required) If true, then this command is safe to be run in parallel, i.e. executed
    //    * simultaneously for multiple projects.  Similar to "rush build", regardless of parallelism
    //    * projects will not start processing until their dependencies have completed processing.
    //    */
    //   "enableParallelism": false,
    //
    //   /**
    //    * Normally projects will be processed according to their dependency order: a given project will not start
    //    * processing the command until all of its dependencies have completed.  This restriction doesn't apply for
    //    * certain operations, for example a "clean" task that deletes output files.  In this case
    //    * you can set "ignoreDependencyOrder" to true to increase parallelism.
    //    */
    //   "ignoreDependencyOrder": false,
    //
    //   /**
    //    * Normally Rush requires that each project's package.json has a "scripts" entry matching
    //    * the custom command name.  To disable this check, set "ignoreMissingScript" to true;
    //    * projects with a missing definition will be skipped.
    //    */
    //   "ignoreMissingScript": false,
    //
    //   /**
    //    * When invoking shell scripts, Rush uses a heuristic to distinguish errors from warnings:
    //    * - If the shell script returns a nonzero process exit code, Rush interprets this as "one or more errors".
    //    * Error output is displayed in red, and it prevents Rush from attempting to process any downstream projects.
    //    * - If the shell script returns a zero process exit code but writes something to its stderr stream,
    //    * Rush interprets this as "one or more warnings". Warning output is printed in yellow, but does NOT prevent
    //    * Rush from processing downstream projects.
    //    *
    //    * Thus, warnings do not interfere with local development, but they will cause a CI job to fail, because
    //    * the Rush process itself returns a nonzero exit code if there are any warnings or errors. This is by design.
    //    * In an active monorepo, we've found that if you allow any warnings in your main branch, it inadvertently
    //    * teaches developers to ignore warnings, which quickly leads to a situation where so many "expected" warnings
    //    * have accumulated that warnings no longer serve any useful purpose.
    //    *
    //    * Sometimes a poorly behaved task will write output to stderr even though its operation was successful.
    //    * In that case, it's strongly recommended to fix the task.  However, as a workaround you can set
    //    * allowWarningsInSuccessfulBuild=true, which causes Rush to return a nonzero exit code for errors only.
    //    *
    //    * Note: The default value is false. In Rush 5.7.x and earlier, the default value was true.
    //    */
    //   "allowWarningsInSuccessfulBuild": false,
    //
    //   /**
    //    * If true then this command will be incremental like the built-in "build" command
    //    */
    //   "incremental": false,
    //
    //   /**
    //    * (EXPERIMENTAL) Normally Rush terminates after the command finishes. If this option is set to "true" Rush
    //    * will instead enter a loop where it watches the file system for changes to the selected projects. Whenever a
    //    * change is detected, the command will be invoked again for the changed project and any selected projects that
    //    * directly or indirectly depend on it.
    //    *
    //    * For details, refer to the website article "Using watch mode".
    //    */
    //   "watchForChanges": false,
    //
    //   /**
    //    * (EXPERIMENTAL) Disable cache for this action. This may be useful if this command affects state outside of
    //    * projects' own folders.
    //    */
    //   "disableBuildCache": false
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom command.
    //    * Rush's "global" commands are invoked once for the entire repo.
    //    */
    //   "commandKind": "global",
    //
    //   "name": "my-global-command",
    //   "summary": "Example global custom command",
    //   "description": "This is an example custom command that runs once for the entire repo",
    //
    //   "safeForSimultaneousRushProcesses": false,
    //
    //   /**
    //    * (Required) A script that will be invoked using the OS shell. The working directory will be
    //    * the folder that contains rush.json.  If custom parameters are associated with this command, their
    //    * values will be appended to the end of this string.
    //    */
    //   "shellCommand": "node common/scripts/my-global-command.js",
    //
    //   /**
    //    * If your "shellCommand" script depends on NPM packages, the recommended best practice is
    //    * to make it into a regular Rush project that builds using your normal toolchain.  In cases where
    //    * the command needs to work without first having to run "rush build", the recommended practice
    //    * is to publish the project to an NPM registry and use common/scripts/install-run.js to launch it.
    //    *
    //    * Autoinstallers offer another possibility: They are folders under "common/autoinstallers" with
    //    * a package.json file and shrinkwrap file. Rush will automatically invoke the package manager to
    //    * install these dependencies before an associated command is invoked.  Autoinstallers have the
    //    * advantage that they work even in a branch where "rush install" is broken, which makes them a
    //    * good solution for Git hook scripts.  But they have the disadvantages of not being buildable
    //    * projects, and of increasing the overall installation footprint for your monorepo.
    //    *
    //    * The "autoinstallerName" setting must not contain a path and must be a valid NPM package name.
    //    * For example, the name "my-task" would map to "common/autoinstallers/my-task/package.json", and
    //    * the "common/autoinstallers/my-task/node_modules/.bin" folder would be added to the shell PATH when
    //    * invoking the "shellCommand".
    //    */
    //   // "autoinstallerName": "my-task"
    // }
  ],

  /**
   * Custom "parameters" introduce new parameters for specified Rush command-line commands.
   * For example, you might define a "--production" parameter for the "rush build" command.
   */
  "parameters": [
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * A "flag" is a custom command-line parameter whose presence acts as an on/off switch.
    //    */
    //   "parameterKind": "flag",
    //
    //   /**
    //    * (Required) The long name of the parameter.  It must be lower-case and use dash delimiters.
    //    */
    //   "longName": "--my-flag",
    //
    //   /**
    //    * An optional alternative short name for the parameter.  It must be a dash followed by a single
    //    * lower-case or upper-case letter, which is case-sensitive.
    //    *
    //    * NOTE: The Rush developers recommend that automation scripts should always use the long name
    //    * to improve readability.  The short name is only intended as a convenience for humans.
    //    * The alphabet letters run out quickly, and are difficult to memorize, so *only* use
    //    * a short name if you expect the parameter to be needed very often in everyday operations.
    //    */
    //   "shortName": "-m",
    //
    //   /**
    //    * (Required) A long description to be shown in the command-line help.
    //    *
    //    * Whenever you introduce commands/parameters, taking a little time to write meaningful
    //    * documentation can make a big difference for the developer experience in your repo.
    //    */
    //   "description": "A custom flag parameter that is passed to the scripts that are invoked when building projects",
    //
    //   /**
    //    * (Required) A list of custom commands and/or built-in Rush commands that this parameter may
    //    * be used with.  The parameter will be appended to the shell command that Rush invokes.
    //    */
    //   "associatedCommands": ["build", "rebuild"]
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * A "string" is a custom command-line parameter whose argument is a single text string.
    //    */
    //   "parameterKind": "string",
    //   "longName": "--my-string",
    //   "description": "A custom string parameter for the \"my-global-command\" custom command",
    //
    //   "associatedCommands": ["my-global-command"],
    //
    //   "argumentName": "SOME_TEXT",
    //
    //   /**
    //    * If true, this parameter must be included with the command.  The default is false.
    //    */
    //   "required": false
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * A "choice" is a custom command-line parameter whose argument must be chosen from a list of
    //    * allowable alternatives (similar to an enum).
    //    */
    //   "parameterKind": "choice",
    //   "longName": "--my-choice",
    //   "description": "A custom choice parameter for the \"my-global-command\" custom command",
    //
    //   "associatedCommands": ["my-global-command"],
    //   "required": false,
    //
    //   /**
    //    * If a "defaultValue" is specified, then if the Rush command line is invoked without
    //    * this parameter, it will be automatically added with the "defaultValue" as the argument.
    //    * The value must be one of the defined alternatives.
    //    */
    //   "defaultValue": "vanilla",
    //
    //   /**
    //    * (Required) A list of alternative argument values that can be chosen for this parameter.
    //    */
    //   "alternatives": [
    //     {
    //       /**
    //        * A token that is one of the alternatives that can be used with the choice parameter,
    //        * e.g. "vanilla" in "--flavor vanilla".
    //        */
    //       "name": "vanilla",
    //
    //       /**
    //        * A detailed description for the alternative that can be shown in the command-line help.
    //        *
    //        * Whenever you introduce commands/parameters, taking a little time to write meaningful
    //        * documentation can make a big difference for the developer experience in your repo.
    //        */
    //       "description": "Use the vanilla flavor"
    //     },
    //
    //     {
    //       "name": "chocolate",
    //       "description": "Use the chocolate flavor"
    //     },
    //
    //     {
    //       "name": "strawberry",
    //       "description": "Use the strawberry flavor"
    //     }
    //   ]
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * An "integer" is a custom command-line parameter whose value is an integer number.
    //    */
    //   "parameterKind": "integer",
    //   "longName": "--my-integer",
    //   "description": "A custom integer parameter for the \"my-global-command\" custom command",
    //
    //   "associatedCommands": ["my-global-command"],
    //   "argumentName": "SOME_NUMBER",
    //   "required": false
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * An "integerList" is a custom command-line parameter whose argument is an integer.
    //    * The parameter can be specified multiple times to build a list.
    //    *
    //    * For example, if the parameter name is "--my-integer-list", then the custom command
    //    * might be invoked as
    //    * `rush my-global-command --my-integer-list 1 --my-integer-list 2 --my-integer-list 3`
    //    * and the parsed array would be [1,2,3].
    //    */
    //   "parameterKind": "integerList",
    //   "longName": "--my-integer-list",
    //   "description": "A custom integer list parameter for the \"my-global-command\" custom command",
    //
    //   "associatedCommands": ["my-global-command"],
    //   "argumentName": "SOME_NUMBER",
    //   "required": false
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * An "stringList" is a custom command-line parameter whose argument is a text string.
    //    * The parameter can be specified multiple times to build a list.
    //    *
    //    * For example, if the parameter name is "--my-string-list", then the custom command
    //    * might be invoked as
    //    * `rush my-global-command --my-string-list A --my-string-list B --my-string-list C`
    //    * and the parsed array would be [A,B,C].
    //    */
    //   "parameterKind": "stringList",
    //   "longName": "--my-string-list",
    //   "description": "A custom string list parameter for the \"my-global-command\" custom command",
    //
    //   "associatedCommands": ["my-global-command"],
    //   "argumentName": "SOME_TEXT",
    //   "required": false
    // },
    //
    // {
    //   /**
    //    * (Required) Determines the type of custom parameter.
    //    * A "choice" is a custom command-line parameter whose argument must be chosen from a list of
    //    * allowable alternatives (similar to an enum).
    //    * The parameter can be specified multiple times to build a list.
    //    *
    //    * For example, if the parameter name is "--my-choice-list", then the custom command
    //    * might be invoked as
    //    * `rush my-global-command --my-string-list vanilla --my-string-list chocolate`
    //    * and the parsed array would be [vanilla,chocolate].
    //    */
    //   "parameterKind": "choiceList",
    //   "longName": "--my-choice-list",
    //   "description": "A custom choice list parameter for the \"my-global-command\" custom command",
    //
    //   "associatedCommands": ["my-global-command"],
    //   "required": false,
    //
    //   /**
    //    * (Required) A list of alternative argument values that can be chosen for this parameter.
    //    */
    //   "alternatives": [
    //     {
    //       /**
    //        * A token that is one of the alternatives that can be used with the choice parameter,
    //        * e.g. "vanilla" in "--flavor vanilla".
    //        */
    //       "name": "vanilla",
    //
    //       /**
    //        * A detailed description for the alternative that can be shown in the command-line help.
    //        *
    //        * Whenever you introduce commands/parameters, taking a little time to write meaningful
    //        * documentation can make a big difference for the developer experience in your repo.
    //        */
    //       "description": "Use the vanilla flavor"
    //     },
    //
    //     {
    //       "name": "chocolate",
    //       "description": "Use the chocolate flavor"
    //     },
    //
    //     {
    //       "name": "strawberry",
    //       "description": "Use the strawberry flavor"
    //     }
    //   ]
    // }
  ]
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/command_line_json/index.html b/pages/configs/command_line_json/index.html index e47aef02..ac159f99 100644 --- a/pages/configs/command_line_json/index.html +++ b/pages/configs/command_line_json/index.html @@ -6,13 +6,13 @@ command_line_json | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/common-versions_json/index.html b/pages/configs/common-versions_json/index.html index c03a47f3..20dbcf02 100644 --- a/pages/configs/common-versions_json/index.html +++ b/pages/configs/common-versions_json/index.html @@ -6,14 +6,14 @@ common-versions.json | Rush - +
Rush StackShopBlogEvents

common-versions.json

This is the template that rush init generates for common-versions.json:

common/config/rush/common-versions.json

/**
 * This configuration file specifies NPM dependency version selections that affect all projects
 * in a Rush repo.  More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/common-versions.schema.json",

  /**
   * A table that specifies a "preferred version" for a given NPM package.  This feature is typically used
   * to hold back an indirect dependency to a specific older version, or to reduce duplication of indirect dependencies.
   *
   * The "preferredVersions" value can be any SemVer range specifier (e.g. "~1.2.3").  Rush injects these values into
   * the "dependencies" field of the top-level common/temp/package.json, which influences how the package manager
   * will calculate versions.  The specific effect depends on your package manager.  Generally it will have no
   * effect on an incompatible or already constrained SemVer range.  If you are using PNPM, similar effects can be
   * achieved using the pnpmfile.js hook.  See the Rush documentation for more details.
   *
   * After modifying this field, it's recommended to run "rush update --full" so that the package manager
   * will recalculate all version selections.
   */
  "preferredVersions": {
    /**
     * When someone asks for "^1.0.0" make sure they get "1.2.3" when working in this repo,
     * instead of the latest version.
     */
    // "some-library": "1.2.3"
  },

  /**
   * When set to true, for all projects in the repo, all dependencies will be automatically added as preferredVersions,
   * except in cases where different projects specify different version ranges for a given dependency.  For older
   * package managers, this tended to reduce duplication of indirect dependencies.  However, it can sometimes cause
   * trouble for indirect dependencies with incompatible peerDependencies ranges.
   *
   * The default value is true.  If you're encountering installation errors related to peer dependencies,
   * it's recommended to set this to false.
   *
   * After modifying this field, it's recommended to run "rush update --full" so that the package manager
   * will recalculate all version selections.
   */
  // "implicitlyPreferredVersions": false,

  /**
   * The "rush check" command can be used to enforce that every project in the repo must specify
   * the same SemVer range for a given dependency.  However, sometimes exceptions are needed.
   * The allowedAlternativeVersions table allows you to list other SemVer ranges that will be
   * accepted by "rush check" for a given dependency.
   *
   * IMPORTANT: THIS TABLE IS FOR *ADDITIONAL* VERSION RANGES THAT ARE ALTERNATIVES TO THE
   * USUAL VERSION (WHICH IS INFERRED BY LOOKING AT ALL PROJECTS IN THE REPO).
   * This design avoids unnecessary churn in this file.
   */
  "allowedAlternativeVersions": {
    /**
     * For example, allow some projects to use an older TypeScript compiler
     * (in addition to whatever "usual" version is being used by other projects in the repo):
     */
    // "typescript": [
    //   "~2.4.0"
    // ]
  }
}
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/common_versions_json/index.html b/pages/configs/common_versions_json/index.html index 81eb4aa4..bb92ddc7 100644 --- a/pages/configs/common_versions_json/index.html +++ b/pages/configs/common_versions_json/index.html @@ -6,13 +6,13 @@ common_versions_json | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/custom-tips_json/index.html b/pages/configs/custom-tips_json/index.html index d3152c84..f725c2f3 100644 --- a/pages/configs/custom-tips_json/index.html +++ b/pages/configs/custom-tips_json/index.html @@ -6,14 +6,14 @@ custom-tips.json (experimental) | Rush - +
Rush StackShopBlogEvents

custom-tips.json (experimental)

This is the template that rush init generates for the Custom tips feature.

common/config/rush/custom-tips.json

/**
 * This configuration file allows repo maintainers to configure extra details to be
 * printed alongside certain Rush messages.  More documentation is available on the
 * Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/custom-tips.schema.json",

  /**
   * Specifies the custom tips to be displayed by Rush.
   */
  "customTips": [
    // {
    //   /**
    //    * (REQUIRED) An identifier indicating a message that may be printed by Rush.
    //    * If that message is printed, then this custom tip will be shown.
    //    * Consult the Rush documentation for the current list of possible identifiers.
    //    */
    //   "tipId": "TIP_RUSH_INCONSISTENT_VERSIONS",
    //
    //   /**
    //    * (REQUIRED) The message text to be displayed for this tip.
    //    */
    //   "message": "For additional troubleshooting information, refer this wiki article:\n\nhttps://intranet.contoso.com/docs/pnpm-mismatch"
    // }
  ]
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/deploy_json/index.html b/pages/configs/deploy_json/index.html index c61bfb92..50a963d9 100644 --- a/pages/configs/deploy_json/index.html +++ b/pages/configs/deploy_json/index.html @@ -6,14 +6,14 @@ deploy.json | Rush - +
Rush StackShopBlogEvents

deploy.json

This is the template that rush init-deploy generates for deploy.json and deploy-<scenario name>>.json:

common/config/rush/deploy.json

/**
 * This configuration file defines a deployment scenario for use with the "rush deploy" command.
 * The default scenario file path is "deploy.json"; additional files use the naming pattern
 * "deploy-<scenario-name>.json". For full documentation, please see https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/deploy-scenario.schema.json",

  /**
   * The "rush deploy" command prepares a deployment folder, starting from the main project and collecting
   * all of its dependencies (both NPM packages and other Rush projects).  The main project is specified
   * using the "--project" parameter.  The "deploymentProjectNames" setting lists the allowable choices for
   * the "--project" parameter; this documents the intended deployments for your monorepo and helps validate
   * that "rush deploy" is invoked correctly.  If there is only one item in the "deploymentProjectNames" array,
   * then "--project" can be omitted.  The names should be complete package names as declared in rush.json.
   *
   * If the main project should include other unrelated Rush projects, add it to the "projectSettings" section,
   * and then specify those projects in the "additionalProjectsToInclude" list.
   */
  "deploymentProjectNames": [ /* YOUR PROJECT HERE */ ],

  /**
   * When deploying a local Rush project, the package.json "devDependencies" are normally excluded.
   * If you want to include them, set "includeDevDependencies" to true.
   *
   * The default value is false.
   */
  // "includeDevDependencies": true,

  /**
   * When deploying a local Rush project, normally the .npmignore filter is applied so that Rush only copies
   * files that would be packaged by "npm pack".  Setting "includeNpmIgnoreFiles" to true will disable this
   * filtering so that all files are copied (with a few trivial exceptions such as the "node_modules" folder).
   *
   * The default value is false.
   */
  // "includeNpmIgnoreFiles": true,

  /**
   * To improve backwards compatibility with legacy packages, the PNPM package manager installs extra links in the
   * node_modules folder that enable packages to import undeclared dependencies.  In some cases this workaround may
   * double the number of links created.  If your deployment does not require this workaround, you can set
   * "omitPnpmWorkaroundLinks" to true to avoid creating the extra links.
   *
   * The default value is false.
   */
  // "omitPnpmWorkaroundLinks": true,

  /**
   * Specify how links (symbolic links, hard links, and/or NTFS junctions) will be created in the deployed folder:
   *
   * - "default": Create the links while copying the files; this is the default behavior.
   * - "script": A Node.js script called "create-links.js" will be written.  When executed, this script will
   *   create the links described in the "deploy-metadata.json" output file.
   * - "none": Do nothing; some other tool may create the links later.
   */
  // "linkCreation": "script",

  /**
   * If this path is specified, then after "rush deploy", recursively copy the files from this folder to
   * the deployment target folder (common/deploy). This can be used to provide additional configuration files
   * or scripts needed by the server when deploying. The path is resolved relative to the repository root.
   */
  //  "folderToCopy": "repo-tools/assets/deploy-config",

  /**
   * Customize how Rush projects are processed during deployment.
   */
  "projectSettings": [
    // {
    //   /**
    //    * The full package name of the project, which must be declared in rush.json.
    //    */
    //   "projectName": "@my-scope/my-project",
    //
    //   /**
    //    * A list of additional local Rush projects to be deployed with this project (beyond the package.json
    //    * dependencies).  Specify full package names, which must be declared in rush.json.
    //    */
    //   "additionalProjectsToInclude": [
    //     // "@my-scope/my-project2"
    //   ],
    //
    //   /**
    //    * When deploying a project, the included dependencies are normally determined automatically based on
    //    * package.json fields such as "dependencies", "peerDependencies", and "optionalDependencies",
    //    * subject to other deployment settings such as "includeDevDependencies".  However, in cases where
    //    * that information is not accurate, you can use "additionalDependenciesToInclude" to add more
    //    * packages to the list.
    //    *
    //    * The list can include any package name that is installed by Rush and resolvable via Node.js module
    //    * resolution; however, if it resolves to a local Rush project, the "additionalProjectsToInclude"
    //    * field will not be recursively applied.
    //    */
    //   "additionalDependenciesToInclude": [
    //     // "@rushstack/node-core-library"
    //   ],
    //
    //   /**
    //    * This setting prevents specific dependencies from being deployed.  It only filters dependencies that
    //    * are explicitly declared in package.json for this project.  It does not affect dependencies added
    //    * via "additionalProjectsToInclude" or "additionalDependenciesToInclude", nor does it affect indirect
    //    * dependencies.
    //    *
    //    * The "*" wildcard may be used to match zero or more characters.  For example, if your project already
    //    * bundles its own dependencies, specify "dependenciesToExclude": [ "*" ] to exclude all package.json
    //    * dependencies.
    //    */
    //   "dependenciesToExclude": [
    //     // "@types/*"
    //   ]
    // }
  ]
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/environment_vars/index.html b/pages/configs/environment_vars/index.html index 5a68e1bd..fc7103ad 100644 --- a/pages/configs/environment_vars/index.html +++ b/pages/configs/environment_vars/index.html @@ -6,7 +6,7 @@ Environment variables | Rush - + @@ -64,7 +64,7 @@ If attempting to move the PNPM store path, see the RUSH_PNPM_STORE_PATH environment variable.

RUSH_VARIANT​

This variable selects a specific installation variant for Rush to use when installing and linking package dependencies.

For more information about this feature, see Installation Variants.

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/experiments_json/index.html b/pages/configs/experiments_json/index.html index f18a437e..e639a8fe 100644 --- a/pages/configs/experiments_json/index.html +++ b/pages/configs/experiments_json/index.html @@ -6,14 +6,14 @@ experiments.json | Rush - +
Rush StackShopBlogEvents

experiments.json

This is the template that rush init generates for experiments.json:

common/config/rush/experiments.json

/**
 * This configuration file allows repo maintainers to enable and disable experimental
 * Rush features.  More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/experiments.schema.json",

  /**
   * By default, 'rush install' passes --no-prefer-frozen-lockfile to 'pnpm install'.
   * Set this option to true to pass '--frozen-lockfile' instead for faster installs.
   */
  // "usePnpmFrozenLockfileForRushInstall": true,

  /**
   * By default, 'rush update' passes --no-prefer-frozen-lockfile to 'pnpm install'.
   * Set this option to true to pass '--prefer-frozen-lockfile' instead to minimize shrinkwrap changes.
   */
  // "usePnpmPreferFrozenLockfileForRushUpdate": true,

  /**
   * If using the 'preventManualShrinkwrapChanges' option, restricts the hash to only include the layout of external dependencies.
   * Used to allow links between workspace projects or the addition/removal of references to existing dependency versions to not
   * cause hash changes.
   */
  // "omitImportersFromPreventManualShrinkwrapChanges": true,

  /**
   * If true, the chmod field in temporary project tar headers will not be normalized.
   * This normalization can help ensure consistent tarball integrity across platforms.
   */
  // "noChmodFieldInTarHeaderNormalization": true,

  /**
   * If true, build caching will respect the allowWarningsInSuccessfulBuild flag and cache builds with warnings.
   * This will not replay warnings from the cached build.
   */
  // "buildCacheWithAllowWarningsInSuccessfulBuild": true,

  /**
   * If true, the phased commands feature is enabled. To use this feature, create a "phased" command
   * in common/config/rush/command-line.json.
   */
  // "phasedCommands": true
}
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/npmrc-publish/index.html b/pages/configs/npmrc-publish/index.html index 132f3fef..fe1f777e 100644 --- a/pages/configs/npmrc-publish/index.html +++ b/pages/configs/npmrc-publish/index.html @@ -6,14 +6,14 @@ .npmrc-publish | Rush - +
Rush StackShopBlogEvents

.npmrc-publish

This is the template that rush init generates for .npmrc-publish:

common/config/rush/.npmrc-publish

# This config file is very similar to common/config/rush/.npmrc, except that .npmrc-publish
# is used by the "rush publish" command, as publishing often involves different credentials
# and registries than other operations.
#
# Before invoking the package manager, Rush will copy this file to "common/temp/publish-home/.npmrc"
# and then temporarily map that folder as the "home directory" for the current user account.
# This enables the same settings to apply for each project folder that gets published.  The copied file
# will omit any config lines that reference environment variables that are undefined in that session;
# this avoids problems that would otherwise result due to a missing variable being replaced by
# an empty string.
#
# * * * SECURITY WARNING * * *
#
# It is NOT recommended to store authentication tokens in a text file on a lab machine, because
# other unrelated processes may be able to read the file.  Also, the file may persist indefinitely,
# for example if the machine loses power.  A safer practice is to pass the token via an
# environment variable, which can be referenced from .npmrc using ${} expansion.  For example:
#
#   //registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}
#

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/npmrc/index.html b/pages/configs/npmrc/index.html index 9f83cf9a..b0ba77f7 100644 --- a/pages/configs/npmrc/index.html +++ b/pages/configs/npmrc/index.html @@ -6,7 +6,7 @@ .npmrc | Rush - + @@ -25,7 +25,7 @@ package manager's usual precedence will apply instead. Generally this practice is discouraged in a Rush repo, but if used, you may need to create additional .npmrc files.

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/pnpm-config_json/index.html b/pages/configs/pnpm-config_json/index.html index e87ecb6d..9a2802e2 100644 --- a/pages/configs/pnpm-config_json/index.html +++ b/pages/configs/pnpm-config_json/index.html @@ -6,7 +6,7 @@ pnpm-config.json | Rush - + @@ -18,7 +18,7 @@ you must manually delete the "pnpmOptions" setting from rush.json and create the pnpm-config.json file.

This is the template that rush init generates for pnpm-config.json:

common/config/rush/pnpm-config.json

/**
 * This configuration file provides settings specific to the PNPM package manager.
 * More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/pnpm-config.schema.json",

  /**
   * If true, then `rush install` and `rush update` will use the PNPM workspaces feature
   * to perform the install, instead of the old model where Rush generated the symlinks
   * for each projects's node_modules folder.
   *
   * When using workspaces, Rush will generate a `common/temp/pnpm-workspace.yaml` file referencing
   * all local projects to install. Rush will also generate a `.pnpmfile.cjs` shim which implements
   * Rush-specific features such as preferred versions.  The user's `common/config/rush/.pnpmfile.cjs`
   * is invoked by the shim.
   *
   * This option is strongly recommended. The default value is false.
   */
  "useWorkspaces": true,

  /**
   * This setting determines how PNPM chooses version numbers during `rush update`.
   * For example, suppose `lib-x@3.0.0` depends on `"lib-y": "^1.2.3"` whose latest major
   * releases are `1.8.9` and `2.3.4`.  The resolution mode `lowest-direct` might choose
   * `lib-y@1.2.3`, wheres `highest` will choose 1.8.9, and `time-based` will pick the
   * highest compatible version at the time when `lib-x@3.0.0` itself was published (ensuring
   * that the version could have been tested by the maintainer of "lib-x").  For local workspace
   * projects, `time-based` instead works like `lowest-direct`, avoiding upgrades unless
   * they are explicitly requested. Although `time-based` is the most robust option, it may be
   * slightly slower with registries such as npmjs.com that have not implemented an optimization.
   *
   * IMPORTANT: Be aware that PNPM 8.0.0 initially defaulted to `lowest-direct` instead of
   * `highest`, but PNPM reverted this decision in 8.6.12 because it caused confusion for users.
   * Rush version 5.106.0 and newer avoids this confusion by consistently defaulting to
   * `highest` when `resolutionMode` is not explicitly set in pnpm-config.json or .npmrc,
   * regardless of your PNPM version.
   *
   * PNPM documentation: https://pnpm.io/npmrc#resolution-mode
   *
   * Possible values are: `highest`, `time-based`, and `lowest-direct`.
   * The default is `highest`.
   */
  // "resolutionMode": "time-based",

  /**
   * If true, then Rush will add the `--strict-peer-dependencies` command-line parameter when
   * invoking PNPM.  This causes `rush update` to fail if there are unsatisfied peer dependencies,
   * which is an invalid state that can cause build failures or incompatible dependency versions.
   * (For historical reasons, JavaScript package managers generally do not treat this invalid
   * state as an error.)
   *
   * PNPM documentation: https://pnpm.io/npmrc#strict-peer-dependencies
   *
   * The default value is false to avoid legacy compatibility issues.
   * It is strongly recommended to set `strictPeerDependencies=true`.
   */
  // "strictPeerDependencies": true,

  /**
   * Environment variables that will be provided to PNPM.
   */
  // "environmentVariables": {
  //   "NODE_OPTIONS": {
  //     "value": "--max-old-space-size=4096",
  //     "override": false
  //   }
  // },

  /**
   * Specifies the location of the PNPM store.  There are two possible values:
   *
   * - `local` - use the `pnpm-store` folder in the current configured temp folder:
   *   `common/temp/pnpm-store` by default.
   * - `global` - use PNPM's global store, which has the benefit of being shared
   *    across multiple repo folders, but the disadvantage of less isolation for builds
   *    (for example, bugs or incompatibilities when two repos use different releases of PNPM)
   *
   * In both cases, the store path can be overridden by the environment variable `RUSH_PNPM_STORE_PATH`.
   *
   * The default value is `local`.
   */
  // "pnpmStore": "global",

  /**
   * If true, then `rush install` will report an error if manual modifications
   * were made to the PNPM shrinkwrap file without running `rush update` afterwards.
   *
   * This feature protects against accidental inconsistencies that may be introduced
   * if the PNPM shrinkwrap file (`pnpm-lock.yaml`) is manually edited.  When this
   * feature is enabled, `rush update` will append a hash to the file as a YAML comment,
   * and then `rush update` and `rush install` will validate the hash.  Note that this
   * does not prohibit manual modifications, but merely requires `rush update` be run
   * afterwards, ensuring that PNPM can report or repair any potential inconsistencies.
   *
   * To temporarily disable this validation when invoking `rush install`, use the
   * `--bypass-policy` command-line parameter.
   *
   * The default value is false.
   */
  // "preventManualShrinkwrapChanges": true,

  /**
   * The "globalOverrides" setting provides a simple mechanism for overriding version selections
   * for all dependencies of all projects in the monorepo workspace.  The settings are copied
   * into the `pnpm.overrides` field of the `common/temp/package.json` file that is generated
   * by Rush during installation.
   *
   * Order of precedence: `.pnpmfile.cjs` has the highest precedence, followed by
   * `unsupportedPackageJsonSettings`, `globalPeerDependencyRules`, `globalPackageExtensions`,
   * and `globalOverrides` has lowest precedence.
   *
   * PNPM documentation: https://pnpm.io/package_json#pnpmoverrides
   */
  "globalOverrides": {
    // "example1": "^1.0.0",
    // "example2": "npm:@company/example2@^1.0.0"
  },

  /**
   * The `globalPeerDependencyRules` setting provides various settings for suppressing validation errors
   * that are reported during installation with `strictPeerDependencies=true`.  The settings are copied
   * into the `pnpm.peerDependencyRules` field of the `common/temp/package.json` file that is generated
   * by Rush during installation.
   *
   * Order of precedence: `.pnpmfile.cjs` has the highest precedence, followed by
   * `unsupportedPackageJsonSettings`, `globalPeerDependencyRules`, `globalPackageExtensions`,
   * and `globalOverrides` has lowest precedence.
   *
   * https://pnpm.io/package_json#pnpmpeerdependencyrules
   */
  "globalPeerDependencyRules": {
    // "ignoreMissing": ["@eslint/*"],
    // "allowedVersions": { "react": "17" },
    // "allowAny": ["@babel/*"]
  },

  /**
   * The `globalPackageExtension` setting provides a way to patch arbitrary package.json fields
   * for any PNPM dependency of the monorepo.  The settings are copied into the `pnpm.packageExtensions`
   * field of the `common/temp/package.json` file that is generated by Rush during installation.
   * The `globalPackageExtension` setting has similar capabilities as `.pnpmfile.cjs` but without
   * the downsides of an executable script (nondeterminism, unreliable caching, performance concerns).
   *
   * Order of precedence: `.pnpmfile.cjs` has the highest precedence, followed by
   * `unsupportedPackageJsonSettings`, `globalPeerDependencyRules`, `globalPackageExtensions`,
   * and `globalOverrides` has lowest precedence.
   *
   * PNPM documentation: https://pnpm.io/package_json#pnpmpackageextensions
   */
  "globalPackageExtensions": {
    // "fork-ts-checker-webpack-plugin": {
    //   "dependencies": {
    //     "@babel/core": "1"
    //   },
    //   "peerDependencies": {
    //     "eslint": ">= 6"
    //   },
    //   "peerDependenciesMeta": {
    //     "eslint": {
    //       "optional": true
    //     }
    //   }
    // }
  },

  /**
   * The `globalNeverBuiltDependencies` setting suppresses the `preinstall`, `install`, and `postinstall`
   * lifecycle events for the specified NPM dependencies.  This is useful for scripts with poor practices
   * such as downloading large binaries without retries or attempting to invoke OS tools such as
   * a C++ compiler.  (PNPM's terminology refers to these lifecycle events as "building" a package;
   * it has nothing to do with build system operations such as `rush build` or `rushx build`.)
   * The settings are copied into the `pnpm.neverBuiltDependencies` field of the `common/temp/package.json`
   * file that is generated by Rush during installation.
   *
   * PNPM documentation: https://pnpm.io/package_json#pnpmneverbuiltdependencies
   */
  "globalNeverBuiltDependencies": [
    // "fsevents"
  ],

  /**
   * The `globalAllowedDeprecatedVersions` setting suppresses installation warnings for package
   * versions that the NPM registry reports as being deprecated.  This is useful if the
   * deprecated package is an indirect dependency of an external package that has not released a fix.
   * The settings are copied into the `pnpm.allowedDeprecatedVersions` field of the `common/temp/package.json`
   * file that is generated by Rush during installation.
   *
   * PNPM documentation: https://pnpm.io/package_json#pnpmalloweddeprecatedversions
   *
   * If you are working to eliminate a deprecated version, it's better to specify `allowedDeprecatedVersions`
   * in the package.json file for individual Rush projects.
   */
  "globalAllowedDeprecatedVersions": {
    // "request": "*"
  },


  /**
   * (THIS FIELD IS MACHINE GENERATED)  The "globalPatchedDependencies" field is updated automatically
   * by the `rush-pnpm patch-commit` command.  It is a dictionary, where the key is an NPM package name
   * and exact version, and the value is a relative path to the associated patch file.
   *
   * PNPM documentation: https://pnpm.io/package_json#pnpmpatcheddependencies
   */
  "globalPatchedDependencies": { },

  /**
   * (USE AT YOUR OWN RISK)  This is a free-form property bag that will be copied into
   * the `common/temp/package.json` file that is generated by Rush during installation.
   * This provides a way to experiment with new PNPM features.  These settings will override
   * any other Rush configuration associated with a given JSON field except for `.pnpmfile.cjs`.
   *
   * USAGE OF THIS SETTING IS NOT SUPPORTED BY THE RUSH MAINTAINERS AND MAY CAUSE RUSH
   * TO MALFUNCTION.  If you encounter a missing PNPM setting that you believe should
   * be supported, please create a GitHub issue or PR.  Note that Rush does not aim to
   * support every possible PNPM setting, but rather to promote a battle-tested installation
   * strategy that is known to provide a good experience for large teams with lots of projects.
   */
  "unsupportedPackageJsonSettings": {
    // "dependencies": {
    //   "not-a-good-practice": "*"
    // },
    // "scripts": {
    //   "do-something": "echo Also not a good practice"
    // },
    // "pnpm": { "futurePnpmFeature": true }
  }
}
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/pnpmfile_cjs/index.html b/pages/configs/pnpmfile_cjs/index.html index dcbcbcb5..44eabb0c 100644 --- a/pages/configs/pnpmfile_cjs/index.html +++ b/pages/configs/pnpmfile_cjs/index.html @@ -6,14 +6,14 @@ .pnpmfile.cjs | Rush - +
Rush StackShopBlogEvents

.pnpmfile.cjs

This is the template that rush init generates for the monorepo pnpmfile.js file:

common/config/rush/.pnpmfile.cjs

'use strict';

/**
 * When using the PNPM package manager, you can use pnpmfile.js to workaround
 * dependencies that have mistakes in their package.json file.  (This feature is
 * functionally similar to Yarn's "resolutions".)
 *
 * For details, see the PNPM documentation:
 * https://pnpm.js.org/docs/en/hooks.html
 *
 * IMPORTANT: SINCE THIS FILE CONTAINS EXECUTABLE CODE, MODIFYING IT IS LIKELY TO INVALIDATE
 * ANY CACHED DEPENDENCY ANALYSIS.  After any modification to pnpmfile.js, it's recommended to run
 * "rush update --full" so that PNPM will recalculate all version selections.
 */
module.exports = {
  hooks: {
    readPackage
  }
};

/**
 * This hook is invoked during installation before a package's dependencies
 * are selected.
 * The `packageJson` parameter is the deserialized package.json
 * contents for the package that is about to be installed.
 * The `context` parameter provides a log() function.
 * The return value is the updated object.
 */
function readPackage(packageJson, context) {
  // // The karma types have a missing dependency on typings from the log4js package.
  // if (packageJson.name === '@types/karma') {
  //  context.log('Fixed up dependencies for @types/karma');
  //  packageJson.dependencies['log4js'] = '0.6.38';
  // }

  return packageJson;
}
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/rush-plugin-manifest_json/index.html b/pages/configs/rush-plugin-manifest_json/index.html index b99ce0e1..ae80a0e5 100644 --- a/pages/configs/rush-plugin-manifest_json/index.html +++ b/pages/configs/rush-plugin-manifest_json/index.html @@ -6,14 +6,14 @@ rush-plugin-manifest.json (experimental) | Rush - +
Rush StackShopBlogEvents

rush-plugin-manifest.json (experimental)

This is the template for the rush-plugin-manifest.json file that is used when creating a Rush plugin.

<your plugin project>/rush-plugin-manifest.json

/**
 * This file defines the Rush plugins that are provided by this package.
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugin-manifest.schema.json",

  /**
   * An array of one or more plugin definitions provided by this NPM package.
   *
   * For more granular installations, it is recommended for plugins to be implemented by an
   * NPM package that does try to serve other roles such as providing APIs or command-line binaries.
   * The package name should start with "rush-".  The name should end with "-plugin" or "-plugins".
   * For example: "@scope/rush-business-policy-plugin"
   */
  "plugins": [
    {
      /**
       * (Required) The name of the plugin.  The plugin name must be comprised of letters and numbers
       * forming one or more words that are separated by hyphens.  Note that if the plugin has a
       * JSON config file, that filename will be the same as the plugin name.  See "optionsSchema" below
       * for details.
       *
       * If the manifest defines exactly one plugin, then it is suggested to reuse the name from the
       * NPM package.  For example, if the NPM package is "@scope/rush-business-policy-plugin"
       * then the plugin name might be "business-policy" and with config file "business-policy.json".
       */
      "pluginName": "example",

      /**
       * (Required) Provide some documentation that summarizes the problem solved by this plugin,
       * how to invoke it, and what operations it performs.
       */
      "description": "An example plugin",

      /**
       * (Optional) A path to a JavaScript code module that implements the "IRushPlugin" interface.
       * This module can use the "@rushstack/rush-sdk" API to register handlers for Rush events
       * and services.  The module path is relative to the folder containing the "package.json" file.
       */
      // "entryPoint": "lib/example/RushExamplePlugin.js",

      /**
       * (Optional) A path to a "command-line.json" file that defines Rush command line actions
       * and parameters contributed by this plugin.  This config file has the same JSON schema
       * as Rush's "common/config/rush/command-line.json" file.
       */
      // "commandLineJsonFilePath": "lib/example/command-line.json",

      /**
       * (Optional) A path to a JSON schema for validating the config file that end users can
       * create to customize this plugin's behavior.  Plugin config files are stored in the folder
       * "common/config/rush-plugins/" with a filename corresponding to the "pluginName" field
       * from the manifest.  For example: "common/config/rush-plugins/business-policy.json"
       * whose schema is "business-policy.schema.json".
       */
      // "optionsSchema": "lib/example/example.schema.json",

      /**
       * (Optional) A list of associated Rush command names such as "build" from "rush build".
       * If specified, then the plugin's "entryPoint" code module be loaded only if
       * one of the specified commands is invoked.  This improves performance by avoiding
       * loading the code module when it is not needed.  If "associatedCommands" is
       * not specified, then the code module will always be loaded.
       */
      // "associatedCommands": [ "build" ]
    }
  ]
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/rush-plugins_json/index.html b/pages/configs/rush-plugins_json/index.html index 90b8e7ff..5e845181 100644 --- a/pages/configs/rush-plugins_json/index.html +++ b/pages/configs/rush-plugins_json/index.html @@ -6,14 +6,14 @@ rush-plugins.json (experimental) | Rush - +
Rush StackShopBlogEvents

rush-plugins.json (experimental)

This is the template for the rush-plugins.json file that is used to enable Rush plugins.

common/config/rush/command-line.json

/**
 * This configuration file manages Rush's plugin feature.
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugins.schema.json",
  "plugins": [
    /**
     * Each item configures a plugin to be loaded by Rush.
     */
    // {
    //   /**
    //    * The name of the NPM package that provides the plugin.
    //    */
    //   "packageName": "@scope/my-rush-plugin",
    //   /**
    //    * The name of the plugin.  This can be found in the "pluginName"
    //    * field of the "rush-plugin-manifest.json" file in the NPM package folder.
    //    */
    //   "pluginName": "my-plugin-name",
    //   /**
    //    * The name of a Rush autoinstaller that will be used for installation, which
    //    * can be created using "rush init-autoinstaller".  Add the plugin's NPM package
    //    * to the package.json "dependencies" of your autoinstaller, then run
    //    * "rush update-autoinstaller".
    //    */
    //   "autoinstallerName": "rush-plugins"
    // }
  ]
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/rush-project_json/index.html b/pages/configs/rush-project_json/index.html index 09a2e7b9..41012626 100644 --- a/pages/configs/rush-project_json/index.html +++ b/pages/configs/rush-project_json/index.html @@ -6,14 +6,14 @@ rush-project.json | Rush - +
Rush StackShopBlogEvents

rush-project.json

This is the template for the optional rush-project.json config file. This file may be provided by a rig package.

<your project>/config/rush-project.json

/**
 * The "config/rush-project.json" file configures Rush-specific settings for an individual project
 * in a Rush monorepo.  More documentation is available on the Rush website: https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-project.schema.json",

  /**
   * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
   * settings to be shared across multiple projects.
   */
  // "extends": "my-rig/profiles/default/config/rush-project.json",

  /**
   * The incremental analyzer can skip Rush commands for projects whose input files have not changed since
   * the last build.  Normally, every Git-tracked file under the project folder is assumed to be an input.
   * Use "incrementalBuildIgnoredGlobs" to ignore specific files, specified as globs relative to
   * the project folder.  The glob syntax is based on the .gitignore file format.
   */
  "incrementalBuildIgnoredGlobs": [
    // "etc/api-report/*.md"
  ],

  /**
   * Disable caching for this project. The project will never be restored from cache. This may be useful
   * if this project affects state outside of its folder.
   *
   * Default value: false
   */
  // "disableBuildCacheForProject": true,

  /**
   * Options for individual commands and phases.
   */
  "operationSettings": [
    // {
    //   /**
    //    * (Required) The name of the operation.
    //    * This should be a key in the "package.json" file's "scripts" section.
    //    */
    //   "operationName": "build",
    //
    //   /**
    //    * Specify the folders where this operation writes its output files.  If enabled, the Rush build cache
    //    * will restore these folders from the cache.  The strings are folder names under the project root folder.
    //    * These folders should not be tracked by Git.  They must not contain symlinks.
    //    */
    //   "outputFolderNames": [
    //     "lib", "dist"
    //   ],
    //
    //   /**
    //    * Specify a list of glob (minimatch) paths (absolute or relative) pointing to files
    //    * (within or outside the .git repository) that affect the output of this operation.
    //    * If provided, the hash values of these files will become part of the final hash when
    //    * reading and writing from cache.
    //    */
    //   "dependsOnAdditionalFiles": [],
    //
    //   /**
    //    * Specify a list of environment variables that affect the output of this operation.
    //    * If provided, the values of these variables will become part of the hash when reading
    //    * and writing from cache.
    //    */
    //   "dependsOnEnvVars": [ "MY_ENVIRONMENT_VARIABLE" ],
    //
    //   /**
    //    * Disable caching for this operation.  The operation will never be restored from cache.
    //    * This may be useful if this operation affects state outside of its folder.
    //    */
    //   // "disableBuildCacheForOperation": true
    // }
  ]
}

See also​

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/rush_json/index.html b/pages/configs/rush_json/index.html index 7ec1f5f9..1962fe52 100644 --- a/pages/configs/rush_json/index.html +++ b/pages/configs/rush_json/index.html @@ -6,14 +6,14 @@ rush.json | Rush - +
Rush StackShopBlogEvents

rush.json

This is the template that rush init generates for rush.json (in the repo root folder):

<repo root>rush.json

/**
 * This is the main configuration file for Rush.
 * For full documentation, please see https://rushjs.io
 */
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush.schema.json",

  /**
   * (Required) This specifies the version of the Rush engine to be used in this repo.
   * Rush's "version selector" feature ensures that the globally installed tool will
   * behave like this release, regardless of which version is installed globally.
   *
   * The common/scripts/install-run-rush.js automation script also uses this version.
   *
   * NOTE: If you upgrade to a new major version of Rush, you should replace the "v5"
   * path segment in the "$schema" field for all your Rush config files.  This will ensure
   * correct error-underlining and tab-completion for editors such as VS Code.
   */
  "rushVersion": "5.82.1",

  /**
   * The next field selects which package manager should be installed and determines its version.
   * Rush installs its own local copy of the package manager to ensure that your build process
   * is fully isolated from whatever tools are present in the local environment.
   *
   * Specify one of: "pnpmVersion", "npmVersion", or "yarnVersion".  See the Rush documentation
   * for details about these alternatives.
   */
  "pnpmVersion": "6.7.1",

  // "npmVersion": "6.14.15",
  // "yarnVersion": "1.9.4",

  /**
   * Older releases of the Node.js engine may be missing features required by your system.
   * Other releases may have bugs.  In particular, the "latest" version will not be a
   * Long Term Support (LTS) version and is likely to have regressions.
   *
   * Specify a SemVer range to ensure developers use a Node.js version that is appropriate
   * for your repo.
   *
   * LTS schedule: https://nodejs.org/en/about/releases/
   * LTS versions: https://nodejs.org/en/download/releases/
   */
  "nodeSupportedVersionRange": ">=12.13.0 <13.0.0 || >=14.15.0 <15.0.0 || >=16.13.0 <17.0.0",

  /**
   * Odd-numbered major versions of Node.js are experimental.  Even-numbered releases
   * spend six months in a stabilization period before the first Long Term Support (LTS) version.
   * For example, 8.9.0 was the first LTS version of Node.js 8.  Pre-LTS versions are not recommended
   * for production usage because they frequently have bugs.  They may cause Rush itself
   * to malfunction.
   *
   * Rush normally prints a warning if it detects a pre-LTS Node.js version.  If you are testing
   * pre-LTS versions in preparation for supporting the first LTS version, you can use this setting
   * to disable Rush's warning.
   */
  // "suppressNodeLtsWarning": false,

  /**
   * If you would like the version specifiers for your dependencies to be consistent, then
   * uncomment this line. This is effectively similar to running "rush check" before any
   * of the following commands:
   *
   *   rush install, rush update, rush link, rush version, rush publish
   *
   * In some cases you may want this turned on, but need to allow certain packages to use a different
   * version. In those cases, you will need to add an entry to the "allowedAlternativeVersions"
   * section of the common-versions.json.
   */
  // "ensureConsistentVersions": true,

  /**
   * Large monorepos can become intimidating for newcomers if project folder paths don't follow
   * a consistent and recognizable pattern.  When the system allows nested folder trees,
   * we've found that teams will often use subfolders to create islands that isolate
   * their work from others ("shipping the org").  This hinders collaboration and code sharing.
   *
   * The Rush developers recommend a "category folder" model, where buildable project folders
   * must always be exactly two levels below the repo root.  The parent folder acts as the category.
   * This provides a basic facility for grouping related projects (e.g. "apps", "libraries",
   * "tools", "prototypes") while still encouraging teams to organize their projects into
   * a unified taxonomy.  Limiting to 2 levels seems very restrictive at first, but if you have
   * 20 categories and 20 projects in each category, this scheme can easily accommodate hundreds
   * of projects.  In practice, you will find that the folder hierarchy needs to be rebalanced
   * occasionally, but if that's painful, it's a warning sign that your development style may
   * discourage refactoring.  Reorganizing the categories should be an enlightening discussion
   * that brings people together, and maybe also identifies poor coding practices (e.g. file
   * references that reach into other project's folders without using Node.js module resolution).
   *
   * The defaults are projectFolderMinDepth=1 and projectFolderMaxDepth=2.
   *
   * To remove these restrictions, you could set projectFolderMinDepth=1
   * and set projectFolderMaxDepth to a large number.
   */
  // "projectFolderMinDepth": 2,
  // "projectFolderMaxDepth": 2,

  /**
   * Today the npmjs.com registry enforces fairly strict naming rules for packages, but in the early
   * days there was no standard and hardly any enforcement.  A few large legacy projects are still using
   * nonstandard package names, and private registries sometimes allow it.  Set "allowMostlyStandardPackageNames"
   * to true to relax Rush's enforcement of package names.  This allows upper case letters and in the future may
   * relax other rules, however we want to minimize these exceptions.  Many popular tools use certain punctuation
   * characters as delimiters, based on the assumption that they will never appear in a package name; thus if we relax
   * the rules too much it is likely to cause very confusing malfunctions.
   *
   * The default value is false.
   */
  // "allowMostlyStandardPackageNames": true,

  /**
   * This feature helps you to review and approve new packages before they are introduced
   * to your monorepo.  For example, you may be concerned about licensing, code quality,
   * performance, or simply accumulating too many libraries with overlapping functionality.
   * The approvals are tracked in two config files "browser-approved-packages.json"
   * and "nonbrowser-approved-packages.json".  See the Rush documentation for details.
   */
  // "approvedPackagesPolicy": {
  //   /**
  //    * The review categories allow you to say for example "This library is approved for usage
  //    * in prototypes, but not in production code."
  //    *
  //    * Each project can be associated with one review category, by assigning the "reviewCategory" field
  //    * in the "projects" section of rush.json.  The approval is then recorded in the files
  //    * "common/config/rush/browser-approved-packages.json" and "nonbrowser-approved-packages.json"
  //    * which are automatically generated during "rush update".
  //    *
  //    * Designate categories with whatever granularity is appropriate for your review process,
  //    * or you could just have a single category called "default".
  //    */
  //   "reviewCategories": [
  //     // Some example categories:
  //     "production", // projects that ship to production
  //     "tools",      // non-shipping projects that are part of the developer toolchain
  //     "prototypes"  // experiments that should mostly be ignored by the review process
  //   ],
  //
  //   /**
  //    * A list of NPM package scopes that will be excluded from review.
  //    * We recommend to exclude TypeScript typings (the "@types" scope), because
  //    * if the underlying package was already approved, this would imply that the typings
  //    * are also approved.
  //    */
  //   // "ignoredNpmScopes": ["@types"]
  // },

  /**
   * If you use Git as your version control system, this section has some additional
   * optional features you can use.
   */
  "gitPolicy": {
    /**
     * Work at a big company?  Tired of finding Git commits at work with unprofessional Git
     * emails such as "beer-lover@my-college.edu"?  Rush can validate people's Git email address
     * before they get started.
     *
     * Define a list of regular expressions describing allowable e-mail patterns for Git commits.
     * They are case-insensitive anchored JavaScript RegExps.  Example: ".*@example\.com"
     *
     * IMPORTANT: Because these are regular expressions encoded as JSON string literals,
     * RegExp escapes need two backslashes, and ordinary periods should be "\\.".
     */
    // "allowedEmailRegExps": [
    //   "[^@]+@users\\.noreply\\.github\\.com",
    //   "rush-bot@example\\.org"
    // ],

    /**
     * When Rush reports that the address is malformed, the notice can include an example
     * of a recommended email.  Make sure it conforms to one of the allowedEmailRegExps
     * expressions.
     */
    // "sampleEmail": "example@users.noreply.github.com",

    /**
     * The commit message to use when committing changes during 'rush publish'.
     *
     * For example, if you want to prevent these commits from triggering a CI build,
     * you might configure your system's trigger to look for a special string such as "[skip-ci]"
     * in the commit message, and then customize Rush's message to contain that string.
     */
    // "versionBumpCommitMessage": "Bump versions [skip ci]",

    /**
     * The commit message to use when committing changes during 'rush version'.
     *
     * For example, if you want to prevent these commits from triggering a CI build,
     * you might configure your system's trigger to look for a special string such as "[skip-ci]"
     * in the commit message, and then customize Rush's message to contain that string.
     */
    // "changeLogUpdateCommitMessage": "Update changelogs [skip ci]",

    /**
     * The commit message to use when commiting changefiles during 'rush change --commit'
     *
     * If no commit message is set it will default to 'Rush change'
     */
     // "changefilesCommitMessage": "Rush change"
  },

  "repository": {
    /**
     * The URL of this Git repository, used by "rush change" to determine the base branch for your PR.
     *
     * The "rush change" command needs to determine which files are affected by your PR diff.
     * If you merged or cherry-picked commits from the main branch into your PR branch, those commits
     * should be excluded from this diff (since they belong to some other PR).  In order to do that,
     * Rush needs to know where to find the base branch for your PR.  This information cannot be
     * determined from Git alone, since the "pull request" feature is not a Git concept.  Ideally
     * Rush would use a vendor-specific protocol to query the information from GitHub, Azure DevOps, etc.
     * But to keep things simple, "rush change" simply assumes that your PR is against the "main" branch
     * of the Git remote indicated by the repository.url setting in rush.json.  If you are working in
     * a GitHub "fork" of the real repo, this setting will be different from the repository URL of your
     * your PR branch, and in this situation "rush change" will also automatically invoke "git fetch"
     * to retrieve the latest activity for the remote main branch.
     */
    // "url": "https://github.com/microsoft/rush-example",

    /**
     * The default branch name. This tells "rush change" which remote branch to compare against.
     * The default value is "main"
     */
    // "defaultBranch": "main",

    /**
     * The default remote. This tells "rush change" which remote to compare against if the remote URL is
     * not set or if a remote matching the provided remote URL is not found.
     */
    // "defaultRemote": "origin"
  },

  /**
   * Event hooks are customized script actions that Rush executes when specific events occur
   */
  "eventHooks": {
    /**
     * The list of shell commands to run before the Rush installation starts
     */
    "preRushInstall": [
      // "common/scripts/pre-rush-install.js"
    ],

    /**
     * The list of shell commands to run after the Rush installation finishes
     */
    "postRushInstall": [],

    /**
     * The list of shell commands to run before the Rush build command starts
     */
    "preRushBuild": [],

    /**
     * The list of shell commands to run after the Rush build command finishes
     */
    "postRushBuild": []
  },

  /**
   * Installation variants allow you to maintain a parallel set of configuration files that can be
   * used to build the entire monorepo with an alternate set of dependencies.  For example, suppose
   * you upgrade all your projects to use a new release of an important framework, but during a transition period
   * you intend to maintain compatibility with the old release.  In this situation, you probably want your
   * CI validation to build the entire repo twice: once with the old release, and once with the new release.
   *
   * Rush "installation variants" correspond to sets of config files located under this folder:
   *
   *   common/config/rush/variants/<variant_name>
   *
   * The variant folder can contain an alternate common-versions.json file.  Its "preferredVersions" field can be used
   * to select older versions of dependencies (within a loose SemVer range specified in your package.json files).
   * To install a variant, run "rush install --variant <variant_name>".
   *
   * For more details and instructions, see this article:  https://rushjs.io/pages/advanced/installation_variants/
   */
  "variants": [
    // {
    //   /**
    //    * The folder name for this variant.
    //    */
    //   "variantName": "old-sdk",
    //
    //   /**
    //    * An informative description
    //    */
    //   "description": "Build this repo using the previous release of the SDK"
    // }
  ],

  /**
   * Rush can collect anonymous telemetry about everyday developer activity such as
   * success/failure of installs, builds, and other operations.  You can use this to identify
   * problems with your toolchain or Rush itself.  THIS TELEMETRY IS NOT SHARED WITH MICROSOFT.
   * It is written into JSON files in the common/temp folder.  It's up to you to write scripts
   * that read these JSON files and do something with them.  These scripts are typically registered
   * in the "eventHooks" section.
   */
  // "telemetryEnabled": false,

  /**
   * Allows creation of hotfix changes. This feature is experimental so it is disabled by default.
   * If this is set, 'rush change' only allows a 'hotfix' change type to be specified. This change type
   * will be used when publishing subsequent changes from the monorepo.
   */
  // "hotfixChangeEnabled": false,

  /**
    * This is an optional, but recommended, list of allowed tags that can be applied to Rush projects
    * using the "tags" setting in this file.  This list is useful for preventing mistakes such as misspelling,
    * and it also provides a centralized place to document your tags.  If "allowedProjectTags" list is
    * not specified, then any valid tag is allowed.  A tag name must be one or more words
    * separated by hyphens or slashes, where a word may contain lowercase ASCII letters, digits,
    * ".", and "@" characters.
    */
  // "allowedProjectTags": [ "tools", "frontend-team", "1.0.0-release" ],

  /**
   * (Required) This is the inventory of projects to be managed by Rush.
   *
   * Rush does not automatically scan for projects using wildcards, for a few reasons:
   * 1. Depth-first scans are expensive, particularly when tools need to repeatedly collect the list.
   * 2. On a caching CI machine, scans can accidentally pick up files left behind from a previous build.
   * 3. It's useful to have a centralized inventory of all projects and their important metadata.
   */
  "projects": [
    // {
    //   /**
    //    * The NPM package name of the project (must match package.json)
    //    */
    //   "packageName": "my-app",
    //
    //   /**
    //    * The path to the project folder, relative to the rush.json config file.
    //    */
    //   "projectFolder": "apps/my-app",
    //
    //   /**
    //    * An optional category for usage in the "browser-approved-packages.json"
    //    * and "nonbrowser-approved-packages.json" files.  The value must be one of the
    //    * strings from the "reviewCategories" defined above.
    //    */
    //   "reviewCategory": "production",
    //
    //   /**
    //    * A list of Rush project names that are to be installed from NPM
    //    * instead of linking to the local project.
    //    *
    //    * If a project's package.json specifies a dependency that is another Rush project
    //    * in the monorepo workspace, normally Rush will locally link its folder instead of
    //    * installing from NPM.  If you are using PNPM workspaces, this is indicated by
    //    * a SemVer range such as "workspace:^1.2.3".  To prevent mistakes, Rush reports
    //    * an error if the "workspace:" protocol is missing.
    //    *
    //    * Locally linking ensures that regressions are caught as early as possible and is
    //    * a key benefit of monorepos.  However there are occasional situations where
    //    * installing from NPM is needed.  A classic example is a cyclic dependency.
    //    * Imagine three Rush projects: "my-toolchain" depends on "my-tester", which depends
    //    * on "my-library".  Suppose that we add "my-toolchain" to the "devDependencies"
    //    * of "my-library" so it can be built by our toolchain.  This cycle creates
    //    * a problem -- Rush can't build a project using a not-yet-built dependency.
    //    * We can solve it by adding "my-toolchain" to the "decoupledLocalDependencies"
    //    * of "my-library", so it builds using the last published release.  Choose carefully
    //    * which package to decouple; some choices are much easier to manage than others.
    //    *
    //    * (In older Rush releases, this setting was called "cyclicDependencyProjects".)
    //    */
    //   "decoupledLocalDependencies": [
    //     // "my-toolchain"
    //   ],
    //
    //   /**
    //    * If true, then this project will be ignored by the "rush check" command.
    //    * The default value is false.
    //    */
    //   // "skipRushCheck": false,
    //
    //   /**
    //    * A flag indicating that changes to this project will be published to npm, which affects
    //    * the Rush change and publish workflows. The default value is false.
    //    * NOTE: "versionPolicyName" and "shouldPublish" are alternatives; you cannot specify them both.
    //    */
    //   // "shouldPublish": false,
    //
    //   /**
    //    * Facilitates postprocessing of a project's files prior to publishing.
    //    *
    //    * If specified, the "publishFolder" is the relative path to a subfolder of the project folder.
    //    * The "rush publish" command will publish the subfolder instead of the project folder.  The subfolder
    //    * must contain its own package.json file, which is typically a build output.
    //    */
    //   // "publishFolder": "temp/publish",
    //
    //   /**
    //    * An optional version policy associated with the project.  Version policies are defined
    //    * in "version-policies.json" file.  See the "rush publish" documentation for more info.
    //    * NOTE: "versionPolicyName" and "shouldPublish" are alternatives; you cannot specify them both.
    //    */
    //   // "versionPolicyName": "",
    //
    //   /**
    //    * An optional set of custom tags that can be used to select this project.  For example,
    //    * adding "my-custom-tag" will allow this project to be selected by the
    //    * command "rush list --only tag:my-custom-tag".  The tag name must be one or more words
    //    * separated by hyphens or slashes, where a word may contain lowercase ASCII letters, digits,
    //    * ".", and "@" characters.
    //    */
    //   // "tags": [ "1.0.0-release", "frontend-team" ]
    // },
    //
    // {
    //   "packageName": "my-controls",
    //   "projectFolder": "libraries/my-controls",
    //   "reviewCategory": "production",
    //   "tags": [ "frontend-team" ]
    // },
    //
    // {
    //   "packageName": "my-toolchain",
    //   "projectFolder": "tools/my-toolchain",
    //   "reviewCategory": "tools",
    //   "tags": [ "tools" ]
    // }
  ]
}
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/version-policies_json/index.html b/pages/configs/version-policies_json/index.html index 4e033cd0..5d1bb7bf 100644 --- a/pages/configs/version-policies_json/index.html +++ b/pages/configs/version-policies_json/index.html @@ -6,14 +6,14 @@ version-policies.json | Rush - +
Rush StackShopBlogEvents

version-policies.json

This is the template that rush init generates for version-policies.json:

common/config/rush/version-policies.json

/**
 * This is configuration file is used for advanced publishing configurations with Rush.
 * More documentation is available on the Rush website: https://rushjs.io
 */

/**
 * A list of version policy definitions.  A "version policy" is a custom package versioning
 * strategy that affects "rush change", "rush version", and "rush publish".  The strategy applies
 * to a set of projects that are specified using the "versionPolicyName" field in rush.json.
 */
[
  // {
  //   /**
  //    * (Required) Indicates the kind of version policy being defined ("lockStepVersion" or "individualVersion").
  //    *
  //    * The "lockStepVersion" mode specifies that the projects will use "lock-step versioning".  This
  //    * strategy is appropriate for a set of packages that act as selectable components of a
  //    * unified product.  The entire set of packages are always published together, and always share
  //    * the same NPM version number.  When the packages depend on other packages in the set, the
  //    * SemVer range is usually restricted to a single version.
  //    */
  //   "definitionName": "lockStepVersion",
  //
  //   /**
  //    * (Required) The name that will be used for the "versionPolicyName" field in rush.json.
  //    * This name is also used command-line parameters such as "--version-policy"
  //    * and "--to-version-policy".
  //    */
  //   "policyName": "MyBigFramework",
  //
  //   /**
  //    * (Required) The current version.  All packages belonging to the set should have this version
  //    * in the current branch.  When bumping versions, Rush uses this to determine the next version.
  //    * (The "version" field in package.json is NOT considered.)
  //    */
  //   "version": "1.0.0",
  //
  //   /**
  //    * (Required) The type of bump that will be performed when publishing the next release.
  //    * When creating a release branch in Git, this field should be updated according to the
  //    * type of release.
  //    *
  //    * Valid values are: "prerelease", "release", "minor", "patch", "major"
  //    */
  //   "nextBump": "prerelease",
  //
  //   /**
  //    * (Optional) If specified, all packages in the set share a common CHANGELOG.md file.
  //    * This file is stored with the specified "main" project, which must be a member of the set.
  //    *
  //    * If this field is omitted, then a separate CHANGELOG.md file will be maintained for each
  //    * package in the set.
  //    */
  //   "mainProject": "my-app",
  //
  //   /**
  //    * (Optional) If enabled, the "rush change" command will prompt the user for their email address
  //    * and include it in the JSON change files.  If an organization maintains multiple repos, tracking
  //    * this contact information may be useful for a service that automatically upgrades packages and
  //    * needs to notify engineers whose change may be responsible for a downstream build break.  It might
  //    * also be useful for crediting contributors.  Rush itself does not do anything with the collected
  //    * email addresses.  The default value is "false".
  //    */
  //   // "includeEmailInChangeFile": true
  // },
  //
  // {
  //   /**
  //    * (Required) Indicates the kind of version policy being defined ("lockStepVersion" or "individualVersion").
  //    *
  //    * The "individualVersion" mode specifies that the projects will use "individual versioning".
  //    * This is the typical NPM model where each package has an independent version number
  //    * and CHANGELOG.md file.  Although a single CI definition is responsible for publishing the
  //    * packages, they otherwise don't have any special relationship.  The version bumping will
  //    * depend on how developers answer the "rush change" questions for each package that
  //    * is changed.
  //    */
  //   "definitionName": "individualVersion",
  //
  //   "policyName": "MyRandomLibraries",
  //
  //   /**
  //    * (Optional) This can be used to enforce that all packages in the set must share a common
  //    * major version number, e.g. because they are from the same major release branch.
  //    * It can also be used to discourage people from accidentally making "MAJOR" SemVer changes
  //    * inappropriately.  The minor/patch version parts will be bumped independently according
  //    * to the types of changes made to each project, according to the "rush change" command.
  //    */
  //   "lockedMajor": 3,
  //
  //   /**
  //    * (Optional) When publishing is managed by Rush, by default the "rush change" command will
  //    * request changes for any projects that are modified by a pull request. These change entries
  //    * will produce a CHANGELOG.md file. If you author your CHANGELOG.md manually or announce updates
  //    * in some other way, set "exemptFromRushChange" to true to tell "rush change" to ignore the projects
  //    * belonging to this version policy.
  //    */
  //   "exemptFromRushChange": false,
  //
  //   // "includeEmailInChangeFile": true
  // }
];
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/configs/version_policies_json/index.html b/pages/configs/version_policies_json/index.html index 112238e5..5ccd6e84 100644 --- a/pages/configs/version_policies_json/index.html +++ b/pages/configs/version_policies_json/index.html @@ -6,13 +6,13 @@ version_policies_json | Rush - +
Rush StackShopBlogEvents

Redirecting...

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/contributing/index.html b/pages/contributing/index.html index 9d3557a0..9da7ba03 100644 --- a/pages/contributing/index.html +++ b/pages/contributing/index.html @@ -6,7 +6,7 @@ Contributing | Rush - + @@ -15,7 +15,7 @@ rushstack-websites GitHub repo.

For general instructions for building Rush and guidelines for submitting PRs, please read the Contributing documentation for the Rush Stack monorepo.

The relevant monorepo project folders are:

  • apps/rush - the command line interface front end
  • libraries/rush-lib - the automation API and "engine" where all the logic is implemented

Testing Rush builds​

Once you have coded your fix and built your branch (as described in the general Contributing notes), you will want to test your development build of Rush.

Rush features a mechanism called the version selector, which reads rushVersion from rush.json and then automatically installs and invokes that specific version of the engine. Thus if we launch your build of @microsoft/rush, it will not actually run your modified code. To bypass the version selector, we need to invoke the @microsoft/rush-lib engine directly:

cd rushstack/libraries/rush-lib

node ./lib/start.js --help

If you want to make it easy invoke your test build from other locations, we recommend to create a testrush command.

For Bash on Mac OS or Linux:

# Substitute the full path to your own build of rush-lib:
alias testrush="node ~/git/rushstack/libraries/rush-lib/lib/start.js"

For Windows, we might create testrush.cmd and add it to our system PATH:

@ECHO OFF
REM Substitute the full path to your own build of rush-lib:
node "C:\Git\rushstack\apps\rush-lib\lib\start.js" %*

Debugging Rush​

The same approach is used to debug Rush using the VS Code debugger. Create a debugger configuration file like this:

rushstack/libraries/rush-lib/.vscode/launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Rush",
      "program": "${workspaceFolder}/lib/start.js",
      "args": [ "list", "--json" ],  // <====== specify your Rush command line arguments here
      "cwd": "(repo folder that you want to debug)"  // <===== specify your target working folder here
    }
  ]
}

After saving this file, in VS Code click "View" --> "Run" and choose your "Debug Rush" configuration from the list. Then click "Run" --> "Start Debugging" to start debugging. Breakpoints and TypeScript source maps should work correctly.

Building without unit tests​

Rush builds using the Heft toolchain. You can invoke the heft command-line directly for better additional options.

# Full incremental build of Rush and its dependencies, including unit tests
rush build --to rush-lib --verbose

# Do a quick build of "rush-lib" only without unit tests
cd rushstack/libraries/rush-lib

rushx build
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/developer/everyday_commands/index.html b/pages/developer/everyday_commands/index.html index 92b8b100..9e7c2c66 100644 --- a/pages/developer/everyday_commands/index.html +++ b/pages/developer/everyday_commands/index.html @@ -6,13 +6,13 @@ Everyday commands | Rush - +
Rush StackShopBlogEvents

Everyday commands

Your daily workflow only needs a few Rush commands:

rush update​

Remember to run rush update whenever a package.json file has changed. In other words:

  • After pulling new changes from git (e.g. git pull)
  • After manually editing any project's package.json file in any way
  • After editing any common/config files that affect versions (e.g. pnpmfile.js, common-versions.json, etc.)

The rush update operation may change some files under common/config. If so, you should commit those changes to Git and include them in your PR. When in doubt, run rush update -- if everything is already up to date, it won't take any time!

What rush update does:

  1. Rush checks/applies various policies that sometimes update files under common/config.
  2. Rush compares all of your project package.json files against the repository's common shrinkwrap file to see if it's valid.
  3. If it's outdated, the package manager updates the shrinkwrap file.
  4. Either way, the package manager installs all dependencies into the common/temp/node_modules folder.
  5. Finally, Rush constructs a local node_modules folder for each project, by making symlinks into common/temp/node_modules. (This is the same operation as rush link.)

What is this "shrinkwrap file"?

Most projects don't specify an exact version such as 1.2.3 for a dependency, but instead specify SemVer range such as 1.x or ^1.2.3. By itself, this would mean that what gets installed depends on the latest version at the time. Such nondeterminism is bad: It would be maddening for a Git branch that built on Monday to mysteriously be failing on Tuesday because of a new release of a library. The shrinkwrap file solves this problem by storing a complete installation plan in a large file that is tracked by Git.

The shrinkwrap file has different names depending on the package manager that your repo is using: shrinkwrap.yaml, npm-shrinkwrap.json, or yarn.lock

You will notice that automated CI jobs use rush install instead of rush update. The difference is that rush install won't update any files. Instead, it will fail your PR build if something is out of date, to let you know that you forgot to run rush update or forgot to commit the result. (Some people choose to use rush install as their everyday command, in order to catch unintended changes to the shrinkwrap file.)

rush rebuild​

Once you've pulled the latest changes, it's time to compile everything. rush rebuild does a full, clean build of every project in the repository.

If your toolchain supports incremental builds, you can also use rush build to build only the projects that have changed.

rushx​

If you want to build just one project, you can use the rushx command. You run it under the project folder that you want to operate on. The rushx command is analogous to npm run, but with slightly less typing, slightly better error reporting, and command-line help.

rush check​

After editing a package.json file, you can run rush check to see if multiple projects are depending on different versions of the same library. In a monorepo environment, that is undesirable. Many repos will use rush check as a CI build step, so they can fail your PR build if you introduce side-by-side versions.

rush change​

If you work on libraries that get published as NPM packages, your repo probably requires you to include change log entries as part of your PR. You will know because your PR build will fail on the rush change --verify step.

To write change logs, first commit any pending work to Git. Then type rush change from anywhere under your repo working folder. This command will examine your Git history to determine which project folders have diffs. Based on that, it will prompt you to write a change log entry for each one. Each change log entry gets stored in a separate file under common/changes. You should add and commit these files to Git.

Later, Rush's automated publishing workflow will inspect these files to determine which packages need to be published. It will delete the files and copy your messages into the package's CHANGELOG.md file.

👉 See Authoring change logs for tips about writing change logs.

Common scenarios

That's it! Those are all the commonly used Rush commands.

Combining everything, a typical daily incantation might look like this:

# Pull the latest changes from Git
git pull

# Install NPM packages as needed
rush update

# Do a clean rebuild of everything
rush rebuild

# Work on one project
cd ./my-project

# Let's assume there is a "start" script in the package.json.
# (To see the available commands, type "rushx" by itself.)
rushx start
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/developer/modifying_package_json/index.html b/pages/developer/modifying_package_json/index.html index 7ee546c9..ff0c15f3 100644 --- a/pages/developer/modifying_package_json/index.html +++ b/pages/developer/modifying_package_json/index.html @@ -6,7 +6,7 @@ Modifying package.json | Rush - + @@ -20,7 +20,7 @@ rush upgrade-interactive command. It will walk you through selecting projects and choosing which versions to upgrade:

rush upgrade-interactive screenshot

Choosing the project

rush upgrade-interactive screenshot

Choosing the dependencies to upgrade

pnpm outdated​

To create a report about outdated dependencies, you can also use the pnpm outdated command. Note that when invoking PNPM commands in a Rush monorepo, you must use the rush-pnpm CLI helper.

rush-pnpm outdated screenshot

Invoking rush-pnpm outdated

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/developer/new_developer/index.html b/pages/developer/new_developer/index.html index 106ec872..7156f7c9 100644 --- a/pages/developer/new_developer/index.html +++ b/pages/developer/new_developer/index.html @@ -6,13 +6,13 @@ Getting started as a developer | Rush - +
Rush StackShopBlogEvents

Getting started as a developer

Prerequisites​

In order to use Rush, you will need the NodeJS engine. We recommend the latest LTS version, because non-stable NodeJS releases frequently have bugs. You might consider installing via nvm-windows or nvm (Mac/Linux), which allows you to easily switch between different NodeJS versions that might be required for different projects that you work on.

You also need to install the Rush tool itself. It's pretty easy. From your shell or command prompt, type this:

npm install -g @microsoft/rush

NOTE: If this command fails because your user account does not have permissions to access NPM's global folder, you may need to fix your NPM configuration.

To see Rush's command line help, you can type:

rush -h

The command-line help is also published online in the Command Reference.

A couple caveats​

Before we get started, a couple important points to keep in mind:

1. Avoid certain commands in a Rush repo​

Rush optimizes by installing all of your dependency packages in a central folder, and then uses symlinks to create the "node_modules" folder for each of your projects.

Avoid using package manager commands that install/link dependencies. For example, npm run will work fine, but these commands will get confused by Rush's symlinks: npm install, npm update, npm link, npm dedupe, etc. (The same goes for other package managers: Avoid commands such as pnpm install or yarn install.) If you want to use those commands, first run rush unlink to delete the symlinks created by Rush.

If you use git clean -dfx to clean up your folder, be aware that it handles symlinks poorly. To avoid trouble, always run rush unlink before using git clean -dfx.

Afterwards you can run rush update to recreate the symlinks. (There is a standalone rush link command, but it's rarely needed.)

2. If you suspect your install is corrupted...​

Rush's package management commands are "incremental", which means they save time by skipping steps that appear to be unnecessary. Since Rush runs in automated build environments, we have many safeguards to ensure these checks are accurate. However when debugging or tinkering with packages on your local machine, sometimes your NPM "node_modules" folder can get into a bad state, causing strange errors.

If you suspect your install is corrupted, try running rush update --purge. This will force a full reinstall of your packages, and usually get you back into a good state.

© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/developer/other_commands/index.html b/pages/developer/other_commands/index.html index 4d4c5a55..619a4813 100644 --- a/pages/developer/other_commands/index.html +++ b/pages/developer/other_commands/index.html @@ -6,13 +6,13 @@ Other helpful commands | Rush - +
Rush StackShopBlogEvents

Other helpful commands

Installing the latest SemVer-compatible version of everything​

Normally rush update only makes the minimal incremental changes necessary to satisfy the project package.json files. If you want to update everything to the latest version, you would do this:

# This effectively deletes the old shrinkwrap file and re-solves everything
# using the latest compatible versions as specified in package.json files.
# Note that the package.json files themselves are not modified.
rush update --full

For everyday work, --full can introduce unrelated breaks in your PR branch, for example if one of the dependencies didn't perfectly follow the SemVer rules. This isn't too much of a concern for small repos. For a large monorepo, we recommended to use rush update for everyday work, and then run rush update --full periodically as a separate workflow by a CI job or designated person.

Faster ways to build​

  • If you're only working on a few projects: Let's say your Git repo contains 50 projects, but you really only work on the widget and widget-demo projects. You can ask Rush to build only those two projects, plus the libraries that they depend on: rush rebuild --to widget --to widget-demo

  • If you changed a library: Let's say your Git repo contains 50 projects, and you just fixed some bugs in the widget library. You need to run unit tests for all the projects that use this library, and anything that depends on them, but it would be wasteful to rebuild everything else. To rebuild just the downstream projects: rush rebuild --from widget

The full set of project selection parameters are described in the article Selecting subsets of projects.

A faster way to install​

If your repo is using PNPM with the new useWorkspaces=true mode enabled in your rush.json file, you can use a feature called "filtered installs". This feature reduces installation times by only installing the subset of NPM packages required to build a specific project.

For example:

# Only install the NPM packages needed to build "my-project" and the other
# Rush projects that it depends on:
rush install --to my-project

# Like with "rush build", you can use "." to refer to the project from your
# shell's current working directory:
cd my-project
rush install --to .

# Here's how to install dependencies required to do "rush build --from my-project"
rush install --from my-project

Getting back to a clean state​

After working with Rush, maybe you want to get back to a clean state, e.g. so you can zip up a folder. Here's a couple commands to do that:

# Remove all the symlinks created by Rush:
rush unlink

# Remove all the temporary files created by Rush, including deleting all
# the NPM packages that were installed in your common folder:
rush purge
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/developer/project_tags/index.html b/pages/developer/project_tags/index.html index 9b9b2565..c1d3e8e0 100644 --- a/pages/developer/project_tags/index.html +++ b/pages/developer/project_tags/index.html @@ -6,7 +6,7 @@ Using project tags | Rush - + @@ -17,7 +17,7 @@ accidentally misspells a tag, or if they use an old tag that is now obsolete, it may take a while to discover this mistake. You can use the "allowedProjectTags" setting to define a fixed list tags to be used in your monorepo. This also provides a centralized place to document their meanings.

rush.json

  . . .
  /**
    * This is an optional, but recommended, list of allowed tags that can be applied to Rush projects
    * using the "tags" setting in this file.  This list is useful for preventing mistakes such as misspelling,
    * and it also provides a centralized place to document your tags.  If "allowedProjectTags" list is
    * not specified, then any valid tag is allowed.  A tag name must be one or more words
    * separated by hyphens or slashes, where a word may contain lowercase ASCII letters, digits,
    * ".", and "@" characters.
    */
  "allowedProjectTags": [
    // Apply this tag to all Rush projects that are CLI tools
    "tools",

    // Apply this tag to all projects owned by our company's frontend team
    "frontend-team",

    // Use this to tag projects to be included in the QA test pass
    // for the upcoming product launch.
    "1.0.0-release"
  ],  . . .
© 2023 Microsoft
- + \ No newline at end of file diff --git a/pages/developer/selecting_subsets/index.html b/pages/developer/selecting_subsets/index.html index 286c7ae9..39fb5057 100644 --- a/pages/developer/selecting_subsets/index.html +++ b/pages/developer/selecting_subsets/index.html @@ -6,7 +6,7 @@ Selecting subsets of projects | Rush - + @@ -55,7 +55,7 @@ will select A, B, and C
  • Note that Rush does not provide any parameter that would reduce the selection. This is an intentional design choice; in #1241 we'll implement personal tags for building up more complex selections.)

    • Here's a more complex combined command-line:

    rush build --only A --impacted-by-except B --to F

    The projects selected by this example are A, C, D, E, and F:

    rush build --only A --impacted-by-except B --to F

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/developer/tab_completion/index.html b/pages/developer/tab_completion/index.html index 0c6543a4..8fc3fefa 100644 --- a/pages/developer/tab_completion/index.html +++ b/pages/developer/tab_completion/index.html @@ -6,7 +6,7 @@ Configuring tab completion | Rush - + @@ -18,7 +18,7 @@ For more information, see How to create your profile and Profiles and execution policy.

    Add the following code to your profile:

    # PowerShell parameter completion shim for the Rush CLI
    Register-ArgumentCompleter -Native -CommandName rush -ScriptBlock {
      param($commandName, $commandAst, $cursorPosition)
        [string]$value = $commandAst.ToString()
        # Handle input like `rush install; rush bui` + Tab
        [int]$position = [Math]::Min($cursorPosition, $value.Length)

        rush tab-complete --position $position --word "$value" | ForEach-Object {
          [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
     }

    Bash​

    To enable tab completion for Bash, add the following code to your .bashrc file:

    # bash parameter completion for the Rush CLI

    _rush_bash_complete()
    {
      local word=${COMP_WORDS[COMP_CWORD]}

      local completions
      completions="$(rush tab-complete --position "${COMP_POINT}" --word "${COMP_LINE}" 2>/dev/null)"
      if [ $? -ne 0 ]; then
        completions=""
      fi

      COMPREPLY=( $(compgen -W "$completions" -- "$word") )
    }

    complete -f -F _rush_bash_complete rush

    Fish​

    To enable tab completion for Fish shell, add the following code to the file ~/.config/fish/completions/rush.fish:

    # Fish parameter completions for the Rush CLI
    complete rush --no-files

    function __fish_rush
        set -l position (string length (commandline -cp))
        set -l word (commandline -opc)
        rush tab-complete --word "$word" --position "$position"
    end

    complete rush -x -a "(__fish_rush)"
    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/extensibility/api/index.html b/pages/extensibility/api/index.html index b920d444..3cdcff98 100644 --- a/pages/extensibility/api/index.html +++ b/pages/extensibility/api/index.html @@ -6,13 +6,13 @@ The "rush-lib" API | Rush - +
    Rush StackShopBlogEvents

    The "rush-lib" API

    Rush provides an API for use by automation scripts. It is documented in the integrated API reference for all Rush Stack projects:

         API Reference: @microsoft/rush-lib package

    Below are some usage examples.

    Although these code samples are presented as plain JavaScript, we strongly recommend to use TypeScript and model your scripts as regular Rush projects. It is more work to set up initially, but it generally saves time and simplifies maintenance in the long run.

    Reading the rush.json configuration​

    Rather than trying to load rush.json as a JSON file, it is recommended to use the RushConfiguration class which provides a richer set of data views.

    For example, this script will show all the Rush projects and their folders:

    const rushLib = require('@microsoft/rush-lib');

    // loadFromDefaultLocation() will search parent folders to find "rush.json" and then
    // take care of parsing it and loading related config files.
    const rushConfiguration = rushLib.RushConfiguration.loadFromDefaultLocation({
      startingFolder: process.cwd()
    });

    for (const project of rushConfiguration.projects) {
      console.log(project.packageName + ':');
      console.log('  ' + project.projectRelativeFolder);
    }

    Modifying package.json files​

    If you want to modify a package.json file, the PackageJsonEditor class provides helpful validation and normalization:

    const rushLib = require('@microsoft/rush-lib');

    const rushConfiguration = rushLib.RushConfiguration.loadFromDefaultLocation({
      startingFolder: process.cwd()
    });

    // This will find "@rushstack/ts-command-line" in rush.json, without needing to specify the NPM scope
    const project = rushConfiguration.findProjectByShorthandName('ts-command-line');

    // Add lodash as an optional dependency
    project.packageJsonEditor.addOrUpdateDependency('lodash', '4.17.15', 'optionalDependencies');

    // Save the modified package.json file
    project.packageJsonEditor.saveIfModified();

    Generating a README.md summary​

    For a more realistic example, the repo-toolbox/src/ReadmeAction.ts tool uses these APIs to generate the README.md inventory for the Rush Stack monorepo.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/extensibility/creating_plugins/index.html b/pages/extensibility/creating_plugins/index.html index ccc2c77f..c3460fad 100644 --- a/pages/extensibility/creating_plugins/index.html +++ b/pages/extensibility/creating_plugins/index.html @@ -6,7 +6,7 @@ Creating Rush plugins (experimental) | Rush - + @@ -30,7 +30,7 @@ is that the plugin's config file should be stored in the folder common/config/rush-plugins with the same filename as the "pluginName" field from the manifest.

    Here's a complete example of this naming pattern:

    Plugin componentExample naming pattern
    NPM package name:@your-company/rush-policy-plugins
    "pluginName" in rush-plugin-manifest.json:"email-policy"
    end user config file:<repo>/common/config/rush-plugins/email-policy.json
    config file JSON schema:src/schemas/email-policy.schema.json
    code module:src/RushEmailPolicyPlugin.ts

    To enable Rush's automatic validation of your plugin's config file, specify the optionsSchema setting in your plugin manifest:

    rush-policy-plugins/rush-plugin-manifest.json

        . . .
        /**
         * (Optional) A path to a JSON schema for validating the config file that end users can
         * create to customize this plugin's behavior.  Plugin config files are stored in the folder
         * "common/config/rush-plugins/" with a filename corresponding to the "pluginName" field
         * from the manifest.  For example: "common/config/rush-plugins/business-policy.json"
         * whose schema is "business-policy.schema.json".
         */
        "optionsSchema": "lib/schemas/email-policy.schema.json",
        . . .

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/help/faq/index.html b/pages/help/faq/index.html index cffc9efd..339ee7e5 100644 --- a/pages/help/faq/index.html +++ b/pages/help/faq/index.html @@ -6,7 +6,7 @@ Frequently Asked Questions (FAQ) | Rush - + @@ -22,7 +22,7 @@ .gitattributes file (and you may also need to commit a change to the affected files to work around a GitHub caching issue):

    *.json  linguist-language=JSON-with-Comments

    For a discussion of some other possibilities, see issue #1088.

    How to clean up Rush's installation to avoid interfering with other tools?​

    Generally it's recommended to perform all monorepo management using Rush. The symlinks that Rush creates under the project node_modules folders may confuse other tools such as NPM or Yarn, causing them to malfunction because they expect a different installation model. Sometimes this is unavoidable, however. For example, when migrating an existing repo to use Rush however, the CI system may need to reuse an existing working folder to build different branches that use different installation models. To prevent interference, your CI job will first need to invoke a command that deletes the old files from the previous installation model.

    For Yarn or NPM, a command like git clean -dfx is generally sufficient. (THIS DELETES FILES -- read the manual before invoking!)

    For cleaning up a Rush installation, git clean is NOT recommended because it does not handle symlinks reliably. Instead, use the rush purge command to delete the node_modules folders created by Rush.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/help/support/index.html b/pages/help/support/index.html index 6bd67631..64c70f44 100644 --- a/pages/help/support/index.html +++ b/pages/help/support/index.html @@ -6,7 +6,7 @@ Getting support | Rush - + @@ -17,7 +17,7 @@ chat room. We carefully review each submission before merging, which is time consuming work. The maintainers are all people who manage large corporate monorepos with regular daily distractions, so PRs frequently get overlooked. Your contributions are greatly appreciated -- we do want to get that PR reviewed!

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/intro/get_started/index.html b/pages/intro/get_started/index.html index 6995db52..9f732d4c 100644 --- a/pages/intro/get_started/index.html +++ b/pages/intro/get_started/index.html @@ -6,13 +6,13 @@ Getting started | Rush - +
    Rush StackShopBlogEvents

    Getting started

    3 minute demo​

    Want to see Rush in action? The only prerequisite you need is NodeJS.

    From your shell, install Rush like this:

    npm install -g @microsoft/rush

    For command-line help, do this:

    rush -h

    To see Rush build some real projects, try running these commands:

    git clone https://github.com/microsoft/rushstack
    cd rushstack

    # Install the NPM packages:
    # (If you don't have a GitHub email configured, add the "--bypass-policy" option.)
    rush update

    # Incremental install:
    rush update  # <-- instantaneous!

    # Force all projects to be rebuilt:
    rush rebuild

    # Incremental build:
    rush build    # <-- instantaneous!

    # Use "--verbose" to view the console logs for each project as it is built.
    # Projects build in parallel processes, but their logs are collated.
    rush rebuild --verbose

    Let's get started!​

    Choose your tutorial scenario...

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/intro/welcome/index.html b/pages/intro/welcome/index.html index c40d9168..27479d00 100644 --- a/pages/intro/welcome/index.html +++ b/pages/intro/welcome/index.html @@ -6,13 +6,13 @@ Welcome to Rush! | Rush - +
    Rush StackShopBlogEvents

    Welcome to Rush!

    Rush

    Rush makes life easier for JavaScript developers who build and publish many NPM packages at once. If you're looking to consolidate all your projects into a single repo, you came to the right place! Rush is a fast, professional solution for managing this scenario. It gives you:

    • A single NPM install: In one step, Rush installs all the dependencies for all your projects into a common folder. This is not just a "package.json" file at the root of your repo (which might set you up to accidentally require() a sibling's dependencies). Instead, Rush uses symlinks to reconstruct an accurate "node_modules" folder for each project, without any of the limitations or glitches that seem to plague other approaches.

      👉 This algorithm supports the PNPM, NPM, and Yarn package managers.

    • Automatic local linking: Inside a Rush repo, all your projects are automatically symlinked to each other. When you make a change, you can see the downstream effects without publishing anything, and without any npm link headaches. If you don't want certain projects to get linked, that's supported, too.

    • Fast builds: Rush detects your dependency graph and builds your projects in the right order. If two packages don't directly depend on each other, Rush parallelizes their build as separate NodeJS processes (and shows live console output in a readable order). In practice this multi-process approach can yield more significant speedups than all those async functions in your single-process toolchain.

    • Subset and incremental builds: If you only plan to work with a few projects from your repo, rush rebuild --to <project> does a clean build of just your upstream dependencies. After you make changes, rush rebuild --from <project> does a clean build of only the affected downstream projects. And if your toolchain is package-deps-hash enabled, rush build delivers a powerful cross-project incremental build (that also supports subset builds).

    • Cyclic dependencies: If you have hammers that build hammer-factory-factories, Rush has you covered! When a package indirectly depends on an older version of itself, projects in the cycle use the last published version, whereas other projects still get the latest bits.

    • Bulk publishing: When it's time to do a release, Rush can detect which packages have changes, automatically bump all the appropriate version numbers, and run npm publish in each folder. If you like, configure your server to automatically run rush publish every hour.

    • Changelog tracking: Whenever a PR is created, you can require developers to provide a major/minor/patch log entry for the affected projects. During publishing, these changes will be automatically aggregated into a nicely formatted CHANGELOG.md file.

    • Enterprise policies: Want to review new libraries before developers add them to package.json, but avoid hassling people about already approved cases? Want to enforce that all your projects depend on the same library version numbers? Are unprofessional personal e-mail addresses accidentally showing up in your company's Git history? Rush can help maintain a consistent ecosystem when you've got many developers and many projects in the mix.

    • Lots more! Rush was created by the platform team for Microsoft SharePoint. We build hundreds of production NPM packages every day, from internal and public Git repositories, for third party SDKs and live services with millions of users. If there's an important package management problem that needs solvin', it's likely to end up as a feature for Rush.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/intro/why_mono/index.html b/pages/intro/why_mono/index.html index 62179673..e1a21f61 100644 --- a/pages/intro/why_mono/index.html +++ b/pages/intro/why_mono/index.html @@ -6,13 +6,13 @@ Why one big repo⁈ | Rush - +
    Rush StackShopBlogEvents

    Why one big repo⁈

    Open source NPM packages seem to be developed in lots of small GitHub repos. Shouldn't I do that?

    Sure, if you're building isolated components, and it's not too important how they fit together. But business software doesn't seem to work that way. It's more like this:

    Most people start out by building a single web application, not a bunch of libraries. After your application ships, it keeps growing in size. Then one day you need to share some code with a different project, and you realize you've got a big rat's nest. Time to refactor!

    Clearly you must split this thing up into manageable components. NPM packages are the way to do that in JavaScript. Looking around, the convention seems to be "one GitHub repo for each NPM package." During a heroic week or two, you create 10 Git repos, split up your code, and give it a try...

    ...but working with 10 Git repos turns out to be a big pain! There are just so many headaches:

    • Tunnel vision: If a colleague mostly does their work in repos #5 and #6, they seem to completely ignore pull requests from the other 8 repos. New repos spring into existence every day without you even knowing about it.

    • Cascading publishing: Propagating a fix from lib3 down to your application project requires updating/building/publishing many Git repos in the right order: lib3 --> lib2 --> lib1 --> application. When lib3 has frequent churn, this becomes really tedious. How will people even remember the right order to publish? The internet has lots of bodies to throw at this problem, but you have limited people, and they're very busy.

    • Downstream victims: When Bob publishes a change to lib3, it can take a while before all downstream projects get upgraded to use it. If there's a regression, it might be a week before Alice tries to run "npm update" in lib1 and discovers the problem. By then, maybe Bob has left for his backpacking trip across Europe. Why should Alice shoulder the burden of fixing someone else's regression? Seems like every time she upgrades, something is broken!

    • Linking madness: The workaround is to use npm link to symlink your application directly to lib3 for testing. But NPM creates symlinks via a global folder, which causes trouble if you need to work with multiple branches of lib3 on the same laptop. And with 10+ libraries, it's hard to remember what is symlinked to what.

    The "one repo per package" model makes sense for isolated projects that are maintained by uncoordinated strangers. (Also, most of those libraries get updated fairly infrequently, which makes the problem easier.) Whereas in our example, everyone works at the same company, and the "libraries" act more like components of an integrated architecture. Code gets churned a lot, and a change in one place can easily break another part of the system. Building multiple projects together lets you run all the unit tests for every change, which moves responsibility for fixes where it belongs: To the person who originally introduced the change.

    The emergent principle becomes "one Git repo per team", or even better "as few Git repos as possible to get the job done".

    monorepo block diagram

    Lots of people who build large scale business software seem to end up with all their code in one big "monorepo". JavaScript is just the last guy to join the party.

    The big concern with this strategy is obviously build times. JavaScript tools are slower than compiled languages. If one project takes 1 minute to build, and you have 75 projects, in theory you could be looking at a ridiculous 75 minute build time. It seems intimidating, but with an industrial strength toolchain you can scale very far before build times become an issue. Most of our roadmap for Rush and Heft is focused on build times, and we're optimistic that there's still plenty of room for optimizations. With subset/incremental builds, you can in theory avoid rebuilding everything unless a change really does affect everything -- and for that kind of change, it's hard to argue that finding breaks early isn't worth the price of waiting for a longer build.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/add_to_repo/index.html b/pages/maintainer/add_to_repo/index.html index f79a775e..9ebd0351 100644 --- a/pages/maintainer/add_to_repo/index.html +++ b/pages/maintainer/add_to_repo/index.html @@ -6,7 +6,7 @@ Adding projects to a repo | Rush - + @@ -25,7 +25,7 @@ If an NPM dependency is not declared in your package.json file, a runtime error may occur if your project tries to import it. These phantom dependency errors are one of the most common issues when migrating an existing project into a Rush monorepo. Generally the fix is simply to add the missing dependency to your package.json file.

    The rush scan command is a quick way to detect these problems.

    Step 7: Adding more projects​

    You can add more projects by following the same operations from Step 4. In our example, we would add my-controls next (because it depends on my-toolchain), and then my-application last (because it depends on everything). We proactively added a couple more category folders ("libraries" and "apps") since we expect more of these types of things in our scenario. The filled out "projects" section looks like this:

      "projects": [
        {
          "packageName": "my-app",
          "projectFolder": "apps/my-app"
        },

        {
          "packageName": "my-controls",
          "projectFolder": "libraries/my-controls",
          "reviewCategory": "production"
        },

        {
          "packageName": "my-toolchain",
          "projectFolder": "tools/my-toolchain",
          "reviewCategory": "tools"
        }
      ]

    Once you have all your projects added and building without errors, you may consider enabling other optional features. The config files contain lots of snippets that you can uncomment to get started. The rush-example repo uses some of these snippets.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/autoinstallers/index.html b/pages/maintainer/autoinstallers/index.html index 62295e5b..354d523d 100644 --- a/pages/maintainer/autoinstallers/index.html +++ b/pages/maintainer/autoinstallers/index.html @@ -6,7 +6,7 @@ Autoinstallers | Rush - + @@ -43,7 +43,7 @@ You should redo this step whenever you modify the package.json file.

    # Create or update common/autoinstallers/my-autoinstaller/pnpm-lock.yaml
    # This file should be committed and tracked by Git.
    rush update-autoinstaller --name my-autoinstaller

  • Commit the updated files to git

    git add common/autoinstallers/my-autoinstaller/

    git commit -m "Updated autoinstaller"

    • To associate an autoinstaller with a custom command, specify its name in the autoinstallerName field in command-line.json.

    To associate an autoinstaller with a Rush plugin, see the Creating Rush plugins documentation.

    Maintaining an autoinstaller​

    • To modify an autoinstaller, edit its package.json file.

      # This will also upgrade any indirect dependencies.
      rush update-autoinstaller --name my-autoinstaller

      # Commit the updated pnpm-lock.yaml
      git commit -m "Updated autoinstaller"

    • To delete the autoinstaller, simply delete its folder:

      # BE CAREFUL WHEN RECURSIVELY DELETING FOLDERS
      rm -Rf common/autoinstallers/my-autoinstaller

      # Commit the changes to Git
      git add common/autoinstallers

      git commit -m "Deleted autoinstaller"

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/build_cache/index.html b/pages/maintainer/build_cache/index.html index 9128dd99..42000fc8 100644 --- a/pages/maintainer/build_cache/index.html +++ b/pages/maintainer/build_cache/index.html @@ -6,21 +6,19 @@ Enabling the build cache | Rush - +
    Rush StackShopBlogEvents

    Enabling the build cache

    Rush has always supported an incremental build analyzer that enables rush build to skip projects whose input files have not changed since the last build. -We call this the "output preservation" strategy for incremental builds. It can also be used with custom commands -by enabling the incremental flag in custom-commands.json.

    However, the build output is not saved anywhere, so generally a full rebuild is still required when checking out -a different branch. Rush's build cache improves on this by creating a tar archive of each project's build outputs. +It can also be used with custom commands by enabling the incremental flag in custom-commands.json. +We call this the "output preservation" strategy for incremental builds. Because the build output +is not saved anywhere, a full rebuild is generally still required when checking out a different branch.

    Rush's build cache improves on this by creating a tar archive of each project's build outputs. The archive is cached so that later, if rush build can find a match in the cache, it can extract the archive instead of building that project. This can provide dramatic speedups, for example reducing a 30 minute build time -to 30 seconds. The cache key is a hash of the source files and NPM dependencies, following the -same basic rules as the incremental analyzer. We call this the -"cache restoration" strategy for incremental builds.

    The build cache archives are stored in two places:

    • In a cache folder on your local disk. This way you can switch between different branches without +to 30 seconds. We call this the "cache restoration" strategy for incremental builds.

      The build cache archives are stored in two places:

      • In a cache folder on your local disk. This way you can switch between different branches without losing your incremental build state. You can even configure a centralized folder to be shared between multiple enlistments on your machine. The default location is common/temp/build-cache.

      • In a cloud-hosted storage container. (Optional) In a typical setup, the CI system would be configured to write to cloud storage, and individual users are granted read-only access. For example, each time a PR is merged into @@ -29,10 +27,17 @@ config file. You can copy the template from the website or use rush init to create this file.

        To enable the basic local disk cache, add these two settings:

        common/config/rush/build-cache.json

        {
          . . .
          /**
           * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.
           *
           * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.
           */
          "buildCacheEnabled": true,

          /**
           * (Required) Choose where project build outputs will be cached.
           *
           * Possible values: "local-only", "azure-blob-storage", "amazon-s3"
           */
          "cacheProvider": "local-only",

          . . .
        }

        Upgrade note: Early releases of this feature were enabled using the "buildCache": true setting in experiments.json. This has been superseded by "buildCacheEnabled" in build-cache.json.

        Configuring project output folders​

        With only this change, if you run rush rebuild --verbose, you will see this warning:

        Project does not have a rush-project.json configuration file, or one provided by a rig,
        so it does not support caching.

        The build cache needs to know which folders should be stored in the tar archive. Those details vary between toolchains, and are thus configured separately for each project using the -rush-project.json config file.

        For example:

        <your-project>/config/rush-project.json

        {
          . . .

          /**
           * Specify the folders where your toolchain writes its output files.  If enabled, the Rush build cache will
           * restore these folders from the cache.
           *
           * The strings are folder names under the project root folder.  These folders should not be tracked by Git.
           * They must not contain symlinks.
           */
          "projectOutputFolderNames": ["lib", "dist"]
          . . .
        }

        The cache key by default will consider your project's inputs to be the source files under the project folder -that are not excluded by .gitignore; the details can be customized using -the rush-project.json config file.

        It's recommended to use a rig package to avoid having -to copy this file into each project folder.

        Testing the build cache​

        Now you should see projects being cached as shown in this sample log output:

        rush build --verbose
        . . .

        ==[ example-project ]==============================================[ 1 of 5 ]==

        This project was not found in the build cache.

        Invoking: heft test --clean

        . . .

        Caching build output folders: lib

        Successfully set cache entry.

        "example-project" completed successfully in 11.27 seconds.

        When we run the same command a second time, Rush extracts the archive instead of invoking the build task:

        rush build --verbose
        . . .

        ==[ example-project ]==============================================[ 1 of 5 ]==

        Build cache hit.

        Clearing cached folders: lib, dist

        Successfully restored output from the build cache.

        example-project was restored from the build cache.

        Note that rush rebuild will not read from cache, only rush build does. To disable writing from cache during rush rebuild, +rush-project.json config file.

        For example:

        <your-project>/config/rush-project.json

        {
          . . .

          /**
           * Specify the folders where your toolchain writes its output files.  If enabled, the Rush build cache will
           * restore these folders from the cache.
           *
           * The strings are folder names under the project root folder.  These folders should not be tracked by Git.
           * They must not contain symlinks.
           */
          "projectOutputFolderNames": ["lib", "dist"]
          . . .
        }

        Configuring project inputs​

        By default, the following inputs are incorporated into Rush's cache key. In other words, if any of these things +changes, then the project must be rebuilt:

        • the hash of the source files that are under the project's folder, ignoring any files excluded by .gitignore

        • the hashes of source files under other workspace projects that are dependencies of the project
          +(applies to cache restoration strategy but not output preservation strategy)

        • the versions of all external NPM packages that your project depends on, including indirect dependencies

        • the Rush command-line parameters used to perform the operation

        These details can be customized using the rush-project.json config file. +For example, you can include/exclude certain glob patterns, or specify environment variables that affect the +build output. It's recommended to use a rig package to avoid +having to copy rush-project.json into every project folder.

        Important: Configure these settings carefully. If a project inputs/outputs are not accurately specified, +then the build cache may produce incorrect or inconsistent results. For example, the restored output may +be missing some files. Or it may be different from what would be produced by a full rebuild. Such problems +can be difficult to reproduce and troubleshoot.

        If you suspect that the Rush build cache may be misconfigured, try the +rush-audit-cache-plugin. +It monitors file writes during the build to identify inputs that are not part of your cache key.

        Testing the build cache​

        Now you should see projects being cached as shown in this sample log output:

        rush build --verbose
        . . .

        ==[ example-project ]==============================================[ 1 of 5 ]==

        This project was not found in the build cache.

        Invoking: heft test --clean

        . . .

        Caching build output folders: lib

        Successfully set cache entry.

        "example-project" completed successfully in 11.27 seconds.

        When we run the same command a second time, Rush extracts the archive instead of invoking the build task:

        rush build --verbose
        . . .

        ==[ example-project ]==============================================[ 1 of 5 ]==

        Build cache hit.

        Clearing cached folders: lib, dist

        Successfully restored output from the build cache.

        example-project was restored from the build cache.

        Note that rush rebuild will not read from cache, only rush build does. To disable writing from cache during rush rebuild, set the RUSH_BUILD_CACHE_WRITE_ALLOWED environment variable to 0.

        By default, the cached tar archives are stored under your common/temp/build-cache folder (and thus will be cleaned by rush purge). It is safe to delete these files.

        Enabling cloud storage​

        Currently the cacheProvider setting provides three choices:

        • "local-only": no cloud storage; archives are only kept on a local disk folder
        • "azure-blob-storage": Microsoft Azure blob storage container
        • "amazon-s3": Amazon S3 bucket

        (The above providers are modeled as Rush plugins. Custom build cache storage providers can be implemented in the same way.)

        As one example, here's how to configure an Azure blob container:

        common/config/rush/build-cache.json

        {
          . . .
          /**
           * (Required) EXPERIMENTAL - Set this to true to enable the build cache feature.
           *
           * See https://rushjs.io/pages/maintainer/build_cache/ for details about this experimental feature.
           */
          "buildCacheEnabled": true,

          /**
           * (Required) Choose where project build outputs will be cached.
           *
           * Possible values: "local-only", "azure-blob-storage", "amazon-s3"
           */
          "cacheProvider": "azure-blob-storage",

          /**
           * Use this configuration with "cacheProvider"="azure-blob-storage"
           */
          "azureBlobStorageConfiguration": {
            /**
             * (Required) The name of the the Azure storage account to use for build cache.
             */
            "storageAccountName": "example",

            /**
             * The name of the container in the Azure storage account to use for build cache.
             */
            "storageContainerName": "my-container"

            /**
             * If set to true, allow writing to the cache. Defaults to false.
             */
            "isCacheWriteAllowed": false

          . . .

        Note that we have set "isCacheWriteAllowed": false to prevent regular users from writing to the container. @@ -51,8 +56,8 @@ about SAS tokens. You can obtain a SAS token via the Settings > Access keys page for your storage account.

        AWS​

        For Amazon S3, RUSH_BUILD_CACHE_CREDENTIAL will be your AWS Access Key ID and AWS Secret Access Key separated by a colon, such as: <AccessKeyID>:<SecretAccessKey>. You can also pass temporary session tokens required when assuming an IAM role: <AccessKeyID>:<SecretAccessKey>:<SessionToken>.

        If RUSH_BUILD_CACHE_CREDENTIAL is not set, the build cache will attempt to read the environment vars AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN that -are commonly set via the AWS CLI or other CI tooling. However, RUSH_BUILD_CACHE_CREDENTIAL will always take precedence if it exists.

        The build cache feature is still under development. Feedback is welcome!

        Some relevant GitHub issues to follow:

    © 2023 Microsoft
    - +are commonly set via the AWS CLI or other CI tooling. However, RUSH_BUILD_CACHE_CREDENTIAL will always take precedence if it exists.

    The build cache feature is still under development. Feedback is welcome!

    Some relevant GitHub issues to follow:

    © 2023 Microsoft
    + \ No newline at end of file diff --git a/pages/maintainer/cobuilds/index.html b/pages/maintainer/cobuilds/index.html index c224baa1..e86af0c5 100644 --- a/pages/maintainer/cobuilds/index.html +++ b/pages/maintainer/cobuilds/index.html @@ -6,7 +6,7 @@ Cobuilds (experimental) | Rush - + @@ -106,7 +106,7 @@ of the operation's execution result and the corresponding cache_id. Before attempting to acquire a lock, a machine will first query this completion result information. If there is a completion result available, the result is reused based on the parsed information.

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/custom_commands/index.html b/pages/maintainer/custom_commands/index.html index 29afde0d..96470e2a 100644 --- a/pages/maintainer/custom_commands/index.html +++ b/pages/maintainer/custom_commands/index.html @@ -6,7 +6,7 @@ Custom commands | Rush - + @@ -16,7 +16,7 @@ a script defined in each project's package.json file, or a single script file specified by the (optional) shellCommand field.

  • global command: These commands run once for the entire repo, by executing a single script file specified by the (required) shellCommand field.

    • You can also define your own command-line "parameters". A parameter can be associated with one or more commands via its associatedCommands list. You can even associate your custom parameters with Rush's own built-in build and rebuild commands. In the above example, we associate the --ship parameter with rush build, rush rebuild, and our custom rush import-strings.

    Currently three kinds of parameterKind are supported:

    • flag parameter: A "flag" is a simple switch, for example --production.
    • string parameter: A parameter that includes a text string argument, for example --title "Hello, world!".
    • string list parameter: A string parameter that can be specified multiple times, for example --category docs --category dashboard
    • choice parameter: Similar to a string but the argument must come from a list of supported alternatives, for example --locale fr-fr.
    • integer parameter: A parameter that includes an integer argument, for example --pull-request 1234.
    • integer list parameter: An integer parameter that can be specified multiple times, for example --pr 1234 --pr 1235 --pr 1236

    More parameter kinds may be supported in the future. (They are parsed using the ts-command-line library which supports other parameter kinds that could be exposed.)

    Using custom commands and options​

    Your custom definitions and their descriptions will be incorporated into Rush's command-line help (when invoked under your repo working folder). Continuing the above example, if we run rush import-strings --help we'll now see something like this:

    Rush Multi-Project Build Tool 5.1.0 - https://rushjs.io

    usage: rush import-strings [-h] [-p COUNT] [-t PROJECT1]
                               [--to-version-policy VERSION_POLICY_NAME]
                               [-f PROJECT2] [-v] [-s]
                               [--locale {en-us,fr-fr,es-es,zh-cn}]

    Requests translated strings from the translation service and imports them
    into each project.

    Optional arguments:
      -h, --help            Show this help message and exit.
      -p COUNT, --parallelism COUNT
                            Specify the number of concurrent build processes The
                            value "max" can be specified to indicate the number
                            of CPU cores. If this parameter omitted, the default
                            value depends on the operating system and number of
                            CPU cores.
      -t PROJECT1, --to PROJECT1
                            Run command in the specified project and all of its
                            dependencies
      --to-version-policy VERSION_POLICY_NAME
                            Run command in all projects with the specified
                            version policy and all of their dependencies
      -f PROJECT2, --from PROJECT2
                            Run command in all projects that directly or
                            indirectly depend on the specified project
      -v, --verbose         Display the logs during the build, rather than just
                            displaying the build status summary
      -s, --ship            Perform a production build, including minification
                            and localization steps
      --locale {en-us,fr-fr,es-es,zh-cn}
                            Selects a single instead of the default locale
                            (en-us) for non-ship builds or all locales for ship
                            builds.

    How to implement a custom command/parameter? For global commands, Rush simply invokes their shellCommand and passes the parameters along. For bulk commands, Rush can alternatively look for a corresponding script name in your package.json file. Suppose we have something like this:

    example/package.json

    {
      "name": "example",
      "version": "1.0.0",
      "main": "lib/index.js",
      "typings": "lib/index.d.ts",
      "scripts": {
        "import-strings": "./node_modules/.bin/loc-importer",
        "build": "./node_modules/.bin/heft build"
      }
    }

    If we run rush import-strings --locale fr-fr, then Rush will read the "import-strings" script body and execute it like this:

    ./node_modules/.bin/loc-importer --locale fr-fr

    (Rush directly executes it using your shell; it does not rely on npm run.) Since this choice parameter has a default value, if we run rush import-strings, then loc-importer is executed like this:

    ./node_modules/.bin/loc-importer --locale en-us

    In other words, Rush's custom parameters are simply appended to the package.json script body. This means you may run into trouble if your script body uses shell expressions such as "rimraf ./lib && rimraf ./temp" which don't support these parameters, or need them to be inserted in the middle of the string. This is by design: We don't recommend writing nontrivial build scripts inside a JSON string. Instead, it's better to move this operation into a proper script file that can be commented and reviewed. As your monorepo grows, you'll probably also want to move that script into a reusable library that can be shared across projects.

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/custom_tips/index.html b/pages/maintainer/custom_tips/index.html index 2c1b6e88..04607bba 100644 --- a/pages/maintainer/custom_tips/index.html +++ b/pages/maintainer/custom_tips/index.html @@ -6,7 +6,7 @@ Custom tips (experimental) | Rush - + @@ -22,7 +22,7 @@ rush-lib/src/api/CustomTipsConfiguration.ts, so feel free to create a pull request proposing new tips.

    Custom tip identifiers​

    TIP_PNPM_INVALID_NODE_VERSION​

    Corresponds to PNPM's ERR_PNPM_INVALID_NODE_VERSION.

    TIP_PNPM_MISMATCHED_RELEASE_CHANNEL​

    Corresponds to PNPM's ERR_PNPM_MISMATCHED_RELEASE_CHANNEL.

    TIP_PNPM_NO_MATCHING_VERSION​

    Corresponds to PNPM's ERR_PNPM_NO_MATCHING_VERSION.

    TIP_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE​

    Corresponds to PNPM's ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE.

    TIP_PNPM_OUTDATED_LOCKFILE​

    Corresponds to PNPM's ERR_PNPM_OUTDATED_LOCKFILE.

    TIP_PNPM_PEER_DEP_ISSUES​

    Corresponds to PNPM's ERR_PNPM_PEER_DEP_ISSUES.

    TIP_PNPM_TARBALL_INTEGRITY​

    Corresponds to PNPM's ERR_PNPM_TARBALL_INTEGRITY

    TIP_PNPM_UNEXPECTED_STORE​

    Corresponds to PNPM's ERR_PNPM_UNEXPECTED_STORE.

    TIP_RUSH_INCONSISTENT_VERSIONS​

    This message is printed by rush install or rush update when projects have inconsistent dependency versions, only if ensureConsistentVersions is enabled in rush.json.

    Example Rush output:

    Found 5 mis-matching dependencies!

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/deploying/index.html b/pages/maintainer/deploying/index.html index 6c97fecb..c516aeee 100644 --- a/pages/maintainer/deploying/index.html +++ b/pages/maintainer/deploying/index.html @@ -6,7 +6,7 @@ Deploying projects | Rush - + @@ -44,7 +44,7 @@ We will create two config files:

    • common/config/rush/deploy.json - the default scenario file, which we'll use for app1
    • common/config/rush/deploy-app2-example.json -- the app2-example scenario, which we will use for app2

    Both of these files can be created using rush init-deploy:

    # Create common/config/rush/deploy.json
    rush init-deploy --project app1

    # Create common/config/rush/deploy-app2-example.json
    rush init-deploy --project app2 --scenario app2-example

    After editing deploy-app2-example.json to specify "linkCreation": "script", we can now use the --scenario parameter with rush deploy:

    # Copy app1 and its dependencies to /mnt/deploy/app1
    # Uses scenario file: common/config/rush/deploy.json
    rush deploy --target-folder /mnt/deploy/app1

    # Copy app2 and its dependencies to /mnt/deploy/app2
    # Uses scenario file: common/config/rush/deploy-app2-example.json
    rush deploy --target-folder /mnt/deploy/app2 --scenario app2-example

    Note that the --project parameter is not needed with rush deploy because each config file has only one project in its "deploymentProjectNames" array.

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/enabling_ci_builds/index.html b/pages/maintainer/enabling_ci_builds/index.html index babd8412..4773d3d5 100644 --- a/pages/maintainer/enabling_ci_builds/index.html +++ b/pages/maintainer/enabling_ci_builds/index.html @@ -6,7 +6,7 @@ Enabling CI builds | Rush - + @@ -36,7 +36,7 @@ to invoke the Rush tool:

    .github/workflows/ci.yml

    name: CI
    on:
      push:
        branches: ['main']
      pull_request:
        branches: ['main']
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
            with:
              fetch-depth: 2
          - name: Git config user
            uses: snow-actions/git-config-user@v1.0.0
            with:
              name: # Service Account's Name
              email: # Service Account's Email Address
          - uses: actions/setup-node@v3
            with:
              node-version: 16
          - name: Verify Change Logs
            run: node common/scripts/install-run-rush.js change --verify
          - name: Rush Install
            run: node common/scripts/install-run-rush.js install
          - name: Rush rebuild
            run: node common/scripts/install-run-rush.js rebuild --verbose --production

    For an example of an equivalent setup using an Azure DevOps build pipeline, take a look at the build.yaml file, in the monorepo where Rush is developed.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/enabling_prettier/index.html b/pages/maintainer/enabling_prettier/index.html index a5dfd132..5bba9cd4 100644 --- a/pages/maintainer/enabling_prettier/index.html +++ b/pages/maintainer/enabling_prettier/index.html @@ -6,7 +6,7 @@ Enabling Prettier | Rush - + @@ -47,7 +47,7 @@ To do this, create a file called pre-commit in the common/git-hooks folder:

    common/git-hooks/pre-commit

    #!/bin/sh
    # Called by "git commit" with no arguments.  The hook should
    # exit with non-zero status after issuing an appropriate message if
    # it wants to stop the commit.

    # Invoke the "rush prettier" custom command to reformat files whenever they
    # are committed. The command is defined in common/config/rush/command-line.json
    # and uses the "rush-prettier" autoinstaller.
    node common/scripts/install-run-rush.js prettier || exit $?

  • Make the file executable: chmod +x pre-commit

  • To actually install the hook, run rush install.

  • Before finally merging your PR, you may want to run prettier . --write one last time to reformat any files that may have been modified before we installed the hook.

    • You're done! Whenever changes are committed to Git, they will now be automatically prettified.

    Installing prettier plugins​

    Prettier supports plugins, which can add new languages or formatting rules. If you choose to add prettier plugins to your setup, special care must be taken to ensure that all of the tooling that might call prettier will be able to load your prettier configuration:

    • rush prettier as configured in the steps above
    • Editors (VSCode, Webstorm, Sublime, etc.) that are configured to format on save
    • Jest and heft test, which use prettier to format snapshots

    Here's an example, using the prettier-plugin-packagejson plugin:

    1. First, add the plugin package to your autoinstaller package.json file -- if configured as above, this will be common/autoinstallers/rush-prettier/package.json.

      {
        "dependencies": {
          "prettier-plugin-packagejson": "^2.2.18"
        }
      }

    2. Update your autoinstaller's lockfile:

      rush update-autoinstaller --name rush-prettier

    3. Add the full path of your plugin folder to the plugins array in .prettierrc.js:

      module.exports = {
        // ... your other configuration goes here ...
        // ,

        plugins: ['./common/autoinstallers/rush-prettier/node_modules/prettier-plugin-packagejson']
      };

    4. Commit your autoinstaller and prettierrc changes.

    Note that after pulling this change, local developers will need to run rush prettier at least once to install the updated autoinstaller -- otherwise, their format-on-save functions and jest snapshot formatting may stop working. In practice this will fix itself after they perform at least one git commit and run the git hooks, but it may be worth notifying your team any time you do update prettier plugins this way.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/git_hooks/index.html b/pages/maintainer/git_hooks/index.html index 377aec4e..0294eb89 100644 --- a/pages/maintainer/git_hooks/index.html +++ b/pages/maintainer/git_hooks/index.html @@ -6,7 +6,7 @@ Installing Git hooks | Rush - + @@ -31,7 +31,7 @@ in your .git/hooks/ folder.

    Invoking Prettier during "git commit"​

    The Prettier tool ensures that source files follow consistent conventions for syntax issues like spacing and commas. By configuring a git commit hook to invoke Prettier automatically, you can apply these fixes without any effort on the developer's part.

    The Enabling Prettier article provides step-by-step instructions.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/npm_registry_auth/index.html b/pages/maintainer/npm_registry_auth/index.html index e885cecc..7bc2b2b4 100644 --- a/pages/maintainer/npm_registry_auth/index.html +++ b/pages/maintainer/npm_registry_auth/index.html @@ -6,7 +6,7 @@ NPM registry authentication | Rush - + @@ -33,7 +33,7 @@ artifactory.json config file. The file template contains documentation for other optional settings that can be used to customize the dialogue.

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/package_managers/index.html b/pages/maintainer/package_managers/index.html index 464b4019..bc8f2ea5 100644 --- a/pages/maintainer/package_managers/index.html +++ b/pages/maintainer/package_managers/index.html @@ -6,13 +6,13 @@ NPM vs PNPM vs Yarn | Rush - +
    Rush StackShopBlogEvents

    NPM vs PNPM vs Yarn

    Before you can start installing a JavaScript library, you need to choose which package manager you will use. (Our community loves flexibility and choices, so of course there's not just one!) Rush supports the three most popular package managers. In chronological order:

    • NPM: the tool that pioneered the packaging standard and registry protocol used by most JavaScript package managers today. The tool's developers also maintain the npmjs.com registry, which is currently the most popular place to distribute open source JavaScript libraries.

    • Yarn: a complete rewrite of the NPM tool that preserves the same installation model, but promises faster installations, better reliability, and some cool new features (e.g. Yarn workspaces) that facilitate large scale development.

    • PNPM: A fundamentally new installation model that solves the "phantom dependency" and "NPM doppelganger"" problems, while cleverly making use of symlinks to remain 100% compatible with the NodeJS module resolution standard.

    Which one should I use with Rush?​

    The answer depends on your needs. The Rush developers don't endorse a particular package manager, but here are some observations based on our experience from managing our own monorepos:

    Considerations for NPM​

    • NPM is the most compatible choice, and the most forgiving for dealing with "bad" packages.

    • If you choose NPM, you may need to use an older release. NPM 5.x and 6.x are both known to have unresolved regressions that cause trouble in Rush repos. NPM 4.5.0 is the most recent version that's known to work very reliably, but unfortunately it's pretty old. (We'd greatly appreciate community help improving this situation. We're using GitHub issue #886 to track this effort.)

      Before reporting a Rush bug involving the NPM package manager, first try downgrading to "npmVersion": "4.5.0". If that eliminates the repro, then your issue is likely an NPM regression and may not be fixable in the Rush code base. We still accept these issues, but we track them differently.

    Considerations for PNPM​

    • PNPM is the only option that solves the NPM doppelgangers problem. In a complex monorepo, doppelgangers sometimes cause a lot of trouble, so PNPM has an important advantage in this regard.

    • Although PNPM's symlinking strategy correctly follows the modern NodeJS module resolution standard, many legacy packages do not, which causes compatibility problems. Teams who migrate existing projects from Yarn/NPM to PNPM often encounter "bad packages" that need workarounds or fixes. The incompatibilities generally reflect real problems with those packages: (1) forgetting to list dependencies in the package.json file, or (2) implementing homebrew module resolution without handling symlinks according to the standard. Most "bad" packages have straightforward fixes, but it may seem daunting for a small team. (The PNPM Discord chat room is a great resource for help, though.)

    • PNPM is newer and less widely used than NPM or Yarn, but it's a solid piece of software. Microsoft uses PNPM in Rush repos with hundreds of projects and hundreds of PRs per day, and we've found it to be very fast and reliable.

    • PNPM is currently the only option that supports the --strict-peer-dependencies protection (see "strictPeerDependencies" in rush.json).

    Considerations for Yarn​

    • Rush's support for Yarn is relatively new and unproven, so we're eager to hear about issues and get them fixed.

    • Yarn installs faster than NPM (although somewhat slower than PNPM).

    • Yarn's "workspaces" are not used in a Rush repo, since they rely on an installation model that doesn't protect against phantom dependencies. Rush's linking strategy is mostly equivalent to workspaces, however.

    Specifying your package manager​

    To change your package manager, edit the rush.json file and uncomment one of the three fields (npmVersion, pnpmVersion, or yarnVersion):

    rush.json

    /**
      * The next field selects which package manager should be installed and determines its version.
      * Rush installs its own local copy of the package manager to ensure that your build process
      * is fully isolated from whatever tools are present in the local environment.
      *
      * Specify one of: "pnpmVersion", "npmVersion", or "yarnVersion".  See the Rush documentation
      * for details about these alternatives.
      */
    "pnpmVersion": "2.15.1",

    // "npmVersion": "4.5.0",
    // "yarnVersion": "1.9.4",

    After changing the setting, delete your old shrinkwrap file and other package manager specific files from the common/config/rush folder. (Otherwise Rush will complain about unsupported config files.) Then run rush update --full --purge. That's it!

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/phased_builds/index.html b/pages/maintainer/phased_builds/index.html index 53fcaa98..433e7285 100644 --- a/pages/maintainer/phased_builds/index.html +++ b/pages/maintainer/phased_builds/index.html @@ -6,7 +6,7 @@ Enabling phased builds | Rush - + @@ -15,7 +15,7 @@ script is a single operation.

    Phased builds are a way to increase parallelism, by defining individual operations as phases that can be executed on a project. As an example, if project B depends on project A, we could first build project A, and then begin building project B while running the unit tests for project A in parallel.

    NOTE: Phased builds are built on top of, and require, the build cache feature -- if you haven't already enabled the build cache for your monorepo, see Enabling build cache.

    Enable the experiment​

    In common/config/rush/experiments.json, enable the "phasedCommands" experiment.

    {
      "phasedCommands": true
    }

    Define phases​

    In common/config/rush/command-line.json, add a section "phases", as follows:

    {
      "phases": [
        {
          /**
           * The name of the phase. Note that this value must start with the \"_phase:\" prefix.
           */
          "name": "_phase:build",

          /**
           * The dependencies of this phase.
           */
          "dependencies": {
            "upstream": ["_phase:build"]
          },

          /**
           * Normally Rush requires that each project's package.json has a \"scripts\" entry matching the phase name. To disable this check, set \"ignoreMissingScript\" to true.
           */
          "ignoreMissingScript": true,

          /**
           * By default, Rush returns a nonzero exit code if errors or warnings occur during a command. If this option is set to \"true\", Rush will return a zero exit code if warnings occur during the execution of this phase.
           */
          "allowWarningsOnSuccess": false
        },
        {
          "name": "_phase:test",
          "dependencies": {
            "self": ["_phase:build"]
          },
          "ignoreMissingScript": true,
          "allowWarningsOnSuccess": false
        }
      ]
    }

    In this example, we define two phases -- _phase:build and _phase:test. The _phase:build operation depends on the _phase:build operation of its upstream projects (using the traditional Rush dependency graph). The _phase:test operation does not depend on any upstream projects, but requires the _phase:build operation of its own project to be completed first. Note that phase names must start with _phase:.

    Individual projects can choose not to implement a phase (if ignoreMissingScript is enabled), but they cannot define their own phases, or change the dependencies of phases. This ensures that phases will behave consistently within your monorepo, regardless of what subset of projects you are building.

    Redefine the build and test commands​

    In common/config/rush/command-line.json, in the "commands" section, redefine the "build" command to be a phased command instead of a bulk command, and specify what phases you would like it to run. In the example below we also define a "test" command.

    {
      "commands": [
        {
          "commandKind": "phased",
          "name": "build",
          "phases": ["_phase:build"],
          "enableParallelism": true,
          "incremental": true
        },

        // No need to define "rebuild", by default, it is the same as build
        // but with incremental=false.

        {
          "commandKind": "phased",
          "name": "test",
          "summary": "Build and test all projects.",
          "phases": ["_phase:build", "_phase:test"],
          "enableParallelism": true,
          "incremental": true
        },

        {
          "commandKind": "phased",
          "name": "retest",
          "summary": "Build and test all projects.",
          "phases": ["_phase:build", "_phase:test"],
          "enableParallelism": true,
          "incremental": false
        }
      ]
    }

    This command definition shows off another useful feature of phased builds: we can create our "phase" building blocks and then build commands out of them. Instead of rush build running builds and tests for all projects, we can define rush build to mean "build everything without tests", and rush test to mean "build everything and run tests".

    Assign parameters to phases​

    If you have defined any custom parameters for your build command in command-line.json, you'll now need to associate them to phases, so Rush knows which phases can accept your parameter.

    Here are some examples:

    {
      "parameters": [
        {
          "longName": "--production",
          "parameterKind": "flag",
          "description": "Perform a production build, including minification and localization steps",
          "associatedCommands": ["build", "rebuild", "test", "retest"],
          "associatedPhases": ["_phase:build"]
        },
        {
          "longName": "--update-snapshots",
          "parameterKind": "flag",
          "description": "Update unit test snapshots for all projects",
          "associatedCommands": ["test", "retest"],
          "associatedPhases": ["_phase:test"]
        }
      ]
    }

    Here, we've defined one flag (--production) that can be specified on all 4 variations of our build command, but it will only be passed to the build phase. And, we've defined anothe flag (--update-snapshots) that can be specified only on the test and retest commands, and is only passed to the test phase.

    So, if we were to execute this command:

    rush test --production --update-snapshots

    Rush will pass the --production parameter to the _phase:build script for each project, and then pass the --update-snapshots parameter to the _phase:test script for each project.

    Add the phase scripts to your projects​

    Within the package.json file for every project in your monorepo, add the new _phase: scripts:

    {
      "scripts": {
        "_phase:build": "heft build --clean",
        "_phase:test": "heft test --no-build",
        "build": "heft build --clean",
        "test": "heft test --clean"
      }
    }

    The example above attempts to align developer expectations for the build and test commands:

    • Moving into the project folder and running rushx build cleans and builds the project, without testing.
    • Moving into the project folder and running rushx test cleans, builds, and tests the project.
    • Running rush build --only <project> cleans and builds the project, without testing.
    • Running rush test --only <project> cleans, builds, and tests the project.

    Where possible, for any custom phases you define, keep this pattern in mind -- what's important isn't that phases are implemented identically to rushx commands, but rather that rush <something> and rushx <something> produce similar results, if applicable.

    Some projects may not have any meaningful work to do for a phase, in which case you can define it as an empty operation (""), or leave it off entirely, if ignoreMissingScript was specified in the phase definition.

    Define per-phase output folder names​

    Within the rush-project.json configuration file of each project (or, preferably, each rig profile), redefine your operationSettings so that each folder is specified in only one phase. For example:

    {
      "operationSettings": [
        // Old configuration (before phases)
        {
          "operationName": "build",
          "outputFolderNames": ["lib", "lib-commonjs", "dist", "temp"]
        },
        // New configuration (after phases)
        {
          "operationName": "_phase:build",
          "outputFolderNames": ["lib", "lib-commonjs", "dist"]
        },
        {
          "operationName": "_phase:test",
          "outputFolderNames": ["temp/coverage", "temp/jest-reports"]
        }
      ]
    }

    Note how there's no overlap between the output folders specified by _phase:build and _phase:test -- this is an important new requirement for phased builds. In general, it's not possible for Rush to reliably cache the output of an operation if that output can be modified by a different operation, so you should structure your operations such that if _phase:build produces a "lib" folder, no other operation will put output in that folder.

    The phased builds feature is still under development. Feedback is welcome!

    Some relevant GitHub issues to follow:

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/publishing/index.html b/pages/maintainer/publishing/index.html index e5ebf911..0ed242e4 100644 --- a/pages/maintainer/publishing/index.html +++ b/pages/maintainer/publishing/index.html @@ -6,13 +6,13 @@ Publishing packages | Rush - +
    Rush StackShopBlogEvents

    How to use Rush in your build flow to automate publishing of updated packages

    There are two stages in a Rush publishing flow. The first stage is during development. Developers are asked to provide change files to track changes that deserve a space in change log. The second stage is at publishing time. Rush can be used to gather all change files to increase version, update change log, and publish new packages to a npm registry.

    1. Track Changes​

    Only changes to public packages need to be tracked. People can control which package should get published and which package should not get published in rush.json by specifying field shouldPublish. Once public packages have been defined, repo admins can enforce developers to provide change files if they have modified any public packages. Developers can use a tool to generate change files after answering a few questions.

    How to enforce developers to provide change files​

    rush change --verify

    This command fails if a developer modifies a public package without providing related change files. It is recommended to add this command as a step of CI builds so that build fails when change files are missing.

    How a developer generates change files​

    rush change

    Running rush change will prompt a developer with a few questions and generate appropriate change files after questions have been answered. A change file contains what type of version increase this change needs and a description of the change. The change file should be committed with related changes into the repo.

    2. Publish packages​

    rush publish

    When it is time to publish updated packages, rush publish is the command that increases package version and publish updated packages. It does quite a few things internally to make it happen: gather all change files to figure out what kind of version increase is needed, what packages need to have version increase, increase the versions of dependencies, clean up change files, and so on.

    This command should have its own build definition. So people can just trigger it to run when it is time to publish packages.

    rush publish is configurable to serve difference purposes. For example, it supports a dry run mode so that the changes can be verified and tested before real publishing. More usage cases are listed here:

    Dry run mode​

    rush publish has several flavors of dry runs that allow you to execute intermediate steps of the publish process without actually publishing to an npm registry. This can be useful for testing as well as for creating version bumps and changelogs in situations where this is no external package repository in use for publishing.

    rush publish

    When run without any parameters, this does the whole process in a read-only mode, which means the changes are not saved to disk, not committed to the source repository, and packages are not really published. It is useful if you want to check if the version increases and change log updates look right for you.

    rush publish --apply

    In this mode the changes are added to the changelog files and the package.json files are updated with new version numbers and written to disk, but nothing is actually committed to the source repository or published. This is useful if you want to review or edit any of these files before committing to the source repository or publishing to the package repository.

    rush publish --apply --target-branch targetBranch

    In this mode, the changes above are actually committed to a new git branch (prefixed with publish-) that is based off of targetBranch. Running this command with targetBranch set to the branch specified in repository.defaultBranch will effectively do everything that a "live" publish would do (including commits to git source), short of actually publishing to an npm repository.

    Publish mode​

    There are extra parameters for configuring the publishing process: which registry to publish to, what token to use, and whether to include commit details.

    rush publish --apply --target-branch targetBranch --publish

    This command increases versions, commit changes to targetBranch, and publish packages to a registry based on environmental npm registry value.

    rush publish --apply --target-branch targetBranch --publish --registry registryUrl --npm-auth-token npmToken

    In addition to what previous command can do, this command allows packages to be published to the specified registry with a specified npm token.

    rush publish --apply --target-branch targetBranch --publish --registry registryUrl --npm-auth-token npmToken --add-commit-details

    In addition to what previous command can do, This command will include commit details in the change logs.

    Pack mode​

    Instead of publishing, you also have the option to pack the outputs locally into .tgz files.

    rush publish --pack --include-all --publish

    Note: Any command that uses the --publish flag will disable dry mode, which allows writing the file contents to the disk.

    You can also use this command in combination with --release-folder to hint where the files should be outputted.

    3. Version Policy​

    Version policy is a new concept introduced into Rush to solve the problem of how to notify packages to do different types of version increase when the number of packages is large. For example, @microsoft/rush and @microsoft/rush-lib are always published together and use the same version. Those two versions should always be increased together. Another example is that developers can create different branches to service different major versions. People should not be able to modify the major version in that branch. Version policy solves this kind of problems by defining different policies, one enforcing that rush and rush-lib always have the same version and the other locking the major version in a branch.

    What is a version policy?​

    A version policy is set of rules that define how the version should be increased. It is defined in common/config/rush/version-policies.json. An example can be found in here. A public package specifies what version policy it is associated with by providing versionPolicyName in rush.json. An example can be found in Rush and Rush-lib configuration. Multiple packages can use one version policy if they all follow the same rules. When a package is associated with a version policy, it becomes public and can be published when rush publish runs.

    The schema of version-policies.json is defined here.

    Two types of version policies​

    There are currently two types of version policies supported: lockstep version policy and individual version policy. Projects using one lockstep version policy all have the same version. Projects using an individual version policy get version increased according to their change files and the restrictions of the policy. For example, if an individual version policy has a locked major version, all packages using this policy will have their major version locked.

    [
      {
        "policyName": "myPublic",
        "definitionName": "lockStepVersion",
        "version": "1.0.0-dev.6",
        "nextBump": "prerelease"
      },
      {
        "policyName": "myInternal",
        "definitionName": "individualVersion",
        "lockedMajor": 3
      }
    ]

    Publishing process when version policies are used​

    You need two steps to publish your packages when version policies are used. The first step is to increase the package versions. And the second step is to publish the packages. The reason to break up publishing into two steps is that it is very often that you need to test the packages after version increase and before package publishing.

    Command to increase version​

    rush version --bump

    Running rush version --bump will increase package versions based on their associated version policies.

    Command to publish packages​

    rush publish --include-all

    Running rush publish --include-all will publish all the public packages that have version increased.

    4. Summary​

    In summary, you can use Rush to automate the whole publishing flow for your repo.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/recommended_settings/index.html b/pages/maintainer/recommended_settings/index.html index ec1a26e9..144fdb8a 100644 --- a/pages/maintainer/recommended_settings/index.html +++ b/pages/maintainer/recommended_settings/index.html @@ -6,7 +6,7 @@ Recommended settings | Rush - + @@ -34,7 +34,7 @@ peer dependencies, which is an invalid state that can cause build failures or incompatible dependency versions. (For historical reasons, JavaScript package managers generally do not treat this invalid state as an error.)

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/setup_new_repo/index.html b/pages/maintainer/setup_new_repo/index.html index 9caa7e3a..c954a802 100644 --- a/pages/maintainer/setup_new_repo/index.html +++ b/pages/maintainer/setup_new_repo/index.html @@ -6,13 +6,13 @@ Setting up a new repo | Rush - +
    Rush StackShopBlogEvents

    Setting up a new repo

    This tutorial walks through the process of consolidating several projects into a new Rush monorepo. (If you'd like to see a fully worked out sample based on these steps, take a look at the rush-example repo on GitHub.)

    For this example, suppose we have 3 project folders, like this:

    • my-app: a web application
    • my-controls: a control library used by the application
    • my-toolchain: a NodeJS build tool used to compile the other projects

    Initially each of these projects is in its own folder. They are built using a cumbersome procedure like this:

    ~$ cd my-toolchain
    ~/my-toolchain$ npm run build
    ~/my-toolchain$ npm link
    ~/my-toolchain$ cd ../my-controls
    ~/my-controls$ npm link my-toolchain
    ~/my-controls$ npm run build
    ~/my-controls$ npm link
    ~/my-controls$ cd ../my-app
    ~/my-app$ npm link my-toolchain
    ~/my-app$ npm link my-controls
    ~/my-app$ npm run build

    Let's Rushify these projects!

    Step 1: Check your Rush version​

    Before we get started, make sure you have the latest Rush release installed globally:

    ~$ npm install -g @microsoft/rush

    NOTE: If this command fails because your user account does not have permissions to access NPM's global folder, you may need to fix your NPM configuration.

    Step 2: Use "rush init" to initialize your repo​

    Let's assume you already created an empty GitHub repo that we will copy these projects into. Clone your repo somewhere and then run rush init to generate Rush's config files:

    ~$ git clone https://github.com/my-team/my-repo
    ~$ cd my-repo
    ~/my-repo$ rush init

    It will generate these files (see Config file reference for more info):

    FileWhat it does
    rush.jsonThe main configuration file for Rush
    .gitattributes(Delete this file if you're not using Git.)
    Tells Git not to perform merging operations for shrinkwrap files, because it is unsafe.
    .gitignore(Delete this file if you're not using Git.)
    Tells Git not to track temporary files created by Rush.
    .github/workflows/ci.yml(Delete this file if you're not using GitHub Actions.)
    Configures the GitHub Actions service to perform PR builds using Rush.
    common/config/rush/.npmrcRush uses this file to configure the package registry, regardless of whether the package manager is PNPM, NPM, or Yarn.
    common/config/rush/.npmrc-publishRush uses this file instead of .npmrc when publishing NPM packages.
    common/config/rush/.pnpmfile.cjs(Delete this file if you've chosen to use NPM or Yarn instead of PNPM.)
    Used to workaround problems with dependencies that have mistakes in their package.json file.
    common/config/rush/artifactory.json(Delete this file if you're not using Artifactory.)
    Used to define a custom rush setup experience for configuring Artifactory credentials.
    common/config/rush/build-cache.jsonUsed to configure Rush's cloud build cache.
    common/config/rush/command-line.jsonYou can use this to define custom commands/parameters that will become part of the Rush command-line.
    common/config/rush/common-versions.jsonUsed to specify NPM dependency version selections that affect all projects in a Rush repo.
    common/config/rush/experiments.jsonUsed to enable experimental features of Rush.
    common/config/rush/pnpm-config.jsonUsed to configure how the PNPM package manager behaves during rush install and rush update.
    common/config/rush/rush-plugins.jsonUsed to enable plugins for Rush.
    common/config/rush/version-policies.jsonUsed to define advanced publishing configurations.
    git-hooks/commit-msg.sampleA template for defining Git hooks that will be activated by rush install.

    NOTE: If any of these files already exists in your branch, rush init will issue a warning and will NOT overwrite the existing files.

    Next, add the generated files to Git and commit them to your branch:

    ~/my-repo$ git add .
    ~/my-repo$ git commit -m "Initialize Rush repo"

    Step 3: Customize your configuration​

    The template files have lots of documentation and commented example snippets. We suggest you look over them to familiarize yourself with the basic options and features.

    You can change your options at any time, but there are a few settings in rush.json that you should think about in advance:

    • Choose a package manager: The template defaults to using PNPM, but you can also use NPM or Yarn. See NPM vs PNPM vs Yarn for guidance.

    • Check your Rush version: Make sure your rushVersion setting is the latest version, which is shown in the NPM registry.

    • Check other version fields: Also check that you're using recent stable releases for any other applicable fields such as pnpmVersion, npmVersion, yarnVersion, nodeSupportedVersionRange

    • Decide whether to use the "category folders" model: See the comments in rush.json regarding projectFolderMinDepth and projectFolderMaxDepth, and make a plan for how project folders will be organized in the monorepo

    • Configure your registry access: The initial .npmrc file is configured to use the public NPM registry. If you will be using a private registry, you should update the common/config/rush/.npmrc file.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/setup_policies/index.html b/pages/maintainer/setup_policies/index.html index 5b628c97..fe31427b 100644 --- a/pages/maintainer/setup_policies/index.html +++ b/pages/maintainer/setup_policies/index.html @@ -6,7 +6,7 @@ Enabling policies | Rush - + @@ -14,7 +14,7 @@
    Rush StackShopBlogEvents

    Enabling policies

    The rush-schema.json JSON schema defines some additional settings you can specify in rush.json.

    projectFolderMinDepth: Controlling folder size​

    Rush repositories can grow very big. When you have lots of projects (and maybe several repositories), it's very useful to impose a standard structure that makes it immediately obvious which folders contain buildable projects. We suggest a convention like this:

    • In the repo, top-level folders are "category folders" (e.g. "~/demo/libraries")
    • Project folders are always nested under a category folder (e.g. "~/demo/libraries/lib1")
    • A project folder must always be at the second level (e.g. we forbid nesting such as "~/demo/libraries/lib1/lib2")
    • Cross-project files are always stored in the common folder (e.g. "~/demo/common/docs", "~demo/common/scripts", etc.)
    • There are no exceptions to these rules

    If we want to adopt this policy for our demo repo, we can move the projects into category folders like this:

    ~/demo/apps/application
    ~/demo/libraries/lib1
    ~/demo/libraries/lib2

    ...and then enforce that projects must be a the second level using these settings in ~/demo/rush.json:

      // The minimum folder depth for the projectFolder field.
      // (The default value is 1, i.e. no slashes in the path name.)
      "projectFolderMinDepth": 2,
      // The maximum folder depth for the projectFolder field.
      // (The default value is 2, i.e. a single slash in the path name.)
      "projectFolderMaxDepth": 2,

    allowedEmailRegExps: Avoiding private e-mail addresses​

    Git requires every commit to be accompanied by a name and e-mail address. However, there is no validation of these fields, and their defaults are pulled from a global setting on your PC that's easy to forget about. When using Git for work, people often accidentally commit using an unintended e-mail address that looks... not so professional. If the repo is hosted on GitHub, these e-mail addresses immediately become queryable via the GitHub REST API, easy pickings for unscrupulous spammers. (The privacy settings for your GitHub account don't affect "git commit".)

    Rush can help, though. The "gitPolicy" setting in rush.json allows you to specify a list of acceptable e-mail patterns for a repository. The patterns are regular expressions. (Since they are inside a JSON string literal, note that backslashes must be double-escaped.)

      "gitPolicy": {
        // A list of regular expressions describing allowable e-mail patterns
        // for Git commits.  They are case-insensitive anchored JavaScript RegExps.
        // Example: ".*@example\\.com"
        "allowedEmailRegExps": [
          // Require GitHub scrubbed e-mails
          "[^@]+@users\\.noreply\\.github\\.com"
        ],

        // An example valid e-mail address for "Mr. Example" that conforms to one
        // of the allowedEmailRegExps.  Example: "mr-example@contoso.com"
        "sampleEmail": "mrexample@users.noreply.github.com"
      },

    Whenever the developer runs rush install, Rush will check that their e-mail address follows one of the patterns. If not, it displays a warning like this:

    rush install
    Rush Multi-Package Build Tool

    Checking Git policy for this repository.

    Hey there!  To keep things tidy, this repo asks you to submit your Git commmits
    using an e-mail like this pattern:

        [^@]+@users\.noreply\.github\.com

    ...but yours is configured like this:

        Bob <bobbles@somewhere.sketchy.int>

    To fix it, you can use commands like this:

        git config --local user.name "Mr. Example"
        git config --local user.email "mrexample@users.noreply.github.com"

    Aborting, so you can go fix your settings.  (Or use --bypass-policy to skip.)

    approvedPackagesPolicy: Reviewing new NPM dependencies​

    Are there certain people on your team who constantly find exciting new libraries and add them to your package.json? This can quickly get out of hand, especially in environments that require legal or security reviews for external code. The approvedPackagesPolicy feature allows you to detect when new NPM dependencies are introduced.

    Since different levels of scrutiny are often required (e.g. for a shipping product, versus an intern project, versus an internal library), we distinguish "review categories". This allows us to approve a package once for an entire category of projects, while still being alerted when the dependency is used somewhere else.

    Continuing the example scenario from Setting up a new repo, here's how we would update rush.json to define some review categories for "published" versus "internal" projects:

    {
      "rushVersion": "4.0.0",
      "npmVersion": "5.5.1",
      "nodeSupportedVersionRange": ">=8.9.0 <9.0.0",

      "approvedPackagesPolicy": {
        "reviewCategories": [ "published", "internal" ],
        // We don't need to review @types packages, because we can assume
        // the untyped package should already have been approved
        "ignoredNpmScopes": [ "@types" ]
      },

      "projects": [
        {
          "packageName": "application",
          "projectFolder": "application",
          "reviewCategory": "internal"
        },
        {
          "packageName": "lib1",
          "projectFolder": "lib1",
          "reviewCategory": "internal"
        },
        {
          "packageName": "lib2",
          "projectFolder": "lib2",
          "reviewCategory": "published"
        }
      ]
    }

    When you run rush install, it will create two files that report your dependencies. These files should be added to Git and can be configured so that changes require approval:

    • ~/demo/common/config/rush/browser-approved-packages.json: Packages approved for usage in a web browser. This is generally the stricter of the two types, so by default all new packages are added to this file. For web browser dependencies, the review discussion typically focuses on: How big is the minified code? What's the license? Are there security issues?
    • ~/demo/common/config/rush/nonbrowser-approved-packages.json: Packages approved for usage everywhere except in a web browser. This review discussion typically focuses on: How much clutter will it pull into our node_modules folder? Do we already have an equivalent package? Is there any real code in there, or is it a just a flimsy wrapper for another package?

    After running rush install, the browser-approved-packages.json file might look like this:

    {
      "packages": [
        {
          "name": "@rushstack/heft",
          "allowedCategories": [ "internal" ]
        },
        {
          "name": "@rushstack/node-library-build",
          "allowedCategories": [ "internal", "published" ]
        },
        {
          "name": "semver",
          "allowedCategories": [ "internal", "published" ]
        }
      ]
    }

    For example, this file is showing that the external dependency @rushstack/heft was found in the package.json file for an "internal" project (let's say ~/demo/lib1) but not any "public" project (such as ~/demo/application).

    Rush has no way to detect whether an NPM package is for the browser or not. Since these are all non-browser files, you must manually move them to the other file browser-approved-packages.json.

    How approvals work​

    Whenever rush install is run, the content in these files will be broadened to match the current contents of package.json. This file should be committed to Git. When the developer creates a pull request, the PR diff can be used e.g. to trigger a special approval.

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/maintainer/using_rush_plugins/index.html b/pages/maintainer/using_rush_plugins/index.html index 3b3f102d..9a2f6ec5 100644 --- a/pages/maintainer/using_rush_plugins/index.html +++ b/pages/maintainer/using_rush_plugins/index.html @@ -6,7 +6,7 @@ Using Rush plugins (experimental) | Rush - + @@ -24,7 +24,7 @@ packages are currently built-in to Rush and enabled automatically. For now, you should NOT register them in rush-plugins.json.

    This is a temporary accommodation while the plugin framework is still experimental. In the next major release of Rush, the build cache packages will need to be configured in standard way.

    Third-party plugins​

    Here's a gallery of some community contributed plugins.

    NPM PackageDescription
    rush-archive-project-pluginArchive Rush projects that are no longer maintained
    rush-github-action-build-cache-pluginSave and restore the build cache in Github actions
    rush-init-project-pluginInitialize new Rush projects
    rush-lint-staged-pluginIntegrate lint-staged with a Rush monorepo
    rush-print-log-if-error-pluginPrint a project's entire log file when an error occurs
    rush-sort-package-jsonSort the package.json file entries for Rush projects
    rush-upgrade-self-pluginA helper for upgrading to the latest release of Rush

    If you created an interesting plugin for Rush, let us know in a GitHub issue. Thanks!

    See also​

    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/pages/news/index.html b/pages/news/index.html index fa111357..cd0f6f6a 100644 --- a/pages/news/index.html +++ b/pages/news/index.html @@ -6,7 +6,7 @@ What's new | Rush - + @@ -15,7 +15,7 @@ CHANGELOG.md.

    Rush is maintained by the Rush Stack developer community. For roadmaps and updates from the team, please visit the Rush Stack News page.

    The Rush Hour monthly video call is the easiest way to find out what's happening with Rush Stack:

    • Sign up using the Events page.
    • If you missed an event, the Past Events archive often includes a green Meeting Notes button with a summary of important points.

    Announcements​

    Follow us on Mastodon (@rushstack@fosstodon.org) or Twitter (@rushstack).

    Mastodon feed for @rushstack@fosstodon.org
    . . .
    •   •   •
    © 2023 Microsoft
    - + \ No newline at end of file diff --git a/search/index.html b/search/index.html index cf3f2e2c..2070a862 100644 --- a/search/index.html +++ b/search/index.html @@ -6,13 +6,13 @@ Search the documentation | Rush - +
    Rush StackShopBlogEvents

    Search the documentation

    © 2023 Microsoft
    - + \ No newline at end of file