DevelopmentElixirOpen Source

Razor: Hit the Ground Running With Your Next Phoenix Project

Craig Lyons ·

As the popularity of Elixir and Phoenix continues to grow, we find ourselves spinning up more and more Phoenix apps for our clients and side projects. At Carbon Five, we have a pretty good consensus on our favorite practices and tools. With each new app, we find ourselves repeating the same steps to bring in many of the same resources and processes.

We created Razor, an opinionated app generator, to save ourselves this time and trouble. Razor isn’t the only one out there, but it captures our common needs and preferences at Carbon Five pretty comprehensively. It also provides a great platform for discussion; we hope to watch Razor evolve as the Elixir ecosystem grows and we continue to learn.

What’s in the box?

How does it work?

Razor is a CLI interface built to an escript binary. When you run razor new YourAppName, it downloads a copy of the Carbon Five razor-phoenix app skeleton, renames everything for your app, and walks you through the remaining install steps. It also initializes a new git repo, ready to be pushed to an origin of your own.

Installation

Full instructions are here, but here’s the tldr:

  • Install Elixir, yarn, and brunch, and have them available in your path. Razor & the apps you generate will have .tool-versions files to ease version management if you use asdf.
  • Install the latest escript build from github with mix escript.install https://github.com/carbonfive/razor/raw/master/razor_archives/razor.
    The escript is installed to a directory that isn’t in your path by default. You can add it to your path, or create a symlink, i.e. ln -s /path/to/razor /usr/local/bin/
  • Cut your new app with razor new YourAppName
  • Follow the remaining instructions provided by Razor
  • Next, you can run the small built-in test suite withmix test, and spin up the app with any of these .env-friendly methods:
  • source .env; mix phoenix.server
  • heroku local
  • foreman start

Now you can visit http://localhost:4000 to see your fully-featured new app.
That’s it! You’re straight on to building the fun stuff. You can remove the demo bits (or keep them).

How about deployment?

Your new app can be deployed to Heroku Pipelines with both acceptance and production environments, in just a couple minutes by following the deployment instructions. If you use CircleCI, you get continuous integration testing right out of the box. The baked-in deployment configuration is also agnostic enough to be used in many modern deployment environments.

Why did we pick these things, and are they subject to change?

We’ve used these tools & processes on small fun projects and large production apps, and they’ve proven themselves reliable and useful in the majority of them. The Elixir ecosystem is evolving pretty rapidly, so it’s likely Razor will also change significantly over time. It’s worth noting that changes to Razor will not require changes to the generated apps themselves.
We’d also like to see Razor adopt more options (some listed below) so it can land in the sweet spot of ease, flexibility, and power.

With Mogwai comes much responsibility

Razor makes it a little too easy to spin up a Phoenix app with a fair amount of complexity (many say Phoenix itself is guilty of this too). The Elixir ecosystem is strong due largely to its dedication to depth of understanding, so we recommend spinning up a Phoenix app or two yourself first, and come back to Razor once you have a clear idea of how everything works. It’s also good to review the razor-phoenix source to learn how it’s all baked in.

What’s next?

Help us sharpen Razor! Try it on your system. If you find issues or have ideas, please put up issues and pull requests. Here are a few suggestions to get you started:

  • CircleCI 2.0
  • Dockerized version
  • Flag for installing with webpack instead of brunch

Most importantly, enjoy using Razor!

Related Posts

Craig Lyons
Craig Lyons