PlugAndPlay 🔌►

Set up a Plug application with less boilerplate.

PlugAndPlay is not a web framework – it's a small scaffold. You use Plug as you would normally, only sooner.

Later, if you need more control, you can easily replace PlugAndPlay piece by piece or wholesale.

Setting up a Plug app, the easy way

Generate a new project with --sup, e.g.

mix new hello_world --sup

Open mix.exs and add plug_and_play to your list of dependencies:

def deps do
  [
    {:plug_and_play, "~> 0.7.0"},
  ]
end

(This makes PlugAndPlay conveniences available and saves you from manually adding Plug and the Cowboy web server to the deps list.)

Make your root module (e.g. lib/hello_world.ex) look something like:

defmodule HelloWorld do
  defmodule Router do
    use PlugAndPlay.Router

    get "/" do
      send_resp conn, 200, "Hello world!"
    end

    match _ do
      send_resp conn, 404, "404!"
    end
  end
end

(This saves you from manually including some Plug.Router boilerplate.)

Make your application module (e.g. lib/hello_world/application.ex) look something like:

defmodule HelloWorld.Application do
  use PlugAndPlay.Application, router: HelloWorld.Router
end

(This saves you from manually setting up a Supervisor to run your app in the Cowboy web server on the right port.)

Now you should be able to start the app in a terminal with:

mix deps.get
mix server

(This saves you from typing mix run --no-halt.)

It outputs the URL at which the server runs - usually http://0.0.0.0:8080. Go there and marvel!

Custom port number

The default port is 8080.

If the environment variable PORT is set, that port number will be used. This is the convention on e.g. Heroku and with Dokku, meaning things will Just Work™ if you deploy there.

Or you can assign a port explicitly, e.g. from application config.

Assuming you have config like this in config/config.exs:

config :hello_world, port: 1234

You could do this in lib/hello_world/application.ex:

defmodule HelloWorld.Application do
  use PlugAndPlay.Application,
    router: HelloWorld.Router,
    port: Application.get_env(:hello_world, :port)
end

If you set up your own supervision tree, you can also specify the port there.

Custom plug pipeline

If you need additional plugs, skip use PlugAndPlay.Router and simply write out the code instead:

use Plug.Router

plug :match
plug :my_custom_plug
plug :dispatch

You can still use the rest of the PlugAndPlay conveniences, of course, even if you skip PlugAndPlay.Router.

Custom supervision

By default, PlugAndPlay defines a supervision tree for you so you don't have to. If that's all you need, ignore this section.

If you want more control, you can define your own supervision tree with PlugAndPlay.Supervisor as one of its children.

Make your main application (e.g. lib/hello_world/application.ex) look something like:

defmodule HelloWorld.Application do
  use Application

  def start(_type, _args) do
    children = [
      PlugAndPlay.Supervisor.child_spec(HelloWorld.Router),
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

You can specify the desired port as a second argument to child_spec.

You can specify multiple instances as long as they have different routers and ports:

children = [
  PlugAndPlay.Supervisor.child_spec(HelloWorld.RouterOne, 1111),
  PlugAndPlay.Supervisor.child_spec(HelloWorld.RouterTwo, 2222),
]

Credits and license

By Henrik Nyh 2017-02-25 under the MIT License.