Justfile In Cookiecutter-FastAPI Projects

Creating a justfile within a project generated by Tobi-De/cookiecutter-fastapi can significantly streamline your development workflow. Inspired by projects like github/scripts-to-rule-them-all, a justfile allows you to define and execute common development tasks with simple commands. This article will guide you through the process of setting up a justfile in your cookiecutter-fastapi project, enhancing productivity and maintainability.

Understanding Justfile

Before diving into the specifics, let's understand what justfile is and why it is beneficial. just is a command runner that saves commands as recipes. Instead of memorizing long commands or relying on complex shell scripts, you define these commands in a justfile and execute them with a simple just command. This approach offers several advantages:

• Improved Readability: Commands are named and organized, making it easier to understand what each command does.
• Reduced Typing: Short, memorable command names replace long, complex commands.
• Consistency: Ensures that commands are executed the same way every time, reducing the risk of errors.
• Portability: The justfile can be easily shared and used across different environments.

In the context of a cookiecutter-fastapi project, a justfile can manage tasks such as running the development server, executing tests, building Docker images, and more. By automating these tasks, you can focus on writing code rather than managing infrastructure.

Setting Up Just in Your Project

To get started, you need to install just. You can install it via various package managers, or directly download the binary from the just installation page. After the installation, verify that just is correctly installed by running just --version in your terminal. This should output the version number of just.

Next, create a file named justfile in the root directory of your cookiecutter-fastapi project. This file will contain the definitions for your commands. The justfile syntax is straightforward. Each command definition starts with the command name, followed by a colon, and then the command to be executed. For example:

run: 
    uvicorn app.main:app --reload

This command defines a rule named run that executes uvicorn app.main:app --reload. Now, you can run the development server by simply typing just run in your terminal.

Essential Commands for FastAPI Projects

Let's explore some essential commands that you can include in your justfile for a cookiecutter-fastapi project.

Running the Development Server

The most basic command is for running the development server. This allows you to quickly start your application and test changes. The command typically involves using uvicorn, an ASGI server, to serve your FastAPI application. Here’s how you can define it in your justfile:

run:
 uvicorn app.main:app --reload

This command tells uvicorn to serve the app instance from the app/main.py file, with the --reload flag enabled for automatic reloading upon code changes. To use it, simply run just run in your terminal.

Running Tests

Automated testing is crucial for maintaining code quality and ensuring that your application behaves as expected. You can define a command to run your tests using pytest or any other testing framework you prefer. Here’s an example using pytest:

test:
 pytest

Before running the tests, ensure that you have installed the necessary testing libraries, such as pytest and pytest-cov. You can install them using pip:

pip install pytest pytest-cov

With this setup, running just test will execute your test suite.

Formatting Code

Maintaining consistent code style is essential for collaboration and readability. You can use tools like black and isort to automatically format your code. Define commands for these tools in your justfile:

format:
 black .
 isort .

These commands will format your code according to the black and isort configurations. To use them, run just format in your terminal. Make sure you have black and isort installed:

pip install black isort

Linting Code

Linting helps identify potential issues and enforce coding standards. You can use tools like flake8 to lint your code. Add a command for flake8 to your justfile:

lint:
 flake8 .

Running just lint will execute the linter and report any issues in your code. Ensure that flake8 is installed:

pip install flake8

Building Docker Images

If you are using Docker to containerize your application, you can define a command to build the Docker image. This command typically involves using the docker build command with the appropriate flags and arguments. Here’s an example:

build-image:
 docker build -t my-fastapi-app .

This command builds a Docker image with the tag my-fastapi-app using the Dockerfile in the current directory. To use it, run just build-image in your terminal. Before running this command, make sure you have Docker installed and running on your system.

Running Docker Compose

For more complex applications that involve multiple services, you can use Docker Compose to manage them. Define a command to start your application using Docker Compose:

up:
 docker-compose up -d

This command starts the services defined in your docker-compose.yml file in detached mode. To use it, run just up in your terminal. Ensure that you have Docker Compose installed and configured correctly.

Cleaning Up

Remove the __pycache__ directories and .pyc files.

clean:
 find . -type d -name "__pycache__" -print0 | xargs -0 rm -rf
 find . -type f -name "*.pyc" -print0 | xargs -0 rm -f

Updating Dependencies

To update the project’s dependencies, you can use pip to upgrade the packages listed in your requirements.txt file.

update-deps:
 pip install --upgrade -r requirements.txt

This command updates all the dependencies to their latest versions. It’s a good practice to run this command periodically to keep your project up-to-date.

Advanced Tips and Tricks

Using Variables

You can use variables in your justfile to make it more flexible and reusable. Variables are defined using the := operator. For example:

PROJECT_NAME := my-fastapi-app

build-image:
 docker build -t $(PROJECT_NAME) .

In this example, the PROJECT_NAME variable is used in the build-image command. You can change the value of the variable to build images with different tags.

Passing Arguments

You can pass arguments to your commands using the {} syntax. This allows you to customize the behavior of your commands at runtime. For example:

run-with-port PORT:
 uvicorn app.main:app --reload --port {PORT}

In this example, the run-with-port command takes a PORT argument, which is used to specify the port number for the development server. To use it, run just run-with-port 8000 in your terminal.

Combining Commands

You can combine multiple commands into a single command using the && operator. This allows you to execute a sequence of commands with a single command. For example:

full-setup:
 just format && just lint && just test

This command executes the format, lint, and test commands in sequence. To use it, run just full-setup in your terminal.

Example justfile

Here’s a complete example of a justfile for a cookiecutter-fastapi project:

PROJECT_NAME := my-fastapi-app

run:
 uvicorn app.main:app --reload

test:
 pytest

format:
 black .
 isort .

lint:
 flake8 .

build-image:
 docker build -t $(PROJECT_NAME) .

up:
 docker-compose up -d

clean:
 find . -type d -name "__pycache__" -print0 | xargs -0 rm -rf
 find . -type f -name "*.pyc" -print0 | xargs -0 rm -f

update-deps:
 pip install --upgrade -r requirements.txt

full-setup:
 just format && just lint && just test

run-with-port PORT:
 uvicorn app.main:app --reload --port {PORT}

Conclusion

Using a justfile in your cookiecutter-fastapi project can significantly improve your development workflow by automating common tasks and ensuring consistency. By defining commands for running the development server, executing tests, formatting code, linting code, building Docker images, and more, you can focus on writing code and building great applications. This guide provides a solid foundation for creating your justfile, and you can customize it further to suit your specific needs and preferences. Embrace the power of just and take your FastAPI development to the next level.

For more information on just and its features, visit the official just documentation.