DEV Community

Cover image for Perfect Elixir: Simplifying Elixir Developer Onboarding
Jon Lauridsen
Jon Lauridsen

Posted on • Edited on

Perfect Elixir: Simplifying Elixir Developer Onboarding

#elixir #tutorial #development #webdev

Onboarding can be a costly but hidden drag on a team — not just in raw setup time, but also in how easily it becomes a process full of uncertainty and fragility. How developers get started reflects the standards of care a team chooses to uphold, and we should explore how simple and safe we can make this experience.

This article will explore how to streamline onboarding through a simple, semi-automated script — striking a balance between ease of use and maintainability.

ℹ️ BTW I've started on projects where onboarding could take two weeks 😱. Senior devs spent hours debugging others' setups — a time sink repeated with every new hire. We can do better!

Table of Contents

 

Redefining Onboarding

When we say onboarding, we mean everything a new developer needs to do to start working on our project.

The traditional approach relies on written guides. But guides come with downsides:

  1. No testability: They can't be validated automatically, easily drifting out of date.
  2. Complexity grows: Old steps tend to stick around "just in case", with new ones piling on.
  3. Hard to maintain: Updates happen under pressure, usually when someone's blocked.

What if we reimagined onboarding as a single command — no dependencies, no guesswork — that guides the developer interactively?

On macOS and Linux systems, the simplest way to run a remote script is:

$ curl -Ssf https://…/script | sh
Enter fullscreen mode Exit fullscreen mode

That's beautifully simple, but it comes with a limit: To onboard we'll want to inspect the user's environment to understand what tools they have configured, and that's not possible when piping to sh (since it spawns a new shell that is not necessarily the same as their working shell).

Instead, using source allows the script to access the user's environment:

$ curl -fsSL https://…/script > /tmp/script && source /tmp/script
Enter fullscreen mode Exit fullscreen mode

That's still incredibly simple, and with this approach, we can move toward a fully guided, low-friction setup. Next, let's look at one of the trickier parts: installing system tools.

 

Beware Global System Changes

For our project, the developer must have installed pkgx, as introduced in the Setting Up an Elixir Dev Environment article. But how do we do that?

First instinct could be to automatically install it, but installing system tools is a risky proposition — here's why we must not do it automatically:

  1. It's invasive: Developers customize their environments. Global changes can break their system or other projects.
  2. It's brittle: There are a lot of environment variance out there, very difficult to write code that will work reliably across all of them.
  3. It's high-maintenance: Continuously testing all the various supported permutations spirals out of control fast

Luckily, we only need pkgx, because it takes care of the rest of the tooling. And it's easy to install manually — no sudo needed. So we should ask the developer to install it, and keep our script focused on guidance, not installation. That will also make our onboarding script much safer and much easier to test — win-win.

 

Implementing the Onboarding Script

 

Building Trust

Our first priority: earn the developer's trust.

Instead of doing anything upfront, our script can clearly explain what it will do — and what it won't:

$ URL="https://raw.githubusercontent.com/gaggle/perfect-elixir/refs/heads/perfect-elixir-5-onboarding/bin/bootstrap"

$ curl -fsSL $URL > /tmp/boot && source /tmp/boot
🚀 Welcome to the Perfect Elixir Onboarding Script! 🚀

This script will help you set up your development environment for our project. 

🔒 Trust and Transparency: 
  - This script NEVER makes changes to your system
  - It ONLY inspects your environment and makes suggestions

Ready to proceed? [y/N]:
Enter fullscreen mode Exit fullscreen mode

🖥️ Terminal

Bootstrap script introducing itself and prompting the user to proceed

Clear. Transparent. Opt-in.

ℹ️ BTW I'm skipping the underlying code here (it just prints text), but the full script is available on GitHub.

 

Step 1: Install pkgx

We check if pkgx is installed:

Ok to proceed? [y/N]: y
• Checking for pkgx… x

📦 pkgx is not installed

User action required: Install pkgx
──────────────────────────────────
pkgx is our package manager for handling system dependencies. Learn more at https://pkgx.sh.

Here are quick ways to install it:
1. Via Homebrew:
   $ brew install pkgxdev/made/pkgx
2. Via cURL:
   $ curl -Ssf https://pkgx.sh | sh
Other installation methods at https://docs.pkgx.sh/run-anywhere/terminals.

ℹ️ pkgx installation is simple, and installing via Homebrew does not require sudo.

After pkgx has been installed please source this script again.
Enter fullscreen mode Exit fullscreen mode

So now the power is in the user's hands, and they can choose to install it according to their preferences. After installation, the user re-sources the script and continues.

 

Step 2: Activate Shell Integration

Next, we check if pkgx's shell integration is active:

Ok to proceed? [y/N]: y
• Checking for pkgx… ✓
• Checking pkgx shell integration… x

🔧 pkgx shell integration is not active

User action required: Activate pkgx shell integration
─────────────────────────────────────────────────────
To activate pkgx shell integration, run the following command:

  $ pkgx dev integrate

Integration writes one line to your .shellrc.

ℹ️ For more information about shell integration see: https://docs.pkgx.sh/using-pkgx/shell-integration.

After shell integration has been activated please source this script again.
Enter fullscreen mode Exit fullscreen mode

Shell integration unlocks pkgx's dev command — our tool for managing project-specific dependencies.

 

Step 3: Clone the Repository

Now we're ready to check for our repository:

Ok to proceed? [y/n]: y
• Checking for pkgx… ✓
• Checking pkgx shell integration… ✓
• Checking repository is cloned… x

🌿 Repository not found

User action required: Clone the repository
──────────────────────────────────────────
Please clone the repository using your preferred method:

1. Via GitHub CLI:
   $ pkgx gh repo clone gaggle/perfect-elixir
2. Via SSH:
   $ git clone git@github.com:gaggle/perfect-elixir.git
3. Via HTTPS:
   $ git clone https://github.com/gaggle/perfect-elixir.git

After cloning, navigate to the project directory and source this script again.
Enter fullscreen mode Exit fullscreen mode

ℹ️ BTW the first suggestion leverages pkgx's ability to run arbitrary tools, in this case the command would ephemerally run GitHub's CLI. Quite simple!

 

Step 4: Activate the Development Environment

Finally, we ensure the pkgx development environment is active:

Ok to proceed? [y/n]: y
• Checking for pkgx… ✓
• Checking pkgx shell integration… ✓
• Checking repository is cloned… ✓
• Checking development environment is active… x

🔧 Development environment is not active

User action required: Activate the development environment
──────────────────────────────────────────────────────────
To activate the development environment, run:

  $ dev

This will make project-specific versions of dependencies available within the repository.

After activating, please source this script again.
Enter fullscreen mode Exit fullscreen mode

 

Onboarding complete!

When all checks pass, the script confirms completion and guides the user to start using our development workflows:

Ok to proceed? [y/n]: y
• Checking for pkgx… ✓
• Checking pkgx shell integration… ✓
• Checking repository is cloned… ✓
• Checking development environment is active… ✓

✅ Onboarding complete!

- To start working on the project, run:

    $ bin/doctor
Enter fullscreen mode Exit fullscreen mode

🖥️ Terminal
Here is the full flow from a factory-reset machine to being ready to work on the project:

Animated gif showing "Running bootstrap script on a fresh machine, pasting in each of the suggested commands until onboarding is complete"
(dev.to fails to inline this .gif, so it's a hyperlink instead)

This clear, step-by-step approach ensures the developer can get fully set up in a few minutes.

ℹ️ BTW when extending onboarding to cover more steps, it's useful to note that past the first pkgx step the entire pkgx ecosystem is available. That means subsequent steps can easily leverage powerful tools such as GitHub CLI, or specific programming languages, and lots more. It's very powerful.

 

Conclusion

We set out to rethink onboarding, and landed on something radically simple: A single command that guides developers through a safe, low-friction setup. The entire onboarding instruction is:

Run, and follow the steps: $ curl -fsSL https://…/script > /tmp/script && source /tmp/script

It's minimal, extensible, and respectful of the developer’s environment. By avoiding invasive changes, the script stays safe and is easy to test — qualities that matter for teams who care about maintainability.

In our case setup is especially simple because the repository is public, but it works just as well to host the script behind a VPN, on a secure static server — the principles still hold.

ℹ️ BTW when implementing script-based onboarding, keep these security practices in mind:

  • Host on trusted infrastructure
  • Consider checksums for verification
  • Inspect scripts before running them

The real strength of this approach is its flexibility. Once pkgx is available, the script can evolve to include anything — repo access checks, CLI authentication, project prerequisites, even ticketing workflows.

This small investment pays off quickly. A smooth first experience sends a clear message: this is a team that values quality — from first command to first commit.

Top comments (0)