Get a Haskell development environment up and running quickly, as long as Nix is available on your system1.
This repository is a Haskell project template that is optimized for a fully reproducible and friendly development environment. It is based on:
- Nix + Flakes (via
github:srid/haskell-flake
) + GHC 9 - VSCode + HLS
- fourmolu autoformatting
- Relude as Prelude.
.hlint.yaml
is from relude
First-time setup:
- Install Nix (>= 2.8) & enable Flakes (Using Windows? See footnote1)
- Run
nix develop -i -c haskell-language-server
to sanity check your environment - Open as single-folder workspace in Visual Studio Code
- When prompted by VSCode, install the workspace recommended extensions
- Ctrl+Shift+P to run command "Nix-Env: Select Environment" and then select
shell.nix
.- The extension will ask you to reload VSCode at the end. Do it.
To run the program with auto-recompile:
- Press Ctrl+Shift+B in VSCode, or run
bin/run
in terminal, to launch Ghcid running your program.
Open Main.hs
, and expect all HLS IDE features like hover-over tooltip to work out of the box. Try changing the source, and expect Ghcid to re-compile and re-run the app in the terminal below.
Renaming the project:
# First, click the green "Use this template" button on GitHub to create your copy.
git clone <your-clone-url>
cd your-project
NAME=myproject
git mv haskell-template.cabal ${NAME}.cabal
nix run nixpkgs#sd -- haskell-template ${NAME} * */*
git add . && git commit -m rename
- Run
nix flake update
to update all flake inputs. - Run
nix --option sandbox false build .#check -L
to run the flake checks. - Run
treefmt
in nix shell to autoformat the project. This uses treefmt, which uses./treefmt.toml
(where fourmolu and nixpkgs-fmt are specified). - Run
bin/hoogle
to start Hoogle with packages in your cabal file. - Run
bin/test
to run the test suite. - Run the application without installing:
nix run github:srid/haskell-template
(ornix run .
from checkout)
- Split any logic code out of
Main.hs
into, say, aLib.hs
. - Correspondingly, add
other-modules: Lib
to the "shared" section of your cabal file. - Add
tests/Spec.hs
(example below):module Main where import Lib qualified import Test.Hspec (describe, hspec, it, shouldContain) main :: IO () main = hspec $ do describe "Lib.hello" $ do it "contains the world emoji" $ do toString Lib.hello `shouldContain` "๐"
- Add the tests stanza to the cabal file:
test-suite tests import: shared main-is: Spec.hs type: exitcode-stdio-1.0 hs-source-dirs: tests build-depends: hspec
- Update
hie.yaml
accordingly; for example, by adding,- path: "tests" component: "test:tests"
- Add
bin/test
andchmod a+x
it:#!/usr/bin/env bash set -xe exec nix develop -i -c ghcid -c "cabal repl test:tests" -T :main
- Commit your changes to Git, and test it out by running
bin/test
.
Got questions? Ideas? Suggestions? Post them here: https://github.com/srid/haskell-template/discussions
Footnotes
-
On Windows, you may install Nix under WSL2 and use the Remote - WSL extension to connect from the native VSCode. This runs your project under Linux while providing a near-native development experience on Windows. โฉ โฉ2