Now that Holochain has reached its beta and is stable enough for developing serious hApps, it’s time to introduce the tools you’ll be using. This first article goes into Holonix, the dev environment that distributes those tools.

[Editor’s note: this guide is meant for Holochain 0.1. When a new version with breaking changes is released, we’ll update this guide shortly afterwards.]

What is Holonix?

Holonix is our name for an environment that includes pretty much all the tools you need to write, test, and deploy a Holochain application. It’s not an IDE or text editor; it’s simply an ‘overlay’ on your existing Linux or UNIX shell (and that includes WSL2 for Windows) that makes the right versions of all the necessary command-line tools available and ready to use.

You’ve probably used this sort of thing before. It’s often called a ‘reproducible development environment’, and tools like Vagrant, Docker, Virtualbox, and Python’s virtualenv are commonly used to set these up and distribute them among developers who want to share a predictable toolset.

Holonix is built with Nix, a package manager that can be installed in your existing OS. Instead of directly changing the state of your system, though, it can create an ‘overlay’ that you can enter and leave as needed. Anything you’ve already got installed, it will ‘shadow’ with its own version. This approach is much lighter than a VM and even somewhat lighter than a Docker container. But just like those other tools, outside of that environment, your familiar shell environment is preserved — just the way you like it.

You can even have a separate Nix environment for each hApp project you create, by putting a file called flake.nix in there with all the dependencies you need. It lets you target and work with different Holochain versions per project. You can think of this file as a package.json or Cargo.toml file — but for your entire shell and all its commands. You can check this file, along with the flake.lock file, into your Git repo to make sure you and other developers always have the right version of the Holochain dev tools when you’re working on the project.

One nice thing about Nix is that it lets your host environment ‘leak’ through into the new dev environment. Nix merely adds the things specified in your .nix file. So if your PATH environment variable points to the locations of all sorts of weird dev tools that you can’t live without, you’ve still got that inside Holonix.

So what does Holonix contain?

  • The holochain conductor runtime itself
  • A dev tool called hc (I’ll talk about that in another article)
  • hc scaffold command to scaffold a new example or empty hApp
  • hc launch command to run the hApp in a Launcher window
  • lair-keystore command to run Holochain’s secret keystore
  • A specific version of Rust and Cargo
  • Specific versions of a few necessary libraries, like OpenSSL

What doesn’t it contain?

  • An editor or IDE — that means you can use your favourite one.
  • Node.js and NPM, which is used by the scaffolding tool and Tryorama test framework, so make sure you have a recent version installed. You can also configure Holonix to include Node.js and other tools for you; see below.

And I want to stress once again that, if you already have Rust, Cargo, or even Holochain installed somewhere in your system, it doesn’t clobber those — it only points to its own versions when you’re in the Holonix shell.

How do I install Holonix?

First you need to install Nix on your system; it’s available for all three major workstation OSes. Then you load and apply the Holonix setup (called a ‘flake’). From zero to Holonix is not exactly a one-liner, but it is a three-liner and that ain’t so bad. (And we are working on a one-liner.) Go to the quick-start guide and it’ll get you set up in a few minutes!

Now, once you’ve finished the quick-start install, you have a fully working environment. But every time you leave it and enter it again, it checks our GitHub repo for the newest version, so your project code might get out of sync with the dev tools you get.

So you’ll likely want to create project-specific Nix setups that ‘pin’ the dev tools to a specific Holochain version. That’s easy; all you need to do is create a nix file in your project’s root directory — and in fact the scaffolding tool will do that for you. (That’ll be in my next article.)

There’s a page of advanced setup tips if you want to do something special, including keeping your preferred shell (I like fish, and I know others are fond of Zsh) and connecting your IDE to the Rust analyzer that comes with Holonix.

If you want to customise your project’s environment and share it with other developers, this guide also gives you an example of how to do this with Node.JS. Nix hosts a lot of other packages that you can include too.

What if I don’t want to use Holonix?

That’s fine; the packages are all available from crates.io and npmjs.com. Setting that up is outside the scope of this article, but you can read more about it on the Developer Portal.

Next steps

Now that you’ve got Holonix running and have a decent idea of what it’s for, it’s time to build something. You can follow along in the next article, in which I walk through the scaffolding of an app I’ve always wanted to build.

If you need some installation help, go to the Dev.HC Discord and ask an admin to give you the ‘Developer’ badge. The door is always open and the welcome mat is broad, comfy, and well-trod-upon by beginners and experienced devs alike. We’ll see you there!

Install Holochain Learn about Holochain Join the Discussion