Cookiecutter is a templating library for creating project boilerplates in any programming language. When individuals, teams and organizations create projects, they must follow consistent standards so that those projects are easily readable and searchable. Templates accelerate the code writing process, too, since developers are able to spend less time on setup and can get straight to the actual implementation.
Cookiecutter is a Python package, easily installable with pip or other package managers. It enables you to create and use templates for microservices and other software projects. It is a command line tool that doesn’t require knowledge of Python to use. Cookiecutter is widely used among software engineers, researchers, data scientists and other technical roles.
Creating a template is simple and requires updating a cookiecutter.json file. 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 any other 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 simple and powerful. We’ll cover how to do that below.
Who is Cookiecutter For?
Cookiecutter is for individuals, teams and companies to standardize their project development process and accelerate new project creation.
Example use cases include:
- Learning a new framework: Cookiecutter lowers the barriers 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 more manageable. New team members can immediately follow best practices without the risks of copying, pasting and trying to edit just the correct variables.
- Enforcing standards in an organization: Consistent foldering, file-naming conventions and other patterns enable large teams to maintain an organized codebase.
Cookiecutter Features
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, Cookiecutter uses default values.
A template needs to have files and directories worth copying and reusing, such as the skeleton code for a particular framework. Cookiecutter uses these inputs to modify the template. 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 that 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 up enormous possibilities. For example, you could prompt a developer to specify which device types for which they are building an app 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 the way they would 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 by just using Jinja2.
What Are the Limitations?
By design, templates are prescriptive with regard to 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 that 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 Some Alternatives or Extensions?
Boilerplate for Specific Frameworks
While Cookiecutter is compatible with almost any framework, some frameworks do have custom boilerplate that is readily available. If you were to start a React app, for example, there is a great boilerplate available 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 involved to stay organized with Cookiecutter. When a team starts to manage dozens of templates or more, it’s especially important to keep templates up-to-date. Cruft works alongside Cookiecutter to not only make projects but to update existing ones as a template evolves. Cruft also has template validation capabilities to ensure projects match the latest version of a template.
Learn More About Cookiecutter
The Cookiecutter community has lots of resources to help you dig deeper.
