ProjectTemplate: a Rails-style skeleton for R projects

The Rails generator is the model, and the assumption is the point

The ProjectTemplate package lets you automatically build a directory for a new R project with a standardized subdirectory structure, and using that structure it automates data and package loading.

The inspiration is named explicitly: the rails command from Ruby on Rails, which initializes a new Rails project with the proper skeletal structure automatically. What ProjectTemplate borrows is not the code but the philosophy, and the README is explicit that it follows Rails's approach of preferring convention over configuration. The automatic data and library loading and the automatic testing work easily because assumptions are made about the directory structure and naming conventions used in your code.

That last sentence is the design contract, and it comes with a warning attached. You can customize your codebase however you would like, but you will have to edit the ProjectTemplate loading functions to use your conventions instead of the defaults. So the trade is a fixed layout in exchange for automation, and the moment you want a different layout you are maintaining a fork of the loading logic rather than configuring it.

The stated hope is that standardized data loading, automatic importing of best practice packages, integrated unit testing and useful nudges towards keeping a cleanly organized codebase will improve the quality of R coding. The nudges part is worth noting, since it implies the template carries opinionated scaffolding rather than being a neutral skeleton.

For R specifically, the pain being addressed is real. R projects are conventionally done in a notebook or a flat directory of scripts, and the moment a project has data, analysis code, functions and tests, the arrangement of those files and the loading of them becomes a personal convention that only its author knows. ProjectTemplate makes that convention the same for everyone who uses the package.

Creating a project takes three lines in the R console

Installing is a standard CRAN call, and the package is available on CRAN:

    install.packages('ProjectTemplate')

There is a second path for people who want changes that are not in the current CRAN version, installing directly from GitHub with devtools:

	library('devtools')
	install_github('KentonWhite/ProjectTemplate')

The author adds a warning about the second path: for most users, running the bleeding edge version of this package is probably a mistake. That is an unusual thing to say about your own package and it is worth respecting, because a package whose job is to create the layout of a project is a bad thing to be broken in the middle of a study.

Using it is three commands, and the middle one matters. To create a project called my-project, open R and type:

    library('ProjectTemplate')
    create.project('my-project')
    setwd('my-project')
    load.project()

create.project makes the directory and the skeletal structure, setwd moves you into it, and load.project is the call that performs the automated loading of data and packages against the conventions that were just created. The order matters, since load.project depends on the directory layout existing and on you being inside it.

The package is published under the name ProjectTemplate, with a description of providing useful additions to Django's default TestCase in the case of a different package, and here the description is a template utility for R projects that provides a skeletal project. The homepage is projecttemplate.net, and the source is under the R/ directory with the templates themselves in inst/.

The Makefile is where the CRAN release process shows through

The Makefile at the repository root is the most revealing file in the project, because it documents how a release actually happens rather than what the package does.

The default target is rd, which regenerates the documentation:

rd: git
	Rscript -e "library(methods); devtools::document()"
	git add man/ NAMESPACE
	test "$$(git status --porcelain | wc -c)" = "0" || git commit -m "document"

Two things to note. The target depends on a git target, which asserts the working tree is clean before doing anything, so the documentation is regenerated only from a clean checkout. And the result is committed, which is why the man/ directory and NAMESPACE are in the repository rather than being generated at build time.

The version bumping is where the care is. There are three variants, bump-cran, bump-gh and bump, and they differ in the suffix appended to the version in DESCRIPTION. The CRAN variant uses crant -u 2 -C, the GitHub variant rewrites the version to end in -0 and calls crant -u 3 -C, and the plain bump rewrites it to end in -0.0 and calls crant -u 4 -C. The crant calls are what run the CRAN incoming checks, so a release here is gated on the package passing the automated checks that CRAN will run on submission.

The tag target is a single shell line that extracts the version from DESCRIPTION, pulls the changelog section out of NEWS.md between the === markers, and feeds both into git tag -a. So the changelog entry and the version number are the two inputs to a release, and the Makefile makes sure they agree.

There is also a target that keeps the bundled config file in step with the package version, rewriting the version line of inst/defaults/full/config/global.dcf and amending the commit that introduced it, which means the template that ships inside the package always reports the version of the package that carries it. And a bootstrap_snap target that fetches install scripts for R's snap and texlive distributions, which is the packaging route for the Linux distribution versions of R.

The repository layout is a standard R package with a template inside it

The top level entries are what you would expect from a package published on CRAN, plus the template data.

There is the DESCRIPTION file with the package metadata, NAMESPACE, and the R/ directory holding the code. The man/ directory holds the generated documentation, inst/ holds the files installed with the package, which is where the bundled project templates and their default configuration live, and the tests/ directory holds the package's own test suite. The docs/ directory is for the site content, and build_script.R is a separate script for the build.

The packaging metadata around it is the standard R release set. cran-comments.md holds the notes submitted with a CRAN release, NEWS.md is the changelog that the tag target parses, and there are ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md for contributions, along with CODE_OF_CONDUCT.md and an appveyor.yml for continuous integration on Windows.

The R project file, ProjectTemplate.Rproj, is what you open in RStudio, and it is worth noting that this is a template for a skeleton R project that the package generates, not the package's own project file.

The version history is steady but slow. The releases are 0.11.2 on 2026-04-06, 0.11.1 on 2025-08-30 and 0.11.0 on 2024-07-01, and the last push to the repository was on 2026-05-22. The project is not archived and the recent work is recent, but the numbering shows a package that has been refined over years rather than rewritten, which fits something whose job is to be depended on by the shape of other people's work.

The licence is GPL-3.0, with a LICENSE file at the root.

What to check before you let it lay out your project

The design decision to review first is which layout you actually want, because the whole benefit depends on the structure matching your expectations and the defaults being the ones you would have chosen.

The package ships a defaults directory inside inst, and the Makefile refers to a path under inst/defaults/full/config, which indicates that there are multiple layout presets and a full one among them. The create.project call is what selects which one you get, and the README does not enumerate the alternatives. If the layout that comes by default does not match how your work is organised, you are either living with it or editing the loading functions, and the documentation is clear that the second option means owning that code.

The second thing to check is the loading behaviour itself. The automation covers data and package loading, and the assumption is a particular naming convention. If your existing project already has a directory structure and some scripts, adopting the package means renaming files or rewriting the paths in your code, and a partially renamed project is worse than either state.

The third is the version you install. The CRAN release is the safe one, and the author says the bleeding edge version is probably a mistake for most users. Since the version number in DESCRIPTION is also copied into the bundled configuration inside inst, a GitHub install would give you a template whose reported version does not match anything on CRAN, which is confusing if you later share the project with a colleague using the CRAN release.

The last consideration is that this is a GPL-3.0 package that generates a directory of files in your project. The generated files are yours, and the licence of the generator does not reach into what it produces, but if you distribute the templates themselves as part of a product, that is a different question from using the generator, and one worth raising with whoever handles licensing in your organisation.

Editorial conclusion

ProjectTemplate suits an analyst or data scientist who works in R on several projects and wants the same directory layout and the same loading behaviour in each of them, because the value comes from repeatability across projects rather than from any single feature. It does not suit you if your project needs a non-standard layout, since the documentation is explicit that you would have to edit the loading functions to use your own conventions. Before you adopt it, decide which of the bundled layouts you want, because the create.project call picks a default and the defaults directory inside the package holds the alternatives, and check the current CRAN version rather than the GitHub one, since the package author says running the bleeding edge version is probably a mistake for most users.

Frequently asked questions

Official sources

1. KentonWhite/ProjectTemplate on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases