Vercel CLI monorepo support

[andrevenancio]

I would like to bring your attention to this quote from vercel's documentation

Using Monorepos with Vercel CLI
Vercel CLI should always be invoked from the monorepo root, not the subdirectory.

First, run vercel link to select the Vercel Project (you can only link to one at a time). Once linked, subsequent commands such as vercel dev will use the selected Vercel Project. To switch to a different Project in the same monorepo, run vercel link again and select the new Project.

Alternatively, you can use git clone to create multiple copies of your monorepo in different directories and link each one to a different Vercel Project.

There is no explanation to why vercel link needs to be run from the root of the monorepo, but it doesn't make sense from a scaling POV. Let me explain

I'm running Turborepo to manage multiple applications and packages within my Organisation. Assume this illustrative folder structure

apps
  app1
  app2
packages
  package1
  package2
  package3

All examples and documentation across vercel CLI and turborepo suggest:

• Go to vercel.app create a new project and link to our monorepo github repository.
• We are asked to specify which of the apps we would like to deploy (lets assume apps/app1 and we're off to the races).
• we add a env variable called NEXT_PUBLIC_GOOGLE_ANALYTICS (analytics is just a generic example) add a value to it and define that across dev, preview, production.

On our local copy of the repository we then need to run vercel link from the root. Following the steps we login to our Org, we select our Project and we run vercel env pull to populate the dev environment variables for the selected project (which I remind you was apps/app1

So now we have a new file on our monorepo .env.local which contains our NEXT_PUBLIC_GOOGLE_ANALYTICS.

apps
  app1
  app2
packages
  package1
  package2
  package3
.env.local

Now lets go back to vercel.app and lets create another project and associate it with the same monorepo but this time with apps/app2.
We go to the dashboard of this new app, and we add the same exact env variable and we have a different value now.

Now I would expect that since both projects have been created and they have their own set of env variables with different values that when applications are build and deploy they run off those env variables. And they do.

I would also expect that if I want to run npm run dev (concurrently run app1 and app2 that they both have access to their individual env variables). And this is where the design for the Vercel CLI is failing. By requiring it to be on the root of the folder, you are locking each monorepo to only be able to build 1 app at a time, and adding unnecessary steps to vercel link and vercel env pull every time we want to work on either of the apps.

What is a better solution?
I believe a more elegant solution is to do vercel link inside each app/** because its this folder that has to be selected on vercel when creating a new project. So I expect that

cd apps/app1
vercel link
vercel env pull

links the apps/app1 folder to the correct vercel project (e.g. App 1) and pulls the .env.local file to the location apps/app1/.env.local

In the same way I expect that

cd apps/app2
vercel link
vercel env pull

Links the apps/app2 to the App 2 Project on vercel and pulls en env.local to apps/app2/.env.local

Therefore My final structure will be

apps
  app1
    .env.local
  app2
    .env.local
packages
  package1
  package2
  package3

This is the expected behavior. What is not expected, and perhaps is a silly suggestion is that we need to duplicate the whole monorepo in a different folder on our machine so we can have each folder link to a different app.

I would like to understand if this issue is part of the roadmap for Vercel CLI and Turborepo.

This issue was first discussed 2 weeks ago here With no feedback, I'm hopping to have someone from the team to be able to help advise on this.

[anthonyshew]

We have vc link --repo currently in alpha for monorepo support.

Using link --repo, you can link your entire repo to all you Vercel projects in one command. Vercel CLI will become context-aware in your project directories or you can run vc env pull at the root to grab all your environment variables for all your projects.

[andrevenancio]

Hi @anthonyshew , thanks for your reply. I can confirm that this alpha feature solves the issue, and its quite elegant! Thank you

[unitof]

Woah! So happy I stumbled upon this. Is this documented anywhere? This is beautiful and long awaited!

So I'm gussing vc link --repo must be run from within a Git repo after each subproject has been created on Vercel, and linked to GitHub?

▶ vc link --repo
Vercel CLI 34.1.13
WARN! The `--repo` flag is in alpha, please report issues
? Link Git repository at “~/repos/nc/bh-briet” to your Project(s)? yes
? Which scope should contain your Project(s)? no comment LLC
> Found 5 Projects linked to [email protected]:yescomment/bh-briet.git under nocomment
? Which Projects should be linked to?
❯◉ nocomment/bh-briet-server
 ◉ nocomment/bh-briet-tagger
 ◉ nocomment/bh-briet-jacket
 ◉ nocomment/bh-briet-market
 ◉ nocomment/bh-briet-reader

Even cooler, this seems to enable root inference across the entire repository, so vc commands "track back" up to the nearest project root, from any CWD deep within the repo!

So: vc link --repo is super useful even in single-project repos, as it finally allows us to vc commands from anywhere within the repo.

It's a Ship 24 miracle 🖤, see some of you tomorrow

[wladpaiva]

@anthonyshew not sure if I'm facing a bug here but vc env pull from the root directory create only the .env.local in the root folder from whatever project I select.

If I navigate into the folders and run it again it pulls envs as it supposed to.

Am I missing something?

[joelybahh]

@anthonyshew That sounds incredible, was there an update on the status of this? Was it still in alpha? does it work for pushing all .env.local for example, to seed vercel with the current development envs?

[anthonyshew]

Still in alpha but it's in our docs now and we're looking for feedback!: https://vercel.com/docs/cli/link#repo-alpha

Yes, this feature will help you to pull environment variables for all of the projects in your monorepo quicker.