How to properly add a domain to Heroku

I'm a software developer and I'm looking to buy a domain so I can host my current and future projects on. I've done research, but as I'm still not sure if I understand this correctly, I am asking here for help.

Let's say I have bought an example.com domain. As the DNS system is hierarchical, I also now own all the subdomains of example.com, like a.example.com, b.example.com and a.b.c.example.com. So, for every new project that I want to deploy I will be able to allocate a projectname.example.com domain.

To exercise this ownership, I'm being given access to the NS record of the .com domain registry through registrar, so i can set the DNS server responsible for resolving my domain. By default this is going to be the server that registrar has provided me with.

When I deploy an application to the cloud, I'll get a url, for example project1.heroku.com. To redirect traffic, I can just create a CNAME or ALIAS records from project1.example.com to project1.heroku.com

But according to the Heroku documentation, I need to add the domain to heroku itself and then crate a CNAME record to url which I will be given upon doing so. Why is that, and why wouldn't the normal url work? Or do I really don't understand something?


This is a very common misconception. A CNAME doesn't perform HTTP redirection nor create an alias to the web server. It simply tells that the DNS A record can be found elsewhere.

The web server only gets the original hostname in the browser's address bar via the Host header. The web server doesn't have any connection with the DNS infrastructure i.e. it doesn't check any CNAME records at all. Therefore, the web server needs to be aware of the hostname (i.e. configured property) in order to serve the correct content (virtual host).