Skip to content

Commit 8c71500

Browse files
blutorangeblutorange
committed
Add docs for Maven plugin
1 parent 0afd327 commit 8c71500

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

‎plugin-maven/README.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ user@machine repo % mvn spotless:check
5757
- Multiple languages
5858
- [Prettier](#prettier) ([plugins](#prettier-plugins), [npm detection](#npm-detection), [`.npmrc` detection](#npmrc-detection), [caching `npm install` results](#caching-results-of-npm-install))
5959
- [eclipse web tools platform](#eclipse-web-tools-platform)
60+
- [Rome](#rome) ([binary detection](#rome-binary), [config file](#rome-configuration-file), [input language](#rome-input-language))
6061
- **Language independent**
6162
- [Generic steps](#generic-steps)
6263
- [License header](#license-header) ([slurp year from git](#retroactively-slurp-years-from-git-history))
@@ -704,6 +705,7 @@ Currently, none of the available options can be configured yet. It uses only the
704705
<tsfmt/> <!-- has its own section below -->
705706
<prettier/> <!-- has its own section below -->
706707
<eslint/> <!-- has its own section below -->
708+
<rome/> <!-- has its own section below -->
707709

708710
<licenseHeader>
709711
<content>/* (C)$YEAR */</content> <!-- or <file>${project.basedir}/license-header</file> -->
@@ -814,6 +816,7 @@ For details, see the [npm detection](#npm-detection), [`.npmrc` detection](#npmr
814816

815817
<prettier/> <!-- has its own section below -->
816818
<eslint/> <!-- has its own section below -->
819+
<rome/> <!-- has its own section below -->
817820

818821
<licenseHeader>
819822
<content>/* (C)$YEAR */</content> <!-- or <file>${project.basedir}/license-header</file> -->
@@ -890,6 +893,7 @@ For details, see the [npm detection](#npm-detection), [`.npmrc` detection](#npmr
890893
<simple /> <!-- has its own section below -->
891894
<gson /> <!-- has its own section below -->
892895
<jackson /> <!-- has its own section below -->
896+
<rome /> <!-- has its own section below -->
893897
</json>
894898
</configuration>
895899
```
@@ -1220,6 +1224,153 @@ to true.
12201224
<a name="format"></a>
12211225
<a name="custom rules"></a>
12221226

1227+
## Rome
1228+
1229+
[homepage](https://rome.tools/). [changelog](https://github.com/rome/tools/blob/main/CHANGELOG.md). Rome is a formatter that for the Frontend written in Rust, which has a native binary,
1230+
does not require Node.js and as such, is pretty fast. It can currently format
1231+
JavaScript, TypeScript, JSX, and JSON, and may support
1232+
[more frontend languages](https://docs.rome.tools/internals/language_support/)
1233+
such as CSS in the future.
1234+
1235+
You can use rome in any language-specific format for supported languages, but
1236+
usually you will be creating a generic format.
1237+
1238+
```xml
1239+
<configuration>
1240+
<formats>
1241+
<format>
1242+
<includes>
1243+
<include>src/**/typescript/**/*.ts</include>
1244+
</includes>
1245+
1246+
<rome>
1247+
<!-- Download Rome from the network if not already downloaded, see below for more info -->
1248+
<version>12.0.0</version>
1249+
1250+
<!-- (optional) Path to the directory with the rome.json conig file -->
1251+
<configPath>${project.basedir}/path/to/config/dir</configPath>
1252+
1253+
<!-- Optional, Rome will auto detect the language based on the file extension. -->
1254+
<!-- See below for possible values. -->
1255+
<language>ts</language>
1256+
</prettier>
1257+
</rome>
1258+
1259+
</formats>
1260+
</configuration>
1261+
```
1262+
1263+
**Limitations:**
1264+
- The auto-discovery of config files (up the file tree) will not work when using
1265+
Rome within spotless.
1266+
1267+
To apply Rome to more kinds of files, just add more formats
1268+
1269+
```xml
1270+
<configuration>
1271+
<formats>
1272+
<format><includes>src/**/*.ts</includes><rome/></format>
1273+
<format><includes>src/**/*.js</includes><rome/></format>
1274+
```
1275+
1276+
### Rome binary
1277+
1278+
To format with Rome, spotless needs to find the Rome binary. By default,
1279+
spotless downloads the binary for the given version from the network. This
1280+
should be fine in most cases, but may not work e.g. when there is not connection
1281+
to the internet.
1282+
1283+
To download the Rome binary from the network, just specify a version:
1284+
1285+
```xml
1286+
<rome>
1287+
<version>12.0.0</version>
1288+
</rome>
1289+
```
1290+
1291+
Spotless uses a default version when you do not specfiy a version, but this
1292+
may change at any time, so we recommend that you always set the Rome version
1293+
you want to use. Optionally, you can also specify a directory for the downloaded
1294+
Rome binaries (defaults to `~/.m2/repository/com/diffplug/spotless/spotless-data/rome`):
1295+
1296+
```xml
1297+
<rome>
1298+
<version>12.0.0</version>
1299+
<!-- Relative paths are resolved against the project's base directory -->
1300+
<downloadDir>${user.home}/rome</downloadDir>
1301+
</rome>
1302+
```
1303+
1304+
To use a fixed binary, omit the `version` and specify a `pathToExe`:
1305+
1306+
```xml
1307+
<rome>
1308+
<pathToExe>${project.basedir}/bin/rome</pathToExe>
1309+
</rome>
1310+
```
1311+
1312+
Absolute paths are used as-is. Relative paths are resolved against the project's
1313+
base directory. To use a pre-installed Rome binary on the user's path, specify
1314+
just a name without any slashes / backslashes:
1315+
1316+
1317+
```xml
1318+
<rome>
1319+
<!-- Uses the "rome" command, which must be on the user's path. -->
1320+
<pathToExe>rome</pathToExe>
1321+
</rome>
1322+
```
1323+
1324+
### Rome configuration file
1325+
1326+
Rome is a biased formatter and linter without many options, but there are a few
1327+
basic options. Rome uses a file named [rome.json](https://docs.rome.tools/configuration/)
1328+
for its configuration. When none is specified, the default configuration from
1329+
Rome is used. To use a custom configuration:
1330+
1331+
```xml
1332+
<rome>
1333+
<!-- Must point to the directory with the "rome.json" config file -->
1334+
<!-- Relative paths are resolved against the project's base directory -->
1335+
<configPath>${project.basedir}</configPath>
1336+
</rome>
1337+
```
1338+
1339+
### Rome input Language
1340+
1341+
By default, Rome detects the language / syntax of the files to format
1342+
automatically from the file extension. This may fail if your source code files
1343+
have unusual extensions for some reason. If you are using the generic format,
1344+
you can force a certain language like this:
1345+
1346+
```xml
1347+
<configuration>
1348+
<formats>
1349+
<format>
1350+
<includes>
1351+
<include>src/**/typescript/**/*.mjson</include>
1352+
</includes>
1353+
1354+
<rome>
1355+
<version>12.0.0</version>
1356+
<language>json</language>
1357+
</prettier>
1358+
</rome>
1359+
1360+
</formats>
1361+
</configuration>
1362+
```
1363+
1364+
The following languages are currently recognized:
1365+
1366+
* `js` -- JavaScript
1367+
* `jsx` -- JavaScript + JSX (React)
1368+
* `js?` -- JavaScript, with or without JSX, depending on the file extension
1369+
* `ts` -- TypeScript
1370+
* `tsx` -- TypeScript + JSX (React)
1371+
* `ts?` -- TypeScript, with or without JSX, depending on the file extension
1372+
* `json` -- JSON
1373+
12231374
## Generic steps
12241375

12251376
[Prettier](#prettier), [eclipse wtp](#eclipse-web-tools-platform), and [license header](#license-header) are available in every format, and they each have their own section. As mentioned in the [quickstart](#quickstart), there are a variety of simple generic steps which are also available in every format, here are examples of these:

0 commit comments

Comments
 (0)