Skip to content

FAQ

Jump to bottom
github-actions[bot] edited this page Sep 1, 2026 · 1 revision

Generated from 'wiki-faq.ts' on 2026-08-29, 17:39:06 UTC (v2.15.8, R v4.6.1), please do not edit directly.

Is your question not answered below? Please ask it as an issue and we will answer it. Answers regularly end up on this page, so asking helps everyone who wonders the same thing later.

💮 flowR FAQ

🧑‍💻 flowR Development

How do I run all checks before pushing?

Run npm run checkup: it runs the linter, the functionality and system tests, the wiki generation, and the docker image build + smoke test concurrently, then prints one pass/fail summary. Run a subset with the job ids (e.g. npm run checkup -- lint tests) or skip the container build with npm run checkup -- --no-docker.

How to add a linting rule?

To add a new linting rule, see Create Linting Rules.

How to create new wiki pages?

To create an automatically generated wiki page, you can follow these steps:

  • Create a new file in src/documentation with a name like wiki-thename.ts.
  • Register your new wiki page in the src/cli/wiki.ts file to have it executed by the wiki generation tool.

You can test your page by piping the wiki generation script to a file. For example, you can run the following command:

npm run wiki

Alternatively use the following to generate a specific wiki page:

npm run wiki -- --filter=Dataflow

Or, activate the watch mode to automatically regenerate the wiki on changes:

npm run wiki:watch
How to do logging in flowR?

Check out the Logging Section in the Linting and Testing wiki page for more information on how to do logging in flowR.

How to generate mermaid diagrams?

There are several ways to generate mermaid diagrams based on the input data that you want to use.

How to get a REPL with debug-info/hot-reload?

To enter the development repl, execute npm run main-dev in contrast to npm run flowr this will use an unminified build (keeping debug info) and also watches the source files for changes. In case of a change, this mode automatically recompiles. Please note, that this may have negative performance implications (so do not use this for e.g., benchmarking).

How to get flowR to talk?

When using flowR from the CLI, you can use the --verbose option to get more information about what flowR is doing. While coding, however, you can use the setMinLevelOfAllLogs function to set the minimum level of logs to be displayed (this works with the FlowrLogger abstraction). In general, you can configure the levels of individual logs, such as the general log (obtained with getActiveLog) or the parseLog. Please note that flowR makes no guarantees that log outputs are persistent across versions, and it is up to the implementors to provide sensible logging. If you are an implementor and want to add logging, please make sure there are no larger runtime implications when logging is disabled. Have a look at the expensiveTrace function for example, which uses a function to generate the log message only when the log level is reached.

How to run tests with verbose logging?

Use the dedicated npm script to run all tests with trace-level log output:

npm run test:verbose

Alternatively, set the FLOWR_VERBOSE environment variable directly:

FLOWR_VERBOSE=true npm run test

Both forms accept the usual vitest filters (e.g. npm run test:verbose -- cli/server).

What are test labels?

Tests are labeled based on the flowR capabilities that they test for. The list of supported capabilities can be found on the Capabilities wiki page. For more extensive information on test labels, see the test labels wiki section.

Why can't I pass arguments when running flowR with npm?

With npm you have to pass arguments in a specific way. The -- operator is used to separate the npm arguments from the script arguments. For example, if you want to run flowR with the --help argument, you can use the following command:

npm run flowr -- --help

✨ Using flowR

How to query an R project?

For this you can use flowR's Query API. If you want to create your own project using flowR as a library, check out the flowr-analysis/sample-analyzer-project-query repository for an example project setup.

How to watch a file for changes in the REPL?

Replace the file:// prefix with watch:// when passing a path to any REPL command. flowR will run the command immediately and then re-run it every time the file (or any file inside the specified folder) changes. Press Ctrl+C or enter any other command to leave watch mode.

:df watch://path/to/analysis.R

For a folder, flowR uses the same project discovery as with file://:

:query @linter watch://path/to/project
How to configure flowR per kind of project?

Use specializeConfig: it overwrites (parts of) the configuration depending on the kind of project flowR detects (e.g. shiny-app). This is how a shiny app gets its project.implicitSources out of the box, as shiny loads these files without any source() call:

{
  "specializeConfig": {
    "shiny-app": {
      "project": {
        "implicitSources": [
          "global.R",
          "ui.R",
          "server.R",
          "app.R"
        ]
      }
    }
  }
}

Anything you configure directly wins over the value the project kind defaults to, so setting project.implicitSources yourself overrides the list above.

Where do I find all the helper objects?

flowR stores its data as plain values and puts the behavior beside it in a helper object named after the thing it is about (SourceLocation, , Identifier, ...). The Helper Objects wiki page lists every one of them, grouped by what it is about, so you can find the one that answers your question without knowing where it lives.

🇷 R FAQ

📦 R Packages

How does flowR know a package's exports?

See the Signature Database wiki page.

How to get documentation for a function or package?

There are a couple of ways to get documentation for a function or package.

🖥️ Firstly, if you have already installed the package the function originated from you can simply run ?<package name>::<function name> in an R session to print the relevant documentation. If you don't know the origin of the package, you can use ??<function name> in an R shell to fuzzy find all documentations containing <function name> or something similar.

🌐 Secondly, if you don't have or don't want to install the package you can simply google the fully qualified name of the function. Good sources include rdrr.io or rdocumentation.org. Additionally, the package documentation PDF can also be downloaded directly from cran.

What is the R prelude and R base package?

The base package contains lots of base functions like source for example. The R prelude includes the base package along with several other packages. Packages that were loaded by the prelude can be called without prefixing the function call with the package name and the :: operator.

The packages loaded by the R prelude can be seen in the attached base packages sections in the output of sessionInfo().

💻 Editor FAQ

⚙️ Recommended Editor Configs

How can I launch the flowr repl form vs code?

You can use the following launch task (.vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": [
        "node_modules/**"
      ],
      "program": "${workspaceFolder}/src/cli/flowr.ts",
      "preLaunchTask": "npm: build:dev",
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229
    }
  ]
}
How can I make eslint and ZED work together?

Use this project config (.zed/settings.json) to disable all formatters except eslint:

{
  "languages": {
    "TypeScript": {
      "formatter": [],
      "prettier": {
        "allowed": false
      },
      "code_actions_on_format": {
        "source.fixAll.eslint": true
      }
    }
  },
  "hard_tabs": true
}

Currently maintained by Florian Sihler and Oliver Gerstl at Ulm University
Email | GitHub | Penguins | Portfolio

💮 flowR Home (Landing Page)

Clone this wiki locally