---
title: "Project Templates"
date-meta: 2022-12-12
---

RStudio includes support for custom, user-defined project templates. Project templates can be used to create new projects with a pre-specified structure.

Project templates can be accessed through the **New Project...** wizard. All registered project templates are made available within the **New Directory** portion of the wizard:

![](images/new-project.png){fig-alt="A screenshot of the RStudio > New Project wizard"}

R packages are the primary vehicle through which RStudio project templates are distributed. Package authors can provide a small bit of metadata describing the template functions available in their package -- RStudio will discover these project templates on start up, and make them available in the **New Project...** dialog.

## Example

We'll use the [ptexamples](https://github.com/rstudio/ptexamples) package to illustrate how a project template can be defined. This package exports a project template that is presented like so from the **New Project...** wizard:

![](images/ptexamples-wizard.png){fig-alt="A screenshot of the Create Example Project Template wizard with a directory name and other user input options."}

After the user clicks **Create Project**, a new project will be created, and the `hello_world()` template function will be called to initialize the project. Here's what the IDE looks like after calling this template function with the aforementioned inputs:

![](images/ptexamples-rstudio.png){fig-alt="A screenshot of the newly created ptexamples RStudio project displaying the index with the user inputs."}

To try using this project template locally, install the package:

``` r
# if needed install.packages("devtools")
devtools::install_github("rstudio/ptexamples")
```

Restart RStudio and then access the `ptexamples` template from the **New Project** wizard.

## Defining the Template Function

The `ptexamples` package contains a function, [`hello_world()`](https://github.com/rstudio/ptexamples/blob/master/R/hello_world.R), intended to be used as a project template. The function has the signature:

``` r
hello_world <- function(path, ...) {
  # ensure path exists
  dir.create(path, recursive = TRUE, showWarnings = FALSE)

  # generate header for file
  header <- c(
    "# This file was generated by a call to 'ptexamples::hello_world()'.",
    "# The following inputs were received:",
    ""
  )

  # collect inputs and paste together as 'Parameter: Value'
  dots <- list(...)
  text <- lapply(seq_along(dots), function(i) {
    key <- names(dots)[[i]]
    val <- dots[[i]]
    paste0(key, ": ", val)
  })

  # collect into single text string
  contents <- paste(
    paste(header, collapse = "\n"),
    paste(text, collapse = "\n"),
    sep = "\n"
  )

  # write to index file
  writeLines(contents, con = file.path(path, "INDEX"))
}
```

When this function is invoked by RStudio, it will receive the `path` as the path to the newly created project, as well as arguments as received from its input widgets. This function collects its inputs, and echos them to a file called `INDEX` in the newly-created project path.

## Defining the Template Metadata

After defining a function to be used as a project template, some initial metadata must be provided to let RStudio know how to use this function as a project template. The `ptexamples` package defines a project template in a file located at:

[inst/rstudio/templates/project/hello_world.dcf](https://github.com/rstudio/ptexamples/blob/master/inst/rstudio/templates/project/hello_world.dcf)

The first set of fields are used to define primary information about the project template:

``` yaml
Binding: hello_world
Title: Example Project Template
OpenFiles: INDEX
```

-   The **Binding** field tells RStudio which R function the project template is associated with. When a user creates a new project using this template, the `hello_world()` function defined by this package will be used to generate the project.

-   The **Title** field is used and shown within the new project wizard.

-   The **OpenFiles** field instructs the IDE to open a file called `INDEX` when the project is first opened, after creating the project.

The following sets of fields are used to define input widgets:

``` yaml
Parameter: check
Widget: CheckboxInput
Label: Checkbox Input
Default: On
Position: left
```

-   The **Parameter** field is used to identify the parameter name. That is, the value of the widget used here will be associated with the parameter called `check` when passed to the template function `hello_world()`.

-   The **Widget** field is used to specify the type of widget to be used. Here, we use a checkbox, to allow for 'on / off' input from the user.

-   The **Label** field is used to give a label associated with the checkbox.

-   The **Default** field gives the default value for the checkbox input -- here, we want to default having the checkbox 'on', or checked.

-   The **Position** field tells the RStudio IDE that this widget should be displayed on the left side of the wizard dialog.

All together, this information tells RStudio that `hello_world()` is a function to be used in generating new projects, as well as what widgets should be used for arguments that `hello_world()` can accept.

## Primary Metadata

The following fields are accepted as part of the primary metadata regarding a project template:

-   **Binding** *(required)*: The name of the R function to be called when this project template is invoked.

-   **Title** *(required)*: The title to be shown within the **New Project...** wizard.

-   **Subtitle**: The subtitle to be shown within the **New Project...** wizard. This will be shown when the user hovers over the project name in the dialog. When unsupplied, this field will be generated based on the content of the **Title** field.

-   **Caption**: The caption to be shown on the landing page for this template function. When unsupplied, this field will be generated based on the content of the **Title** field.

-   **Icon**: The path to an icon, on disk, to be used in the dialog. Must be a `.png` file of size less than 64kb.

-   **OpenFiles**: A comma-delimited set of values, indicating files that should be opened by RStudio when the project is generated. Shell-style globs can be used to indicate when multiple files matching some pattern should be opened -- for example, `OpenFiles: R/*.R` would indicate that RStudio should open all `.R` files within the `R` folder of the generated project.

## Input Widgets

The following widget types are accepted for the **Widget** field in widget descriptions.

### CheckboxInput

Represent a `TRUE` / `FALSE` input value using a checkbox.

#### Example

``` yaml
Parameter: check
Widget: CheckboxInput
Label: label
```

### SelectInput

Select a single item out of a menu list of items. The **Fields** field should be a comma-separated list of fields to be included in the select input.

#### Example

``` yaml
Parameter: project_type
Widget: SelectInput
Label: Project Type
Fields: project, package
```

#### TextInput

Accept unrestricted text input from the user.

#### Example

``` yaml
Parameter: author
Widget: TextInput
Label: Author
```

### FileInput

Provide the path to a file on disk.

#### Example

``` yaml
Parameter: file
Widget: FileInput
Label: Data file
```
