1"use strict";(self.webpackChunkrushjs_io=self.webpackChunkrushjs_io||[]).push([[3450],{5552(e,t,n){n.d(t,{xA:()=>g,yg:()=>y});var r=n(829);function a(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 r=Object.getOwnPropertySymbols(e);t&&(r=r.filter(function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable})),n.push.apply(n,r)}return n}function i(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?o(Object(n),!0).forEach(function(t){a(e,t,n[t])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):o(Object(n)).forEach(function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))})}return e}function s(e,t){if(null==e)return{};var n,r,a=function(e,t){if(null==e)return{};var n,r,a={},o=Object.keys(e);for(r=0;r<o.length;r++)n=o[r],t.indexOf(n)>=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r<o.length;r++)n=o[r],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var p=r.createContext({}),l=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},g=function(e){var t=l(e.components);return r.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef(function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,p=e.parentName,g=s(e,["components","mdxType","originalType","parentName"]),u=l(n),y=a,c=u["".concat(p,".").concat(y)]||u[y]||m[y]||o;return n?r.createElement(c,i(i({ref:t},g),{},{components:n})):r.createElement(c,i({ref:t},g))});function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=u;var s={};for(var p in t)hasOwnProperty.call(t,p)&&(s[p]=t[p]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l<o;l++)i[l]=n[l];return r.createElement.apply(null,i)}return r.createElement.apply(null,n)}u.displayName="MDXCreateElement"},1355(e,t,n){n.r(t),n.d(t,{assets:()=>g,contentTitle:()=>p,default:()=>y,frontMatter:()=>s,metadata:()=>l,toc:()=>m});var r=n(6443),a=n(8338),o=(n(829),n(5552)),i=["components"],s={title:"Setting up a new repo"},p=void 0,l={unversionedId:"pages/maintainer/setup_new_repo",id:"pages/maintainer/setup_new_repo",title:"Setting up a new repo",description:"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.)",source:"@site/docs/pages/maintainer/setup_new_repo.md",sourceDirName:"pages/maintainer",slug:"/pages/maintainer/setup_new_repo",permalink:"/pages/maintainer/setup_new_repo",draft:!1,editUrl:"https://github.com/microsoft/rushstack-websites/tree/main/websites/rushjs.io/docs/pages/maintainer/setup_new_repo.md",tags:[],version:"current",frontMatter:{title:"Setting up a new repo"},sidebar:"docsSidebar",previous:{title:"Using project tags",permalink:"/pages/developer/project_tags"},next:{title:"Adding projects to a repo",permalink:"/pages/maintainer/add_to_repo"}},g={}
1,m=[{value:"Step 1: Check your Rush version",id:"step-1-check-your-rush-version",level:2},{value:"Step 2: Use "rush init" to initialize your repo",id:"step-2-use-rush-init-to-initialize-your-repo",level:2},{value:"Step 3: Customize your configuration",id:"step-3-customize-your-configuration",level:2}],u={toc:m};function y(e){var t=e.components,n=(0,a.A)(e,i);return(0,o.yg)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,o.yg)("head",null,(0,o.yg)("link",{rel:"canonical",href:"https://rushstack.io/pages/pages/maintainer/setup_new_repo/"})),(0,o.yg)("p",null,"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 ",(0,o.yg)("a",{parentName:"p",href:"https://github.com/microsoft/rush-example"},"rush-example")," repo on GitHub.)"),(0,o.yg)("p",null,"For this example, suppose we have 3 project folders, like this:"),(0,o.yg)("ul",null,(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"my-app"),": a web application"),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"my-controls"),": a control library used by the application"),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"my-toolchain"),": a NodeJS build tool used to compile the other projects")),(0,o.yg)("p",null,"Initially each of these projects is in its own folder. They are built using a cumbersome procedure like this:"),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre"},"~$ cd my-toolchain\n~/my-toolchain$ npm run build\n~/my-toolchain$ npm link\n~/my-toolchain$ cd ../my-controls\n~/my-controls$ npm link my-toolchain\n~/my-controls$ npm run build\n~/my-controls$ npm link\n~/my-controls$ cd ../my-app\n~/my-app$ npm link my-toolchain\n~/my-app$ npm link my-controls\n~/my-app$ npm run build\n")),(0,o.yg)("p",null,"Let's Rushify these projects!"),(0,o.yg)("h2",{id:"step-1-check-your-rush-version"},"Step 1: Check your Rush version"),(0,o.yg)("p",null,"Before we get started, make sure you have the latest Rush release installed globally:"),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre"},"~$ npm install -g @microsoft/rush\n")),(0,o.yg)("p",null,(0,o.yg)("em",{parentName:"p"},"NOTE: If this command fails because your user account does not have permissions to access NPM's global folder, you may need to ",(0,o.yg)("a",{parentName:"em",href:"https://docs.npmjs.com/getting-started/fixing-npm-permissions"},"fix your NPM configuration"),".")),(0,o.yg)("h2",{id:"step-2-use-rush-init-to-initialize-your-repo"},'Step 2: Use "rush init" to initialize your repo'),(0,o.yg)("p",null,"Let's assume you already created an empty GitHub repo that we will copy these projects into. Clone your repo somewhere and then run ",(0,o.yg)("inlineCode",{parentName:"p"},"rush init")," to generate Rush's config files:"),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre"},"~$ git clone https://github.com/my-team/my-repo\n~$ cd my-repo\n~/my-repo$ rush init\n")),(0,o.yg)("p",null,"It will generate these files (see ",(0,o.yg)("a",{parentName:"p",href:"/pages/advanced/config_files"},"Config file reference")," for more info):"),(0,o.yg)("table",null,(0,o.yg)("thead",{parentName:"table"},(0,o.yg)("tr",{parentName:"thead"},(0,o.yg)("th",{parentName:"tr",align:"left"},"File"),(0,o.yg)("th",{parentName:"tr",align:"left"},"What it does"))),(0,o.yg)("tbody",{parentName:"table"},(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"rush.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"The main configuration file for Rush")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},".gitattributes")),(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("em",{parentName:"td"},"(Delete this file if you're not using Git.)")," ",(0,o.yg)("br",null),"Tells Git not to perform merging operations for shrinkwrap files, because it is unsafe.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},".gitignore")),(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("em",{parentName:"td"},"(Delete this file if you're not using Git.)")," ",(0,o.yg)("br",null),"Tells Git not to track temporary files created by Rush.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},".github/workflows/ci.yml")),(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("em",{parentName:"td"},"(Delete this file if you're not using GitHub Actions.)")," ",(0,o.yg)("br",null),"Configures the ",(0,o.yg)("a",{parentName:"td",href:"https://github.com/features/actions"},"GitHub Actions")," service to perform PR builds using Rush.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/.npmrc")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Rush uses this file to configure the package registry, regardless of whether the package manager is PNPM, NPM, or Yarn.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/.npmrc-publish")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Rush uses this file instead of ",(0,o.yg)("strong",{parentName:"td"},".npmrc")," when publishing NPM packages.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/.pnpmfile.cjs")),(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("em",{parentName:"td"},"(Delete this file if you've chosen to use NPM or Yarn instead of P
1NPM.)")," ",(0,o.yg)("br",null),"Used to workaround problems with dependencies that have mistakes in their package.json file.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/artifactory.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("em",{parentName:"td"},"(Delete this file if you're not using Artifactory.)")," ",(0,o.yg)("br",null),"Used to define a custom ",(0,o.yg)("inlineCode",{parentName:"td"},"rush setup")," experience for configuring Artifactory credentials.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/build-cache.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Used to configure Rush's cloud build cache.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/command-line.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"You can use this to define custom commands/parameters that will become part of the Rush command-line.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/common-versions.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Used to specify NPM dependency version selections that affect all projects in a Rush repo.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/experiments.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Used to enable experimental features of Rush.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/pnpm-config.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Used to configure how the PNPM package manager behaves during ",(0,o.yg)("inlineCode",{parentName:"td"},"rush install")," and ",(0,o.yg)("inlineCode",{parentName:"td"},"rush update"),".")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/rush-plugins.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Used to enable plugins for Rush.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"common/config/rush/version-policies.json")),(0,o.yg)("td",{parentName:"tr",align:"left"},"Used to define advanced publishing configurations.")),(0,o.yg)("tr",{parentName:"tbody"},(0,o.yg)("td",{parentName:"tr",align:"left"},(0,o.yg)("strong",{parentName:"td"},"git-hooks/commit-msg.sample")),(0,o.yg)("td",{parentName:"tr",align:"left"},"A template for defining Git hooks that will be activated by ",(0,o.yg)("inlineCode",{parentName:"td"},"rush install"),".")))),(0,o.yg)("p",null,(0,o.yg)("strong",{parentName:"p"},"NOTE: If any of these files already exists in your branch, ",(0,o.yg)("inlineCode",{parentName:"strong"},"rush init")," will issue a warning and will NOT overwrite the existing files.")),(0,o.yg)("p",null,"Next, add the generated files to Git and commit them to your branch:"),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre"},'~/my-repo$ git add .\n~/my-repo$ git commit -m "Initialize Rush repo"\n')),(0,o.yg)("h2",{id:"step-3-customize-your-configuration"},"Step 3: Customize your configuration"),(0,o.yg)("p",null,"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."),(0,o.yg)("p",null,"You can change your options at any time, but there are a few settings in ",(0,o.yg)("strong",{parentName:"p"},"rush.json")," that you should think about in advance:"),(0,o.yg)("ul",null,(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"Choose a package manager"),": The template defaults to using PNPM, but you can also use NPM or Yarn. See ",(0,o.yg)("a",{parentName:"p",href:"/pages/maintainer/package_managers"},"NPM vs PNPM vs Yarn")," for guidance.")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"Check your Rush version"),": Make sure your ",(0,o.yg)("inlineCode",{parentName:"p"},"rushVersion")," setting is the latest version, which is shown in the ",(0,o.yg)("a",{parentName:"p",href:"https://www.npmjs.com/package/@microsoft/rush"},"NPM registry"),".")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"Check other version fields"),": Also check that you're using recent stable releases for any other applicable fields such as ",(0,o.yg)("inlineCode",{parentName:"p"},"pnpmVersion"),", ",(0,o.yg)("inlineCode",{parentName:"p"},"npmVersion"),", ",(0,o.yg)("inlineCode",{parentName:"p"},"yarnVersion"),", ",(0,o.yg)("inlineCode",{parentName:"p"},"nodeSupportedVersionRange"))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},'Decide whether to use the "category folders" model'),": See the comments in ",(0,o.yg)("strong",{parentName:"p"},"rush.json")," regarding ",(0,o.yg)("inlineCode",{parentName:"p"},"projectFolderMinDepth")," and ",(0,o.yg)("inlineCode",{parentName:"p"},"projectFolderMaxDepth"),", and make a plan for how project folders will be organized in the monorepo")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"Configure your registry access"),": The initial ",(0,o.yg)("strong",{parentName:"p"},".npmrc")," file is configured to use the public NPM registry. If you will be using a ",(0,o.yg)("a",{parentName:"p",href:"/pages/maintainer/npm_registry_auth"},"private registry"),", you should update the ",(0,o.yg)("strong",{parentName:"p"},"common/config/rush/.npmrc")," file."))))}y.isMDXComponent=!0}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.