`vercel-submodules`:
The CLI to handle
Private Git Submodules
in your Vercel Project

This project is community-driven and not affiliated with Vercel in any way. However, I'd love to contribute!

The Status Quo

@vercel Support for private Git Submodules #44

With Git Submodules, you can add other repositories as a subdirectory of another repository. The experimental.externalDir option in Next.js makes it even more magical by directly transpiling external libraries.

However, Vercel does not support private Git Submodules for now. There have been many community-made workarounds, like calling Vercel CLI inside GitHub Actions (not a fundamental solution) or using shell scripts (it works, but it cannot fit general needs like cloning multiple repositories, auto-response for newly added submodules), having their own set of limitations.

📦 Installation and Usage

yarn add -D vercel-submodules

Go to the Build & Development Settings section and override Install Command with vercel-submodules --all && (...). Such as vercel-submodules --all && yarn install.

Once configured, vercel-submodules take care of everything. It detects the indicated commit hashes with all or configured submodules; you don't have to update anything again!

Clone all Submodules

npx vercel-submodules --all

This command clones all submodules inside the repository.

Clone only specific Submodules

npx vercel-submodules --paths packages/module-a ./packages/module-b docs

This command above will clone submodules with the following path:

./packages/module-a
./packages/module-b
./docs

Configure clone depth

npx vercel-submodules --depth 10

The default value is 1.

Set GitHub Token

You'll need to configure your GitHub token in order to clone private repositories in Vercel. Follow these steps:

Go to your GitHub Developer settings > Personal access tokens.
Click "Generate new token".
Give the token a name and select the repo (Full control of private repositories) permission.
Click "Generate token". You will then be presented with a token that you can use to authenticate with GitHub.
Add the resulting token as an Environment Variable in Vercel called GITHUB_TOKEN.

Alternatively, you can explicitly set the token argument:

npx vercel-submodules --token 7777777141f111cf9f0308a63dbd9d0cad3010c4

FYI, that's my Ethereum address 💎

If the GITHUB_TOKEN environment variable is not set, the CLI will attempt to use the default value of $GITHUB_TOKEN.

You can also use the new fine-graned PAT using the --fg-token flag, too.

npx vercel-submodules --fg-token 7777777141f111cf9f0308a63dbd9d0cad3010c4