Bookdown: best to create a bookdown project in a package structure?

When creating a new bookdown project, is it best to create it in a package structure, i.e. with DESCRIPTION, NAMESPACE, R directory, etc.?

I know it is recommended that shiny apps be built in a package structure, but I think that comes very late (Chapter 20?) in "Mastering Shiny"; I suspect this is why I have seldom seen shiny apps in package structure. I have looked around a bit to see if the same is recommended for bookdown projects, but have not seen anything. Any guidance on this would be appreciated. Thanks!

1 Like

I feel like this is a personal decision. Here are some of my thoughts to help you with your decision:

  • Are you already comfortable with the mechanics and workflow of writing R packages? If not, then trying to write your book within a project structure is going to be overly onerous and delay your progress
  • Will your book use many reusable functions? Do you intend the readers of your book to run these functions themselves in their own analyses? These would be strong arguments to organize your code as an R package
  • I feel like a Shiny app and a bookdown book are slightly different. To share a shiny app, either the other user needs to install it locally on their machine, or you need to deploy it to a web service (eg Thus if you structure it as a package, it is much easier to install the required dependencies and start running the app by calling a package function. In contrast, a bookdown book is a static product. You can build the bookdown book locally, and then share the static product by email or copying it to a website. In other words, it is less critical that others are able to install the dependencies and build the book themselves
  • Neither the bookdown documentation nor the bookdown demo suggest structuring the project as an R package

I like R packages and encourage their use. But I don't like setting such a high bar for a "best practice". I would consider a GitHub repository with R Markdown files, an renv lockfile, and an R script such as build-book.R to be more than sufficient to qualify as a "best practice".

1 Like

@jdblischak Awesome answer! Many thanks.

1 Like

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.