# z - Advanced topic: A complete end-to-end walkthrough to set up a project

## Introduction

This vignette walks you through setting up an entire project using Nix and `{rix}`. We assume you already installed Nix on your system and configured the `rstats-on-nix` cache. If not, go back to the vignette `vignette("a-getting-started")`.

First, we strongly recommend uninstalling any locally installed R versions and using Nix exclusively to manage your R environments. This prevents conflicts between a system-installed R and a Nix-managed environment. While `{rix}` does its best to avoid compatibility issues, it can’t cover every edge case. Beyond avoiding conflicts, defining your environment upfront ensures reproducibility from the start, saving you from potential headaches later.

On Windows, this applies to R installations inside WSL. A system-installed R on Windows won’t interfere with a Nix-managed R inside WSL, so you can keep it if needed.

After uninstalling R, remove your local package libraries:

- Linux and WSL: `~/R/x86_64-pc-linux-gnu-library/<R_version>/`

- macOS: `~/Library/R/<R_version>/library/`

And don’t worry, just because R is no longer installed doesn’t mean you’re locked out of using `{rix}`! Just follow along and trust the process.

## Setting up Git

This isn’t directly related to Nix or `{rix}`, but we strongly recommend using version control for your projects. Whether it’s a private GitHub repository or a self-hosted Git instance like GitLab or Gitea at your job, you should absolutely be using Git—no exceptions.

If you’re new to Git, check out this guide. If you’re already using it, great! Keep going.

## Setting up your environment

Start by writing a script called something like `gen_env.R` and that looks like this:

    library(rix)

    # Choose the path to your project
    path_default_nix <- "."

    rix(
      date = "2025-02-28", # We recommend using a date
      r_pkgs = c("dplyr", "ggplot2"), # List all the packages you need
      ide = "rstudio", # List whatever editor you need
      project_path = path_default_nix,
      overwrite = TRUE,
      print = FALSE
    )

Just copy and paste the lines above and adapt them. You can use any editor for this, we are not going to execute these lines just yet. Now, remember what I told you above, something about trusting the process? We are now going to bootstrap this environment. First, run the following line to drop into a temporary shell with R and `{rix}`:

    nix-shell --expr "$(curl -sl https://raw.githubusercontent.com/ropensci/rix/main/inst/extdata/default.nix)"

Once the build process is done, you can simply start R by typing `R` and then, within the R session, run `source("gen_env.R")`. This will execute the lines above and generate a `default.nix` file. This is your environment’s definition! Now quite R and the Nix shell (CTRL-D on your terminal, or type `quit()` to quite R and `exit` then to quite the Nix shell), or open a new terminal, and type `nix-build`. This will start building your environment.

## Using your environment

Once the build process is done, you can start using your environment. By typing `nix-shell` you will get dropped in that environment. From there, start your IDE by typing the appropriate command (`rstudio` for RStudio, an so on… refer to the vignette `vignette("e-configuring-ide")` for more details). If you need to add packages to the environment, we recommend adding them to the `gen_env.R` script, and regenerate your environment. You may even add `{rix}` itself to your environment so you don’t need to use the temporary shell as explained above.

## Using GitHub Actions

### For a project using {targets}

If you use `{targets}` for your projects (you should, `{targets}` is amazing!) you can run the pipeline on GitHub actions using the same Nix environment. Simply call `rix::tar_nix_ga()` and this will automatically create the appropriate folders and files in your project’s root directory. Now, every time you push, the analysis is built on GitHub actions and the results are automatically cached and pushed to the `targets-runs` branch! This feature is heavily inspired by the original `targets::tar_github_actions()` function.

### For a project that doesn’t use {targets}

First, consider whether you shouldn’t learn `{targets}`. It is well worth your time, believe us. But not all projects lend themselves to being set up as a `{targets}` pipeline, but all projects can benefit from continuous integration. Here are some examples that you can use as inspiration:

- A paper compiled using Quarto and Nix on GitHub Actions
- A blog built on GitHub Actions with Nix and hosted on GitHub pages
- A research paper compiled on GitHub Actions using Nix/rix
- Check out all the actions we use for rix itself

You can also check out this video to explain the why of using continuous integration.

But of course you don’t have to use GitHub Actions, see for example this project.

## How to update or reproduce your project

To update your project’s environment, simply use a more recent date, rebuild using `nix-build` and run your project. This can be useful in certain cases if you want to ensure that your project works with the latest packages, for example, if you’re developing a package yourself. This is how we do it with `{rix}`; the project ships a `default.nix` that contributors must use to work on `{rix}` and we update the date every now and then to make sure that `{rix}` keeps working with the latest CRAN packages. If anything breaks, just put back the original date and continue working. Also open an issue, we might be able to help you.

Once you’re done with the analysis, someone wanting to reproduce the results can simply reuse the project’s `default.nix` to restore the exact development environment you used.