Bootstrap your projects using templates
Written by Kristian Svedal
How can we streamline the creation of similar software projects, ensure baseline consistency and avoid the hassle of copying files across repositories?
This article is about creating and using project templates to boost your productivity.
Project template
A template can be considered a reusable blueprint – write once and use multiple times to instantiate something, saving time and frustration. In this article, that something is software projects = directory structures with files and n levels of nesting.
If there is a high probability that you (or your organization) will need to create similar software projects in the future, consider using project templates. A project template in this context is mainly a directory structure for a certain programming language, tool, or framework.
The project template should:
Be highly relevant / useful to your recurring use-case
Follow some common, agreed-upon standards (if applicable)
Be parameterized to allow the user to tailor it to their needs
Be version-controlled in Git as a template repository – allowing others to easily clone and use the template
Some use-cases and benefits of project templates:
In platform engineering – allow for self-serve Infrastructure as Code (IaC) through well-defined IaC templates (e.g. Terraform, Pulumi).
You need to create multiple APIs, for instance using FastAPI or Flask
In a large organization with many data analysts and data scientists, leverage templates for data science projects in Python
For faster onboarding of new resources – templates are a great starting point to reduce the metric “Time to contribution” and enhance further learning
We will now look more into the specifics with an introduction to Cookiecutter – a Python package for bootstrapping projects easily.
Cookiecutter
“Cookiecutter is a templating library for creating boilerplate for projects in any programming language.” (https://www.cookiecutter.io/article-post/what-is-cookiecutter-highlight). Cookiecutter is a Python package which is platform agnostic. Project templates created by using this package are referred to as cookiecutters.
It has an easy-to-use CLI with the following structure:
cookiecutter [OPTIONS] [TEMPLATE] [EXTRA_CONTEXT]...
Figure: The project’s star history on GitHub
Using a project template
With Cookiecutter, using an existing template is as easy as running a simple command: cookiecutter <path-to-template>. It takes a template (a directory structure with cookiecutter.json) as an argument and bootstraps a new project. The template could be a local template or located in a private or public template repository (e.g. stored on GitHub, GitLab). Using a template from GitHub can be done with cookiecutter gh:gituser/cookiecutter-pypackage. During this process, the available parameters are displayed on the client-side as prompts, where the user can use the default values or override them. The level of customizability is thus defined in the JSON file, placed in the root directory of the template itself.
Figure: Example - using a cookiecutter template for a Python project with Poetry, with the CLI. Sketch created with Excalidraw
Creating a project template
Creating a project template is as easy as creating a directory structure, adding a placeholder for the project name ({{cookiecutter.project_name}}), adding cookiecutter.json with various parameters, and using some Jinja syntax. This then needs to hold the variable project_name.
Variables defined in the configuration can be used to substitute a project or package name, or other files in your project. You can further add choice variables to let the user choose among various alternatives, such as what type of CLI to use, or software licenses. For more advanced usage, check out hooks which allow scripts to be run during various stages of the project generation.
What goes into a template? The short answer is whatever you decide should be included. Think carefully about what would give the developer a smooth experience, to ease the burden from the developer during the development process.
Template creation vs usage – where to start?
Find some typical use cases where this could prove its value, whether you need to improve the scalability of your platform engineering or allow data analysts / scientists / engineers to bootstrap similar projects with ease.
There are thousands of public templates out there, so there may be no need to reinvent the wheel. Just be aware that some templates might be considered “bloated” in that they add potentially a lot of irrelevant dependencies. You also might not fancy the directory structure of some templates. That should not be a surprise, as project templates are opinionated. The creator(s) of a given template make some assumptions about the usage, what would be must-haves and nice-to-haves.
Figure: Using vs creating project templates. Sketch created with Excalidraw
There are alternatives to Cookiecutter, such as Copier and Yeoman. However, Cookiecutter is a highly mature and stable project. One of its main strengths is simplicity. Furthermore, it has excellent test coverage, it is well documented, and widely used – so look no further!
See if you can leverage an existing template repository, fork and tweak it if needed, or create one yourself. Create a template regardless to learn more about how it works and, happy bootstrapping!