Monorepo Support

A "monorepo" is roughly defined as a single repository that contains multiple runnable components. For example, a web app may have both a frontend and backend component, which could be completely isolated from one another or share a subset of common code between them.

Railway provides a few features to help improve support for deploying monorepos of various types.

Isolated Monorepo
A repository that contains components that are completely isolated to the directory they are contained in (eg. JS frontend and Python backend)

Shared Monorepo
A repository that contains components that share code or configuration from the root directory (eg. Yarn workspace or Lerna project)

Isolated Monorepo

The simplest form of a monorepo is a repository that contains two completely isolated projects, meaning they do not reference any code or configuration outside their respective directories. They may even be written in completely different programming languages.

To deploy this type of monorepo on Railway, define a root directory for the application after when a service is created. To do this: select the service within the project canvas to open up the service view. Click on the Settings tab and scroll down to the root directory option. Setting this means that Railway will only pull down files from that directory when creating new deployments.

Shared Monorepo

Popular in the JavaScript ecosystem, shared monorepos contain multiple components that all share a common root directory. By default, all components are built with a single command from the root directory ( eg. npm run build). However, if you are using Nixpacks, then you can override the build command with the NIXPACKS_BUILD_CMD environment variable.

The start command can be overridden in the Railway settings ( eg. npm run start:backend and npm run start:frontend).

To deploy this type of monorepo in Railway, define a separate custom start command in Service Settings for each project that references the monorepo codebase.