Tutorial

To install Garn, head over to our getting started guide.

Your first garn.ts config

All examples in this tutorial are also available here.

Garn projects are configured with a single garn.ts file. (This file is read by Garn rather than run directly via node or deno.) Your garn.ts exports a collection of Projects. A Project contains all the information needed to build, run, and develop your software.

The Garn library exports a lot of helpers that make it easy to quickly construct projects for common stacks, but you can also define these yourself.

Here is an example garn.ts file for a single node-based project:

import * as garn from "https://garn.io/ts/v0.0.20/mod.ts";
import * as pkgs from "https://garn.io/ts/v0.0.20/nixpkgs.ts";

export const frontend = garn.javascript.mkNpmProject({
  description: "my frontend",
  nodeVersion: "18",
  src: "./frontend",
});

In the same directory you can now run garn enter frontend to enter a shell with node version 18 available.

> garn enter frontend
[garn] Entering frontend shell. Type 'exit' to exit.
[...]
> node --version
v18.17.1

Hint: You may have noticed that running garn enter frontend generated two files, flake.nix and flake.lock. These should be committed to your repository rather than gitignored. They both ensure reproducibility, and allow Nix to be used directly rather than only via Garn.

Projects can contain Checks, which can be used to run automated tests for your project. You can add them with addCheck.

export const frontend = garn.javascript
  .mkNpmProject({
    description: "my frontend",
    nodeVersion: "18",
    src: "./frontend",
  })
  .addCheck("test", "npm test");

Now running garn check frontend will run npm test in the frontend project environment. These Checks are pure, i.e. they are run in a build sandbox. The downside of sandboxing is that these checks won't have access to the internet. The upside is that they'll be (almost) perfectly reproducible, cacheable, and runnable on CI (like Garnix, see the docs for more info).

Multi-language support

You can configure multiple sub-projects with different tech stacks in a single garn.ts file. Let's try to add a Go backend:

export const backend = garn.go.mkGoProject({
  description: "my backend",
  src: "./backend",
  goVersion: "1.21",
});

This means that you can use Garn to configure bigger multi-language projects. This enables anyone to run, test, and develop any part of your codebase, without having to install any language-specific tools or learn how to use them.

Garn currently supports Go, Npm and Haskell. If you'd like to see support for other languages or toolchains please let us know.