Defining the recipe marketplace with a CSV file | Moderne Docs (original) (raw)
Starting with CLI version 3.55.0, the recipe marketplace in the Moderne CLI is defined via a CSV file rather than a binary Lucene index. This provides several benefits:
- Faster bootstrapping - Installing recipes only requires appending entries to a CSV file rather than rebuilding a binary index.
- Lazy JAR loading - Recipe JARs are downloaded on-demand when running recipes, rather than requiring all JARs to be present upfront.
- Human-readable format - The marketplace can be easily inspected and debugged using standard tools.
From a user perspective, all CLI commands remain the same. The CSV format is an internal optimization that improves performance without changing how you interact with the CLI.
How it works
When you install a recipe JAR using mod config recipes jar install, the CLI checks whether the JAR contains an embedded recipes.csv file:
- If present: The CLI extracts the CSV and appends its contents to your global marketplace file (see below).
- If absent: The CLI falls back to classpath scanning to discover recipes in the JAR (the previous behavior). This is significantly slower to parse than the CSV approach.
Most OpenRewrite recipe modules now include an embedded recipes.csv file. Third-party recipe libraries that don't use the OpenRewrite build plugin will still work via the fallback mechanism.
Marketplace file location
The global recipe marketplace is stored at:
~/.moderne/cli/recipes-v5.csv
For new CLI installations, this file starts empty and grows as you install recipe JARs. For existing installations, the CLI automatically migrates your previous marketplace (v4) to the new format the first time you run any marketplace-related command (jar install, search, run, etc.).
CSV format
The recipes-v5.csv file contains one row per recipe with the following columns:
| Column | Required | Description |
|---|---|---|
| ecosystem | Yes | The package ecosystem identifier (e.g., maven, npm, yaml). |
| packageName | Yes | The package coordinates (e.g., org.openrewrite.recipe:rewrite-java-dependencies). |
| name | Yes | The fully qualified recipe name (e.g., org.openrewrite.java.dependencies.AddDependency). |
| displayName | No | A human-readable recipe title. |
| description | No | A brief explanation of what the recipe does. |
| recipeCount | No | The number of recipes (direct + transitive) if this is a composite recipe. |
| category1, category2, ... categoryN | No | Hierarchical category columns. category1 is the deepest (most specific) level; higher numbers represent broader parent categories. |
| category1Description, category2Description, ... categoryNDescription | No | Optional descriptions for each corresponding category level. |
| options | No | A JSON array of the recipe's configurable options and their metadata. Must match the options defined in the recipe class. Empty if the recipe defines no options. |
| dataTables | No | A JSON array of data tables defined by the recipe. Must match the data tables the recipe explicitly produces. Empty if the recipe defines no additional data tables beyond the default data tables. |
| version | No | The resolved package version. Populated by the CLI during installation. Should not be included in JAR-embedded CSVs. |
| requestedVersion | No | The version constraint used when installing (e.g., LATEST). Populated by the CLI during installation. Should not be included in JAR-embedded CSVs. |
| team | No | An organization identifier for multi-tenancy. When set, recipes are only visible when working within that organization's context. |
Example entries
Minimal entry - Only the required columns are needed to identify a recipe:
ecosystem,packageName,name
maven,org.openrewrite:rewrite-java,org.openrewrite.java.cleanup.UnnecessaryParentheses
With metadata and categories - Includes human-readable information and hierarchical categorization:
ecosystem,packageName,name,displayName,description,recipeCount,category1,category2,requestedVersion,version
maven,org.openrewrite:rewrite-java,org.openrewrite.java.format.AutoFormat,Auto-format Java code,Formats Java source code according to style guidelines.,15,Formatting,Java,LATEST,8.45.0
With recipe options - Recipes that accept parameters include a JSON array in the options column:
ecosystem,packageName,name,displayName,description,options
maven,org.openrewrite.recipe:rewrite-java-dependencies,org.openrewrite.java.dependencies.AddDependency,Add Gradle or Maven dependency,Add a dependency to a Gradle or Maven project.,"[{""name"":""groupId"",""type"":""String"",""displayName"":""Group ID"",""description"":""The group ID of the dependency."",""required"":true},{""name"":""artifactId"",""type"":""String"",""displayName"":""Artifact ID"",""description"":""The artifact ID of the dependency."",""required"":true},{""name"":""version"",""type"":""String"",""displayName"":""Version"",""description"":""The version of the dependency.""}]"
For more examples, see the Recipe Marketplace CSV Format ADR.
Default data tables
All OpenRewrite recipes automatically produce the following data tables, which do not need to be listed in the dataTables column:
| Data table | Description |
|---|---|
| org.openrewrite.table.SourcesFileResults | Source files that were modified by the recipe. |
| org.openrewrite.table.SourcesFileErrors | Source files that had errors during recipe execution. |
| org.openrewrite.table.RecipeRunStats | Statistics about the recipe run. |
| org.openrewrite.table.ParseFailures | Files that failed to parse. |
| org.openrewrite.table.SearchResults | Source files that matched a search recipe. |
The dataTables column should only include data tables that the recipe explicitly defines beyond these defaults.
Curating categories
The recipes-v5.csv file can be manually adjusted to make it so that recipes can appear in multiple categories. You can do this by duplicating any existing recipe row and changing the category columns.
Do not attempt to create recipe entries from scratch by hand - the options JSON is complex and should be generated by the build plugins.
There are two main reasons why you'd want to duplicate recipes and change their columns:
- Cross-language recipes: Some recipes work across multiple languages and you may want them to appear in multiple places in the marketplace. For example, if you had a Java recipe that also worked for JavaScript repository, you could duplicate the recipe and change the category so that it appears in both places.
- Internal recommendations: Your company may want to create custom groupings of recipes for developers. In this case, you could duplicate the recipe and add it to a specific custom category.
When duplicating rows, the recipe metadata (options, dataTables, displayName, description) must remain identical across all copies. Only the category columns should differ.
If you maintain a recipe library and want to include an embedded recipes.csv file in your JAR, both the Gradle and Maven build plugins provide goals to generate the CSV.
Generating the CSV
To create or update your recipes.csv file, run:
- Gradle
- Maven
./gradlew recipeCsvGenerate
This scans your compiled recipe classes and resources and generates the CSV, preserving any manual customizations you've made (such as custom category assignments).
Automatic validation (Gradle only)
Once a recipes.csv file exists, validation runs automatically as part of the standard Gradle check task. This means every build will verify that:
- Content formatting is correct - Display names start with uppercase, descriptions end with periods, etc.
- The CSV is in sync with the JAR - No phantom recipes (in CSV but not in JAR) or missing recipes (in JAR but not in CSV).
If validation fails, the build will fail with detailed error messages.
For more details, see the Recipe Marketplace CSV Gradle Tasks ADR.
Automatic CSV validation is currently only available in the Gradle plugin. Maven users should manually verify that the generated CSV matches their JAR contents.
Additional resources
- ADR 0006: Recipe Marketplace CSV Format - Technical specification for the CSV format.
- Recipe Marketplace CSV Gradle Tasks ADR - Gradle plugin tasks for recipe authors.