Phoenix Static Buildpack

Purpose

This buildpack is meant to be used with the Heroku Buildpack for Elixir on the Gigalixir Platform. When deploying Phoenix apps to Gigalixir, static assets will need to be compiled. This buildpack sees to it that static assets are compiled and that a corresponding asset manifest is generated.

Features

• Easily customizable to your build needs with its compile hook!
• Works much like the Heroku Buildpack for Elixir!
• Easy configuration with phoenix_static_buildpack.config file
• Automatically sets DATABASE_URL
• If your app doesn't have a Procfile, default web task mix phx.server will be run
• Can configure versions for Node and NPM, including the nodejs entry in an asdf .tool-versions file
• Auto-installs Bower deps if bower.json is in your app's root path
• Caches Node, NPM modules and Bower components
• Can be disabled without removing the buildpack via the PHOENIX_STATIC_BUILDPACK__DISABLED environment variable

Usage

# Create a Gigalixir instance for your project
Gigalixir create

# Deploy
git push -u gigalixir main

Serve with Sass assets

If your project serves Sass assets, you need the sass binary for sass-brunch via ruby buildpack.

Create a Gemfile to include the sass gem:

source 'https://rubygems.org'
ruby '2.3.1'
gem 'sass'

Then run generate the Gemfile.lock:

bundle install

Finally, add the ruby buildpack to your .buildpacks file. Ask Gigalixir Support for any assistance.

Disabling the buildpack

You can disable this buildpack without removing it from your .buildpacks file by setting the PHOENIX_STATIC_BUILDPACK__DISABLED environment variable to 1 or true. When set, detection reports that Phoenix was found but is disabled (and exits non-zero), and the compile step short-circuits early with a message and succeeds without doing any work — so the buildpack is skipped regardless of whether detection runs:

gigalixir config:set PHOENIX_STATIC_BUILDPACK__DISABLED=true

To re-enable it, unset the variable or set it to any other value.

Configuration

Create a phoenix_static_buildpack.config file in your app's root dir if you want to override the defaults. The file's syntax is bash.

If you don't specify a config option, then the default option from the buildpack's phoenix_static_buildpack.config file will be used.

Node version from .tool-versions

If your app has an asdf .tool-versions file in its root dir, the nodejs entry is used as the Node version:

erlang 27.2.2
elixir 1.17.3-otp-27
nodejs 22.19.0

This is the same file the Elixir buildpack reads its erlang and elixir versions from, so a single file can pin every version your app builds with.

An explicit node_version in phoenix_static_buildpack.config still takes precedence, and asdf aliases (lts/jod, system, ...) are ignored with a warning since only an explicit version can be resolved.

Here's a full config file with all available options:

# Clean out cache contents from previous deploys
clean_cache=false

# We can change the filename for the compile script with this option
compile="compile"

# We can set the version of Node to use for the app here
node_version=5.3.0

# We can set the version of NPM to use for the app here (defaults to "latest")
npm_version=2.10.1

# We can set the version of Yarn to use for the app here
yarn_version=1.13.0

# We can set the version of PNPM to use for the app here
pnpm_version=8.15.0

# We can set the path to phoenix app. E.g. apps/phoenix_app when in umbrella.
phoenix_relative_path=.

# Remove node and node_modules directory to keep slug size down if it is not needed.
remove_node=false

# We can change path that npm dependencies are in relation to phoenix app. E.g. assets for phoenix 1.3 support.
assets_path=.

# We can change phoenix mix namespace tasks. E.g. `phoenix` for phoenix < 1.3 support.
phoenix_ex=phx

Compile

By default, Phoenix uses brunch and recommends you to use mix phx.digest in production. For that, we have a default compile shell script which gets run after building dependencies and just before finalizing the build. The compile file looks like this.

To customize your app's compile hook, just add a compile file to your app's root directory. compile is just a shell script, so you can use any valid bash code. Keep in mind you'll have access to your node_modules and mix. This means that if you're using a Node build tool other than brunch, you can just do something like:

# app_root/compile
cd $phoenix_dir
npm --prefix ./assets run build
mix "${phoenix_ex}.digest" #use the ${phoenix_ex} variable instead of hardcoding phx or phoenix

The above compile overrides the default one. :)

FAQ

1. When to use?

• This buildpack is only necessary when you need to compile static assets during deploys. You will not need this buildpack if you are using Phoenix only as a REST API.

2. Do I need heroku-buildpack-nodejs with this?

• No, this buildpack installs Node for you. How it differs from the NodeJS buildpack is that it adds mix to the PATH so you can run mix commands like mix phx.digest.

3. I am getting an error Command "deploy" not found. even though my previous deploys used to work. How to fix?

• The default compile file, which are a set of commands ran during the buildpack's compile hook, was replaced to be compatible with Phoenix versions 1.4 and above. If using brunch and older versions of Phoenix, you will need to add a custom compile in your app's root directory that looks like:

brunch build --production

cd $phoenix_dir

mix "${phoenix_ex}.digest"

if mix help "${phoenix_ex}.digest.clean" 1>/dev/null 2>&1; then
  mix "${phoenix_ex}.digest.clean"
fi

Tests

Tests are available in the test directory. To run all tests, use for tst in test/*; do $tst; done.