We've all been there. One package becomes four, a simple utility library outgrows itself, and suddenly every notebook starts with 30 lines of boilerplate.

Framework gives you conventions and helpers to keep your project organized and follow best practices without working too hard. Define packages in settings.yml, split functions across files, and track data integrity.

library(dplyr)
library(ggplot2)
library(readr)
library(digest)

# Set up paths
data_dir <- "~/project/data"
out_dir <- "~/project/output"

# Source helper functions
source("functions/helpers.R")
source("functions/utils.R")
source("functions/plots.R")

# Load and verify data
df <- read_csv("data/raw/survey.csv")
hash <- digest(df, algo = "md5")
# TODO: check if hash changed?

# Load packages from settings.yml
# Automatically source files in functions/
library(framework)
scaffold()

# Data catalog stored in settings.yml
# Get warned or abort if data changes
df <- data_read("inputs.raw.survey")

Different projects have different needs. Framework provides project types with sensible defaults for each use case. Start with a template and customize as needed.

my-project/
├── inputs/
│   ├── raw/
│   ├── intermediate/
│   ├── final/
│   └── reference/
├── notebooks/
├── scripts/
├── functions/
└── settings.yml

my-project/
├── inputs/
│   ├── raw/
│   ├── intermediate/
│   ├── final/
│   └── reference/
├── outputs/
│   ├── tables/
│   ├── figures/
│   ├── models/
│   └── reports/
├── notebooks/
├── scripts/
├── functions/
├── docs/
├── scratch/
└── settings.yml

my-project/
├── inputs/
│   ├── private/
│   │   ├── raw/
│   │   ├── intermediate/
│   │   ├── final/
│   │   └── reference/
│   └── public/
│       ├── raw/
│       ├── intermediate/
│       ├── final/
│       └── reference/
├── notebooks/
├── scripts/
├── functions/
└── settings.yml

my-project/
├── inputs/
│   ├── private/
│   │   ├── raw/
│   │   ├── intermediate/
│   │   ├── final/
│   │   └── reference/
│   └── public/
│       ├── raw/
│       ├── intermediate/
│       ├── final/
│       └── reference/
├── outputs/
│   ├── private/
│   │   ├── tables/
│   │   ├── figures/
│   │   ├── models/
│   │   └── reports/
│   └── public/
│       ├── tables/
│       ├── figures/
│       ├── models/
│       └── reports/
├── notebooks/
├── scripts/
├── functions/
├── docs/
├── scratch/
└── settings.yml

my-course/
├── data/
├── slides/
├── assignments/
├── course_docs/
├── readings/
└── settings.yml

my-course/
├── data/
├── slides/
├── assignments/
├── course_docs/
├── readings/
├── modules/
├── functions/
├── scripts/
└── settings.yml

my-talk/
├── presentation.qmd
└── settings.yml

my-talk/
├── presentation.qmd
├── data/
├── outputs/
├── scripts/
├── functions/
└── settings.yml

Define your data sources once in settings.yml. Framework tracks file paths and metadata. No more guessing which file is current or where it lives.

data:
  # Use nested YAML:
  inputs:
    raw:
      survey:
        path: inputs/raw/survey.csv
        description: Patient responses

  # Or use dot notation:
  inputs.raw.demographics:
    path: inputs/raw/demographics.rds
    locked: true  # abort if changed

# Read by catalog name
survey <- data_read("inputs.raw.survey")

# List all available data
data_list()

# Save to catalog location
data_save("inputs.final.analysis_ready", df)

Framework automatically hashes every file you read and stores it in a local SQLite database. Know immediately when source data changes. Lock critical files to abort if modified.

data:
  inputs.raw.demographics:
    path: inputs/raw/demographics.rds
    locked: true  # abort if changed

# Hashes stored automatically
# Full history of every read
# Timestamps, file paths, changes

# Hash checked on every read
df <- data_read("inputs.raw.demographics")

# If file changed since last read:
# - Warning by default
# - Abort if locked: true

# Or lock inline:
df <- data_read("inputs.raw.survey",
                locked = TRUE)

Define your packages in settings.yml. When scaffold() runs, it checks packages are installed and loads attached ones automatically. Non-attached packages stay available via namespacing.

packages:
  - name: dplyr
    auto_attach: true
  - name: ggplot2
    auto_attach: true
  - name: readr
    auto_attach: false

# Checks all packages are installed
# Installs missing packages
# Calls library() on those auto-attached
framework::scaffold()

# Use auto-attached directly
df |> filter(x > 5)

# Use non-attached with namespace
df <- readr::read_csv("data.csv")

Or manage packages in the GUI with framework::gui()

Define connections once in settings/connections.yml. Secrets stay in .env (gitignored). Framework supports SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, and DuckDB.

connections:
  framework:
    driver: sqlite
    database: framework.db

  patient_db:
    driver: postgresql
    host: env("DB_HOST")
    port: 5432
    database: env("DB_NAME")
    user: env("DB_USER")
    password: env("DB_PASS")

options:
  default_connection: patient_db

# Query with auto-disconnect
df <- db_query(
  "SELECT * FROM patients",
  "patient_db"
)

# Execute statements
db_execute(
  "DELETE FROM cache WHERE expired",
  "patient_db"
)

# Manual connection if needed
con <- db_connect("patient_db")
DBI::dbListTables(con)
DBI::dbDisconnect(con)

No more renv headaches. Enable with one command, pin versions in settings/packages.yml, and Framework handles the rest. It suppresses the constant nag messages, manages init/snapshot/restore, and keeps your lockfile in sync.

packages:
  - name: dplyr
    version: "1.1.4"
    auto_attach: true

  - name: ggplot2
    version: "3.5.0"
    auto_attach: true

  - name: tidyverse/tidyr
    ref: "main"  # GitHub
    auto_attach: false

# Enable renv (once per project)
renv_enable()

# scaffold() installs pinned versions
# and attaches packages automatically
scaffold()

# Lock current state
packages_snapshot()

# Restore on another machine
packages_restore()

Framework integrates seamlessly with S3 and S3-compatible object storage for sharing notebooks. Configure credentials globally once, then easily add them to each project. Share your work with peers in one command.

s3:
  public_docs:
    driver: s3
    bucket: env("S3_BUCKET")
    region: env("S3_REGION")
    prefix: notebooks/

options:
  default_s3_connection: public_docs

# Render and publish in one step
publish_notebook("analysis.qmd")

# Or publish to a specific connection
publish_notebook(
  "analysis.qmd",
  connection = "public_docs"
)

Configure Quarto rendering once in settings. No more fiddling with code folding, embed_resources, or output paths. Templates can be customized globally so make_notebook() spins up your preferred boilerplate instantly.

quarto:
  html:
    embed_resources: true
    toc: true
    code_fold: true
    theme: cosmo

render_dirs:
  notebooks: outputs/notebooks
  docs: outputs/docs

# Create from your template
make_notebook("analysis")
# → notebooks/analysis.qmd

# Create a script
make_script("etl")
# → scripts/etl.R

# Renders go to predictable places
# → outputs/notebooks/analysis.html

Stop re-running expensive computations. Framework's caching system stores results with automatic expiration and hash verification. Cache anything from API responses to model outputs, and let Framework handle invalidation.

# Fetch from cache or compute
result <- cache_remember("api_response", {
  httr2::request(url) |>
    req_perform() |>
    resp_body_json()
}, expire = "1 hour")

# Cache model training results
model <- cache_remember("trained_model", {
  train_model(data)
}, expire = "7 days")

# List all caches with expiry times
cache_list()

# Read from cache (NULL if missing)
cache_get("api_response")

# Write directly to cache
cache("my_data", processed_df)

# Clear specific cache
cache_forget("stale_data")

# Clear all caches
cache_flush()

AI coding assistants work best with context. Framework sets up context files to guide LLMs about your project structure, conventions, and data locations. Pick your canonical file, and git hooks copy it to the others on commit.

ai:
  # Edit this one, others sync on commit
  canonical_file: CLAUDE.md

git:
  hooks:
    ai_sync: true

# Install git hooks
git_hooks_install()

# On commit:
# 1. Reads CLAUDE.md (canonical)
# 2. Copies to AGENTS.md, COPILOT.md
# 3. All files stay in sync

# Edit once, commit, done.

No more googling "R gitignore file". Framework generates gitignores custom-crafted for each project type, with your directory settings dynamically included. Sensitive data directories are automatically excluded.

# Framework-generated .gitignore

# Private data directories
inputs/raw/
inputs/intermediate/
outputs/private/

# Environment secrets
.env
.env.local

# R artifacts
.Rhistory
.RData
*.Rproj.user/

# Check for accidental exposure
git_security_audit()

# Returns warnings for:
# - Tracked files in private dirs
# - .env files in history
# - Credentials in config
# - Large data files committed