hx new

Create a new Haskell project.

Synopsis

hx new <NAME> [OPTIONS]

Description

The new command creates a new Haskell project with a complete directory structure, Cabal configuration, and hx configuration file.

Arguments

NAME                    Name of the project (must be a valid Cabal package name)

Options

Project Structure

    --lib               Create a library-only project
    --exe               Create an executable-only project
    --minimal           Create minimal project structure
    --no-tests          Skip test suite creation
    --no-git            Don't initialize git repository

Configuration

    --ghc <VERSION>     GHC version to use (e.g., "9.8.2")
    --backend <BACKEND> Compiler backend [ghc, bhc]
    --language <STD>    Haskell language standard [Haskell2010, GHC2021, GHC2024]

Metadata

    --author <NAME>     Author name
    --email <EMAIL>     Author email
    --license <LICENSE> License type (MIT, BSD3, Apache-2.0, etc.)

Examples

Create Default Project

hx new my-project

Creates:

my-project/
├── app/
│   └── Main.hs
├── src/
│   └── MyProject.hs
├── test/
│   └── Spec.hs
├── my-project.cabal
├── hx.toml
├── CHANGELOG.md
├── README.md
└── .gitignore

Library Only

hx new my-lib --lib

Creates a library without an executable:

my-lib/
├── src/
│   └── MyLib.hs
├── test/
│   └── Spec.hs
├── my-lib.cabal
├── hx.toml
└── README.md

Executable Only

hx new my-app --exe

Creates an executable without a library:

my-app/
├── app/
│   └── Main.hs
├── my-app.cabal
├── hx.toml
└── README.md

Minimal Project

hx new my-minimal --minimal

Creates the bare minimum:

my-minimal/
├── Main.hs
├── my-minimal.cabal
└── hx.toml

With Specific GHC Version

hx new my-project --ghc 9.8.2

With BHC Backend

hx new ml-project --backend bhc

Project Type Templates

hx provides specialized project templates for common use cases:

# Web application (Servant + Warp)
hx new webapp my-app

# CLI tool (optparse-applicative)
hx new cli my-tool

# Library
hx new library my-lib

# Numeric computing (BHC, hmatrix, vector, massiv)
hx new numeric my-science

# Web server (BHC, Servant, Warp, WAI)
hx new server my-api

The numeric and server templates automatically configure the BHC backend with optimized profiles. The webapp, cli, and library templates accept --backend bhc to use BHC instead of GHC.

With Author Information

hx new my-project \
  --author "Your Name" \
  --email "you@example.com" \
  --license MIT

Without Git

hx new my-project --no-git

Generated Files

hx.toml

[project]
name = "my-project"
version = "0.1.0"

[toolchain]
ghc = "9.8.2"

[build]
ghc-options = ["-Wall"]

.cabal file

cabal-version: 3.0
name:          my-project
version:       0.1.0
license:       MIT
author:        Your Name
maintainer:    you@example.com

common warnings
  ghc-options: -Wall

library
  import:           warnings
  exposed-modules:  MyProject
  hs-source-dirs:   src
  build-depends:    base ^>=4.18
  default-language: GHC2021

executable my-project
  import:           warnings
  main-is:          Main.hs
  hs-source-dirs:   app
  build-depends:
    , base ^>=4.18
    , my-project
  default-language: GHC2021

test-suite my-project-test
  import:           warnings
  type:             exitcode-stdio-1.0
  main-is:          Spec.hs
  hs-source-dirs:   test
  build-depends:
    , base ^>=4.18
    , my-project
    , hspec
  default-language: GHC2021

Main.hs

module Main where

import MyProject (someFunc)

main :: IO ()
main = someFunc

Library Module

module MyProject (someFunc) where

someFunc :: IO ()
someFunc = putStrLn "Hello from my-project!"

Package Naming

Package names must:

Start with a letter
Contain only letters, digits, and hyphens
Not end with a hyphen

Valid: my-project, parser2, json-utils Invalid: 2parser, my--project, project-

Post-Creation

After creating a project:

cd my-project

# Build
hx build

# Run
hx run

# Test
hx test

Template Details

numeric

Creates a BHC-optimized numeric computing project:

my-science/
├── app/
│   └── Main.hs            # Matrix/vector computation example
├── src/
│   └── Compute.hs         # Numeric operations module
├── test/
│   └── Main.hs            # Property tests with QuickCheck
├── my-science.cabal        # hmatrix, vector, statistics, massiv
├── hx.toml                 # backend = "bhc", profile = "numeric"
└── README.md

server

Creates a BHC-optimized web server project:

my-api/
├── app/
│   └── Main.hs            # Server entry point
├── src/
│   ├── Api.hs             # Servant API definition
│   ├── Server.hs          # Request handlers
│   ├── Config.hs          # Environment-based config
│   └── Types.hs           # Domain types
├── test/
│   └── Main.hs            # hspec-wai API tests
├── my-api.cabal            # servant, warp, wai, aeson
├── hx.toml                 # backend = "bhc", profile = "server"
└── README.md