yesod-bin

The yesod helper executable.

http://www.yesodweb.com/

LTS Haskell 24.17:1.6.2.3@rev:1
Stackage Nightly 2025-07-14:1.6.2.3@rev:1
Latest on Hackage:1.6.2.3@rev:1

See all snapshots yesod-bin appears in

MIT licensed and maintained by Michael Snoyman
This version can be pinned in stack with:yesod-bin-1.6.2.3@sha256:cd4001c41b6f6d9d2dbdf7a2628f77c5fbd387f73047bb1f6e28983b63a7bc06,2862

Module documentation for 1.6.2.3

There are no documented modules for this package.

yesod-bin: the Yesod executable

This executable is almost exclusively used for its yesod devel capabilities, providing a development server for web apps. It also provides some legacy functionality, almost all of which has been superceded by functionality in the Haskell Stack build tool. This README will speak exclusively about yesod devel.

CAVEAT There may be some issues using yesod devel in Docker-enabled projects. See comment on Github.

Development server

The development server will automatically recompile your application whenever you make source code changes. It will then launch your app, and reverse-proxy to it. The reverse proxying ensures that you can connect to your application on a dedicated port, always get the latest version available, and won’t get dropped connections when the app isn’t yet ready. Instead, you’ll get some very motivating messages:

Motivation

Common workflows

The standard Yesod scaffoldings are configured to work with yesod devel out of the box (though see below for non-Yesod development). For the most part, from within your application directory, you’ll just want to run:

  • stack build yesod-bin
  • stack exec -- yesod devel

This will install the corresponding version of the yesod executable into your currently selected snapshot, and then use that executable. (Starting with version 1.5.0, you can be more lax and use a yesod executable compiled for a different snapshot. Once 1.5.0 is more widespread we’ll probably update these instructions.)

Some other common questions:

  • If you want to control which port you can access your application on, use the --port command line option, e.g. stack exec -- yesod devel --port 4000. Changing your port inside your source code will not work, because you need to change the reverse proxying port.
  • If you want to run a command after each successful build, you can use stack exec -- yesod devel --success-hook "echo Yay!"
  • If for some reason you want to disable the reverse proxy capabilities, use stack exec -- yesod devel --disable-reverse-proxy

How it works

The workflow of the devel server is pretty simple:

  • Launch a reverse proxy server
  • Use Stack file-watch capability to run a build loop on your code, rebuilding each time a file is modified
  • Have Stack call yesod devel-signal to write to a specific file (yesod-devel/rebuild) each time a rebuild is successful
  • Each time yesod-devel/rebuild is modified:
    • Kill the current child process
    • Get a new random port
    • Tell the reverse proxy server about the new port to forward to
    • Run the application’s devel script with two environment variables set:
      • PORT gives the newly generated random port. The application needs to listen on that port.
      • DISPLAY_PORT gives the port that the reverse proxy is listening on, used for display purposes or generating URLs.

Now some weird notes:

  • The devel script can be one of the following three files. yesod devel will search for them in the given order. That script must provide a main function.
    • app/devel.hs
    • devel.hs
    • src/devel.hs
  • Unfortunately, directly killing the ghc interpreter has never worked reliably, so we have an extra hack: when killing the process, yesod devel also writes to a file yesod-devel/devel-terminate. Your devel script should respect this file and shutdown whenever it exists. (It may be fixed in 1.6.0.5.)
  • If your .cabal file defines them, yesod devel will tell Stack to build with the flags dev and library-only. You can use this to speed up compile times (biggest win: skip building executables, thus the name library-only).

If that all seems a little complicated, remember that the Yesod scaffolding handles all of this for you. But if you want to implement it yourself…

Non-Yesod development

If you’d like to use the yesod devel server for your non-Yesod application, or even for a Yesod application not based on the scaffolding, this section is for you! We’ve got a sample application in the repository that demonstrates how to get this set up. It demonstrates a good way to jump through the hoops implied above.

One important note: I highly recommend putting all of the logic in your library, and then providing a develMain :: IO () function which your app/devel.hs script reexports as main. I’ve found this to greatly simplify things overall, since you can ensure all of your dependencies are specified correctly in your .cabal file. Also, I recommend using PackageImports in that file, as the example app shows.

Changes

ChangeLog for yesod-bin

1.6.2.3

  • Support optparse-applicative-0.18 #1829

1.6.2.2

  • Support Cabal 3.8 #1769

1.6.2.1

  • Support Cabal 3.6 #1754

1.6.2

  • aeson 2.0

1.6.1

Added command line options cert and key to allow TLS certificate and key files to be passed to yesod devel #1717

1.6.0.6

Fix the add-handler subcommand to support both the old default routes filename (routes) and the new one (routes.yesodroutes) #1688

1.6.0.5

  • Use process groups to ensure GHC is killed on Ctrl-C #1683

1.6.0.4

  • Support Cabal 3.0

1.6.0.3

  • Support Cabal 2.2 #1151

1.6.0.2

  • Fix broken support for older http-reverse-proxy

1.6.0.1

  • Support for http-reverse-proxy 0.6

1.6.0

  • Upgrade to conduit 1.3.0
  • Remove configure, build, touch, and test commands

1.5.3

  • Support typed-process-0.2.0.0

1.5.2.6

  • Drop an upper bound

1.5.2.5

  • Support for add-handler when modules are in src/ directory #1413

1.5.2.4

  • Cabal 2.0 support

1.5.2.3

  • Fix race condition which leads dev server to stay in compilation mode. #1380

1.5.2.2

  • I guess --no-nix-pure implies Nix… sigh #1359

1.5.2.1

  • Use --no-nix-pure #1357

1.5.2

  • Fix warnings

1.5.1

  • Add --host option to yesod devel

1.5.0.1

  • Fix build failure

1.5.0

Rewrite of yesod devel to take advantage of Stack for a simpler codebase.

Advantages:

  • Does not link against the ghc library, so can be used with multiple GHC versions
  • Leverages Stack’s ability to check for dependent files, which is more robust than what yesod devel was doing previously
  • Seems to involve less rebuilding of the library on initial run

Disadvantages:

  • Lost some functionality (e.g., failure hooks, controlling the exit command)
  • Newer codebase, quite likely has bugs that need to be ironed out.

1.4.18.7

  • Actually release the changes for #1284

1.4.18.6

  • Fix support for GHC 8.0.1 #1284

1.4.18.5

  • yesod-bin: Make it build with latest optparse-applicative #1282

1.4.18.4

  • Link yesod-bin with wxneeded on OpenBSD. #1281

1.4.18.3

  • Adding a new handler adds it under wrong stanza #1273

1.4.18.2

1.4.18.1

  • error handling when checking for stack binary #1219
  • GHC 8 support

1.4.18

  • Disable yesod test when using Stack #1198

1.4.17

  • Fully remove the yesod init command

1.4.16.1

1.4.16

1.4.15

  • Deprecate yesod init

1.4.14

  • Fix order of -package-db arguments to runghc #1057

1.4.13

  • Enable stack with yesod keter #1041

1.4.12

  • Devel server: have to type quit to quit

1.4.11

  • Add support to yesod devel to detect and use GHC_PACKAGE_PATH. This makes yesod devel compatible with stack, just run: stack exec -- yesod devel.

1.4.10

  • Scaffolding update

1.4.9.2

1.4.9

  • Command line options for yesod init #986

1.4.8

  • Drop system-filepath

1.4.7.2

  • Scaffolding updates, including fix for #982

1.4.7

  • GHC 7.10 support

1.4.6

  • Add TLS support to yesod devel #964

1.4.5

  • add a switch to yesod to skip deploying a .keter with copy-to #952

1.4.4

  • Add and process Keter option ‘extraFiles’ #947

1.4.3.11

  • Disregard proxy environment variables in yesod devel #945

1.4.3.10

  • Allow blaze-builder 0.4

1.4.3.9

1.4.3.8

  • Scaffold update: fix 404 for missing sourcemap

1.4.3.6

  • Scaffold update: use addToken instead of addNonce

1.4.3.5

  • Fix add-handler putting two routes on one line #922

1.4.3.4

Scaffolding updates:

  • Improve DevelMain support
  • Wipe out database during test runs
  • Convenience unsafeHandler function
  • Remove deprecated Chrome Frame code

1.4.3.3

More consistent whitespace in hamlet files in scaffolding #50

1.4.3.2

add-handler adds arguments too #898

1.4.3

Add the minimal scaffolding

1.4.2

Scaffolding updates:

  • Import.NoFoundation
  • Explanation of static files in Settings.StaticFiles
  • Explanation of environment variables in settings.yml

1.4.1.2

No args passed in keter.yml

1.4.1

Significant update to the scaffolding.

1.4.0.9

Allow devel.hs to be located in app/ or src/ subdirectories.

1.4.0.8

Updated postgres-fay scaffolding for yesod-fay 0.7.0

1.4.0.7

Fix a bug in yesod devel when cabal config has tests: True #864