RFC: Refactoring the CLI to prefer the Monorepo onboarding flow

[matthewvolk]

We have received a ton of feedback (mostly in our developer Slack workspace, which you can join here) that working out of the Catalyst monorepo leads to a better developer experience than working out of the project structure scaffolded by the current create-catalyst CLI; in fact, we've received some requests asking if we can refactor the current CLI such that it simply automates the alternative monorepo onboarding documentation.

Our goal with the create-catalyst CLI is to provide the most seamless Catalyst onboarding flow and to always prioritize developer experience; right now, we are in a fragmented situation in which the CLI outputs a project that looks different from the alternative onboarding documentation. This is a source of confusion, and by converging on a single flow, we can better support all developers working on Catalyst.

Below I am proposing a set of changes that will help bring the CLI from its current state, to a future state that is in line with the alternative documentation available at https://www.catalyst.dev/docs/monorepo. Additionally, instead of referring to the monorepo onboarding flow as the "alternative" onboarding flow, I propose that we should refer to it as the "recommended" onboarding flow.

Important

This set of changes contains breaking changes; if you have any feedback that you think we should consider that argues against refactoring the create-catalyst CLI as proposed below, please comment below letting us know.

Non-breaking Changes

These changes add simple utilities for Git commands needed to clone the Catalyst repository, configure Git remotes, and checkout Git refs if specified.

• Add isExecException type guard to be consumed by hasGitHubSSH and checkoutRef below (refactor(cli): add isExecException to check if an error is an ExecException #1431)
• Add hasGitHubSSH function to determine whether or not to use SSH when interacting with GitHub remotes (refactor(cli): add hasGitHubSSH function to check if GitHub SSH authentication is successful #1432)
• Add checkoutRef function to allow user to specify an arbitrary ref to checkout after cloning the repository (refactor(cli): add checkoutRef function to handle checking out a specific ref #1433)

Breaking Changes

These changes add utilities used to check prerequisites (Node.js, pnpm, and Git versions), removes dead code no longer used in the new flow, and refactors existing code around cloning the Catalyst repository onto your machine.

• Required Node.js Version should not allow for versions higher than Node.js 20 (refactor(cli): update required Node.js version #1434)
• Ensure pnpm is installed on the machine running the CLI (refactor(cli)!: ensure pnpm is installed on the machine running the CLI #1435)
• Ensure git is installed on the machine running the CLI (refactor(cli)!: ensure git is installed on the machine running the CLI #1436)
• Remove applyIntegrations, since integrations can now be consumed by simply fetching the appropriate remote integrations/* branch from upstream, and creating a branch from the remote (refactor(cli)!: remove applyIntegration and --integration CLI flag #1437)
• Refactor cloneCatalyst to simply clone the monorepo and optionally check out a specified ref (refactor(cli)!: make cloneCatalyst clone bigcommerce/catalyst #1438)
• Remove getLatestCoreTag since we should always recommend cloning the bigcommerce/catalyst repo at main instead of the latest core tag (refactor(cli)!: remove unused getLatestCoreTag function #1439)
• Simplify installDependencies so that it installs dependencies found in the root package.json of the monorepo (refactor(cli)!: simplify installDependencies to install all monorepo deps #1440)
• Remove pm because the package manager will now always be pnpm (refactor(cli)!: remove ability to choose package manager other than pnpm #1441)
• Remove auto generation of gql types on project creation (refactor(cli)!: remove auto generation of gql types on project creation #1443)

Docs Changes

• Update the deployment docs to document Vercel project settings required for successful deployment of the monorepo (refactor(docs): adjust the deployment docs to account for monorepo config #1468)