Deploying Monorepo Applications

A "monorepo" can be roughly defined as a single source code repository that contains multiple, independent components. A common example is a web application that contains both a frontend and backend component.

Monorepos usually come in two distinct types based on whether the components share code or configuration between them.

A repository that contains components that are isolated to the directory they are contained within and do not directly depend on anything outside of this directory (eg. JS frontend and Python backend).

A repository that contains components which share code or configuration from the root directory or other components in the monorepo (eg. Yarn workspaces or Lerna project).

At Railway, we've been watching the demand for monorepo support steadily increase. But until recently, we didn't have a great solution for deploying them. While we're still working on adding even better support for monorepo deployments, we now offer some basic features that can be used to deploy most monorepo applications today.

Isolated monorepo components are 100% contained in the folder they reside in. For these, we can configure the deployment trigger's "Root Directory" to tell Railway to only look at the specified subdirectory when building the application. Once the trigger is activated, only this directory will be cloned so it will be as if nothing outside it exists.

Components within shared monorepos usually depend heavily on one another to operate. These repositories usually define a global build command that compiles and links all components and dependencies together. Both Yarn workspaces and Lerna projects are common methods for managing these types of JavaScript-based monorepos.

Since each component depends on code and configuration outside its own directory, the Root Directory feature that we used previously will not work. Instead, we'll make use of a brand new Railway feature: Custom Start Commands.

After configuring a custom start command Railway will build the application as it usually does, except it will start the deployment with the given command, instead of the one it detected automatically. This means you can deploy the same monorepo to multiple Railway projects and run a different component within each one.

While these tools get the job done for most monorepo setups, we still have a few tricks up our sleeves for the future. If you have any questions or feedback on monorepo support (or anything else, really) please feel free to join our Discord Community! 🤗