How to use the command 'yesod' (with examples)

Yesod is a powerful web framework for developing complex and scalable web applications in Haskell. Its command-line tool allows developers to easily scaffold, build, and deploy their projects using various utilities provided by Yesod, working through the stack project manager. Whether you’re setting up a new project or maintaining an existing one, the Yesod command-line tool streamlines several critical development tasks.

Use case 1: Create a new scaffolded site, with SQLite as backend, in the my-project directory

Code:

stack new my-project yesod-sqlite

Motivation: Starting a new web application project from scratch can be daunting, especially when considering the architecture and setup of databases. Using this command, developers can quickly create a scaffolded Yesod project with built-in support for SQLite, allowing them to hit the ground running with a pre-configured database setup.

Explanation:

• stack new: This command initializes a new project in a specified directory.
• my-project: This is the name of the directory where the new project will be created. It also becomes the name of the project.
• yesod-sqlite: This specifies the template to use for scaffolding the new Yesod project, with sqlite being the database backend.

Example Output:

Downloading template "yesod-sqlite" to create project "my-project"...
Project "my-project" was successfully initialized using the 'yesod-sqlite' template.

Use case 2: Install the Yesod CLI tool within a Yesod scaffolded site

Code:

stack build yesod-bin cabal-install --install-ghc

Motivation: The Yesod CLI tool is essential for running various development commands within a Yesod project, such as starting the server or building the project. Installing it ensures that developers have access to these crucial commands for efficient project management.

Explanation:

• stack build: This command tells stack to build the specified packages or tools.
• yesod-bin: This package includes the Yesod command-line tool, which is necessary for executing Yesod-specific commands.
• cabal-install: This is a dependency management tool for Haskell, required in the Yesod environment.
• --install-ghc: This flag instructs stack to install the Glasgow Haskell Compiler if it is not already installed or available, ensuring that all subsequent commands have the required compilation support.

Example Output:

Building all executables for 'my-project' once. After a successful build of all of them,...
Installing executable(s) in /my-project/.stack-work/install/x86_64-osx/lts-14.27/8.6.5/bin

Use case 3: Start development server

Code:

stack exec -- yesod devel

Motivation: During the development phase of an application, developers need to test their updates in real time. This command starts a local development server, allowing developers to see changes reflected immediately as they code, thus improving the iterative testing process.

Explanation:

• stack exec: This command executes a specified program in an isolated environment based on the stack configuration of the project.
• --: This delimiter separates the stack exec command from the arguments that follow, indicating that what follows should be interpreted as part of the command to execute.
• yesod devel: This command starts the Yesod development server, which automatically reloads the server whenever changes are detected in the code.

Example Output:

Yesod development server running on http://localhost:3000

Use case 4: Touch files with altered Template Haskell dependencies

Code:

stack exec -- yesod touch

Motivation: In Haskell, Template Haskell is used for metaprogramming, which can introduce dependencies that are not always tracked automatically. This command helps to ensure that all dependent files are recompiled when changes occur, thereby preventing possible runtime issues caused by stale compiled code.

Explanation:

• stack exec: As previously described, this is used to run the Yesod command in the project environment.
• yesod touch: This triggers the recompilation of files by updating timestamps, ensuring all Template Haskell dependencies are up-to-date.

Example Output:

Files updated: ..., restarting server...

Use case 5: Deploy application using Keter (Yesod’s deployment manager)

Code:

stack exec -- yesod keter

Motivation: Deployment can be a complex task involving various server configurations and dependencies. By using the Keter deployment manager, Yesod projects can be deployed efficiently and reliably, encapsulating application configurations and logs, facilitating continuous delivery.

Explanation:

• stack exec: Executes the subsequent command (yesod keter) within the project’s stack configuration.
• yesod keter: This command packages the Yesod application into a Keter bundle, which can then be deployed on a server running the Keter manager, handling processes like reverse proxies, SSL, etc.

Example Output:

Creating a Keter bundle: my-project.keter
Bundle created successfully. Upload this to your Keter server for deployment.

Conclusion:

The Yesod command-line tool, in conjunction with stack, offers a comprehensive suite of utilities to scaffold, develop, and deploy web applications. By efficiently setting up a new project, managing the development environment, and facilitating deployment, Yesod ensures robust and effective web application development using Haskell.