How to deploy multiple apps in a monorepo with Heroku

Laurent Grima
Sep 5, 2018 · 3 min read
Photo by Twixes on Unsplash

At Inato, all our web apps are contained in one monorepo (front-end apps, APIs, …). We use yarn workspaces to manage all of these packages.

To host and run our apps, we use Heroku.

The standard Heroku setup only works for the 1-app-1-repo use case.

So, here is a quick guide on how to host and run multiple apps from multiple yarn workspaces contained in a single Git repository on Heroku.

Disclaimer: this guide assumes a basic knowledge of Heroku (See Getting Started).


Let’s say you have a single Git repository containing multiple applications in yarn workspaces like so:

.
├── package.json
├── packages
│ ├── web-client
│ │ └── package.json
│ └── api
│ └── package.json
└── scripts
└── heroku.build

Both web-client and api are web applications that need to be exposed to the network.

Using a single Procfile to expose several web processes is not possible on Heroku. You won’t be able to have api and web in a Procfile both exposing web apps. I.e. this does not work:

web: yarn workspace web-client start
api: yarn workspace api start

The web process type is special as it’s the only process type that will receive HTTP traffic from Heroku’s routers. Other process types can be named arbitrarily.

from the Heroku documentation.

The proper way to do it is to:

  • Create one dyno for each app (workspace) you want to run
  • Use the multi-procfile buildpack
  • Optionally use environment variables to tweak your build step

Here’s the detail:

1. Create one dyno for each app (workspace) you want to run

$ heroku create web-client --remote heroku-web-client
$ heroku create api --remote heroku-api

Here,web-client is the name of the Heroku app and will make the app available at http://web-client.herokuapp.com, while heroku-web-client is the name of the git remote pointing to this heroku app and makes it possible to deploy your code to one app or the other like so:

$ git push heroku-web-client master

2. Use the multi-procfile buildpack

Imagine you have a single code base, which has a few different applications within it… or at least the ability to run a few different applications. Or, maybe you’re Google with your mono repo?

In any case, how do you manage this on Heroku? You don’t. Heroku applications assume one repo to one application.

Enter the Multi Procfile buildpack, where every app gets a Procfile!

- Write a bunch of Procfiles and scatter them through out your code base.

- Create a bunch of Heroku apps.

- For each app, set PROCFILE=relative/path/to/Procfile/in/your/codebase, and of course: heroku buildpacks:add -a <app> https://github.com/heroku/heroku-buildpack-multi-procfile

- For each app, git push git@heroku.com:<app> master

For our example, we would have one Procfile per workspace:

.
├── package.json
├── packages
│ ├── web-client
│ │ ├── Procfile
│ │ └── package.json
│ └── api
│ ├── Procfile
│ └── package.json
└── scripts
└── heroku.build

containing for instance:

web: yarn workspace api start

3. Optionally use environment variables to tweak your build step

Using environment variables, you can make this script accomplish different things depending on the app.

Exemple:

top-level package.json
./scripts/heroku.build

That’s it !

inato

Thoughts & experiences from the Inato team

Thanks to Bastien Duret

Laurent Grima

Written by

https://laugri.com • Product Manager at Inato • Migrating from engineering to design

inato

inato

Thoughts & experiences from the Inato team

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade