An overview of Cookiecutter

A “cookie-cutter” house is usually mass-produced and indistinguishable from the rest, probably an undesirable quality when buying your dream home. For a codebase, however, the situation is the total opposite. Cookie-cutter code is the dream.

When individuals, teams, and entire organizations create many projects, it is imperative that projects follow consistent standards to be easily readable and searchable. Templates accelerate writing code, too, since developers spend less time with setup and can get straight to the actual implementation. Cookiecutter (cookiecutter.io) is an open-source, cross-platform tool for this very purpose that is compatible with almost any programming or markup language.

What is Cookiecutter?

Cookiecutter is a Python package, easily installable with pip or other package managers, that enables you to create and use templates for microservices and software projects. It is a command-line tool that requires no knowledge of Python to use. Cookiecutter is widely used among software engineers, researchers, data scientists, and other technical roles.

At its simplest, creating a template requires updating a cookiecutter.json file, while using a template requires running the cookiecutter command with the appropriate directory to create a new project.

Here’s an example template for a Python package that the Cookiecutter team maintains. To use the template, install Cookiecutter first and then run the following command in your terminal:

cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage.git 

Go through the series of prompts and voila! In just a few moments you have the skeleton of a completely functional Python package. Swap out the template for something else and you could just as easily spin up a mobile app, a data science notebook, or a project on your favorite cloud service. There’s an entire community with thousands of templates to choose from.

Creating custom templates to fit your and your organization’s needs is also incredibly powerful. We’ll cover how to do that down below.

Who is Cookiecutter for?

Cookiecutter is for individuals, teams, and companies wanting to standardize their project development process and accelerate new project creation.

Example use cases include:

• Learning a new framework: Cookiecutter lowers the barrier to entry for developers unfamiliar with a particular framework. You can find an expert’s template for a framework you’re learning and quickly get started with a configuration that is known to work.
• Onboarding: Standardization makes collaboration much easier. New team members can immediately follow best practices without the risks of copying, pasting, and trying to edit just the right variables.
• Enforcing standards in an organization: Consistent foldering, file naming conventions, and other patterns enable large teams to maintain an organized codebase.

Features of Cookiecutter

Templates

The heart of a template is the cookiecutter.json file, which might look something like this:‍

{
    "full_name": "Alice Cookie",
    "email": "foobar@example.com",
    "project_name": "Django Boilerplate",
    "version": "0.1.0"
}

‍These key-value pairs determine the prompts a developer needs to answer when using a template. The command-line interface iterates over the keys, prompting a developer to set the various parameters. If a developer does not specify something, the values from the file are defaults that Cookiecutter uses.

Cookiecutter uses these inputs to modify the template. A template needs to have files and directories that are worth copying and reusing, such as the skeleton code for a particular framework. To connect this boilerplate to the inputs, Cookiecutter uses the Jinja2 templating language. With Jinja2, Cookiecutter identifies all instances of the text {{cookiecutter.variable_name}} and replaces that boilerplate with the actual value of the variable. This works both within files as well as for file and directory names.

Loops and Conditional Logic

Jinja2 is very powerful and can do much more than just text substitution. It comes with control structures including for loops and if statements. It even has macros, which are analogous to functions in programming languages. Since all of Cookiecutter’s templating uses Jinja2, it can leverage the same control flow features. This opens enormous possibilities. For example, you could prompt a developer to specify which device types they are building an app for and have unique behaviors depending on the response.

Hooks

Pre/post-generate hooks let you run Python or shell scripts before and/or after generating a project. Inputs from the template prompts are fair game within hooks and work similarly to elsewhere in the project with Jinja2 syntax. This means you can run a script to validate a developer’s responses to the prompts. Other applications of hooks include cleaning up unwanted files or otherwise using logic that would be complicated with just Jinja2.

What are Cookiecutter’s limitations?

By design, templates are prescriptive about a project’s setup, presenting all kinds of advantages as discussed above. On the other hand, a template might be opinionated in a way that does not align with either an individual developer’s or an organization’s preferences, in which case it may be worth choosing another template or revising an existing one. Forcing a template in a situation that doesn’t make sense is less than ideal.

What are alternatives or extensions to Cookiecutter?

Boilerplate for specific frameworks

While Cookiecutter is compatible with almost any framework, some frameworks have custom boilerplate that is readily available. If you were to start a React app, there is great boilerplate to use as a starting point, and other communities often maintain similar ways to get started. Boilerplate is not incompatible with Cookiecutter, and you’ll find templates from popular boilerplate that you can use, too.

Cruft keeps templates organized

As with any new process, there is some overhead in staying organized with Cookiecutter. Especially when a team starts to manage dozens of templates or more, keeping templates up to date becomes critical. Cruft works alongside Cookiecutter to not only make projects but update existing ones as a template evolves. Cruft also has template validation capabilities to ensure projects match the latest version of a template.

Cortex offers a graphical interface for Cookiecutter

Cookiecutter uses a command-line interface, which is great for many developers. Still, some users might prefer a graphical interface complete with dropdowns and buttons. With Cortex, you can take advantage of a graphical wrapper to Cookiecutter along with a host of other features to scaffold new microservices.

Learn more about Cookiecutter

The Cookiecutter community has lots of resources to help you dig deeper.

• Cookiecutter.io
• Official documentation
• Templates
• GitHub