Cross-build to sbt 2 and Scala 3. by anatoliykmetyuk · Pull Request #674 · lightbend/paradox

anatoliykmetyuk · 2026-02-26T09:07:50Z

This PR cross-compiles the plugin to Scala 3 and sbt 2, making it possible to use from sbt 2 projects. It's a big PR, so here's a summary of all the changes by category to assist with reviewing. Virtually all the changes introduced by the PR are covered by one of the categories below.

CI/Testing

JTidy's static mutable state caused flaky HTML encoding when tests ran in parallel; set Test / parallelExecution := false in core and tests to fix.
CI runs verify instead of test: githubWorkflowBuild in build.sbt now invokes verify (Test/compile, Compile/doc, test, scripted, docs/paradox), so scripted tests run in CI. Also CI is running sbt with --batch flag to prevent interactive prompts on project loading failures which are not suitable for automated scripts.

Scala 3 Compatibility

JavaConverters was removed in Scala 3; added version-specific compat/package.scala that maps to JavaConverters (2.12) or CollectionConverters (2.13/3) so core cross-compiles.
1. In Scala 2: java.util.List.asScala (JavaConverters) returns scala.collection.mutable.Buffer, which extends scala.collection.Seq. In Scala 3: java.util.Collection.asScala (CollectionConverters) returns scala.collection.Iterable, which does not extend scala.collection.Seq. Therefore we standardize by adding .toSeq where APIs are expecting Seq[String].
com.lightbend.paradox.markdown.Url had a custom copy(path, query, fragment) method that conflicted with the case class's synthetic copy in Scala 3; renamed to withComponents so core cross-compiles.
MarkdownTestkit: disambiguated Path name collision between java.nio.file.Path and com.lightbend.paradox.markdown.Path. Scala 2 and 3 use different resolution strategies so a collision happens in Scala 3. The port added explicit java.nio.file.Path and ParadoxPath alias to avoid relying on context-dependent resolution.
Scala 3 requires explicit types for implicit values. Test specs (e.g. LinkDirectiveSpec) that use implicit val context for the writer context now have an explicit type: Location[Page] => Writer.Context.

sbt 2 Compatibility

Wrapped tasks that do not support sbt 2 caching out of the box in Def.uncached.
Replaced sbt 1 in syntax (e.g. key in scope) with sbt 2 slash syntax (scope / key).
Bumped sbt-web from 1.5.8 to 1.6.0-M2 to support sbt 2; the new API requires fileConverter.value for syncMappings and deduplicateMappings, due to changes in file types between sbt 1 and sbt 2.
PluginCompat and sbt2-compat pattern is used for breaking API changes between sbt 1 and sbt 2.
sbt 2 changed ScmInfo.browseUrl from java.net.URL to java.net.URI - standardize on java.net.URI.
ParadoxPlugin.scala: inlined sourcesFor at its single call site in. Originally it was in the compat layer for sbt 0.13 support, but the plugin no longer cross-builds to sbt 0.13.
On sbt 2, target.value inside inConfig(Compile) resolves to a versioned subdirectory (target/out/jvm/scala-3.8.1/<project>/) instead of target/ as on sbt 1. This makes the output path of the plugin inconsistent. Changed paths to preserve the sbt 1 behavior throughout ParadoxPlugin.scala.

Scripted Tests

sbt 2's config parser does not allow hyphens in config names; the paradox/docs-overlay scripted test was updated to use camelCase configs (docsFirst, docsSecond).
paradox/snippet-noindent-writer and paradox/snippets expected HTML updated to match current source files. Scripted tests were not tested by the CI so the html files for those tests were broken by an scalafmt run a while ago.
paradox/libraryDependencies test was filtered for sbt 2 as the material plugin is not yet ported to sbt 2. Exclusion logic in build.sbt: verify-no-docker sbt command was changed from a simple alias to a command to enable filtering logic. scripted tests plugin checks for sbt version in build.properties to determine if it matches the sbt version the test is tested against - however this feature does not work in case of glob references, e.g. paradox/*. Logic in verify command works properly because no globs are used.

Two sbt 2 incompatibilities fixed: - paradoxDirectives += CustomDirective fails on sbt 2 because the task result type (functions) has no JsonFormat, which sbt 2 requires for disk caching. Changed to := Def.uncached(Writer.defaultDirectives :+ CustomDirective) to bypass the cache entirely. - In sbt 2, Compile/target resolves to target/out/jvm/scala-<ver>/<name> instead of target/. The paradox output was landing in the wrong directory. Changed defineSiteMappings to anchor the output at baseDirectory.value / "target" so the path stays stable across sbt versions. Also wrapped SbtWeb.syncMappings in Def.uncached so sbt 2 does not skip the file sync when restoring from task cache.

Fixes: - docs-overlay: Rename configs to docsFirst/docsSecond, add docsOverlayParadox task - generated-source: Replace in syntax with / in PageGenerator.scala - libraryDependencies: Use builtinParadoxTheme("generic") - snippet-noindent-writer, snippets: Regenerate expected HTML for Scala 3 - validation: Add sbt2-compat, use PluginCompat.toFileRefsMapping - custom-directive: Use := Def.uncached(...) for paradoxDirectives; add sbt2-compat - ParadoxPlugin: Use baseDirectory/target for output; wrap syncMappings in Def.uncached Tradeoffs: - docs-overlay: Hyphenated config invocation no longer tested; workaround via camelCase + wrapper task - libraryDependencies: Material theme no longer exercised; only generic theme verified - snippets: Expected HTML now Scala 3 format; Scala 2 brace-style output no longer covered - validation: Test depends on sbt2-compat; no longer a minimal vanilla setup - custom-directive: paradoxDirectives += no longer used; breaking change for users on sbt 2

…ot ported to sbt 2 yet

johanandren

I'm not deeploy familiar with all the required changes for sbt-2, but I think this looks good.

anatoliykmetyuk · 2026-02-27T13:28:50Z

@johanandren thank you for taking a look! I've fixed the formatting with a scalafmt run, so the CI should pass now.

eed3si9n · 2026-02-27T15:33:09Z

Thanks @anatoliykmetyuk! I can review at sbt 2.x specific parts, but at a glance, the lion's share of the changes seems to be to bring up old code base into Scala 3.x, which includes using 2.13 stdlib.

eed3si9n · 2026-02-27T15:39:37Z

plugin/src/main/scala/com/lightbend/paradox/sbt/ParadoxPlugin.scala

+        (paradoxTheme / WebKeys.deduplicators).value,
+        fileConverter.value
+      ),
+    paradoxTheme / target := baseDirectory.value / "target" / "paradox" / "theme" / configTarget(configuration.value),


Could we use

target.value / "paradox" / "theme" / configTarget(configuration.value),

like it was before, so it's safe against cross building?

The paths seem to differ between sbt 1 and 2 which causes inconsistent behavior. I've mentioned this one at the PR changes above:

On sbt 2, target.value inside inConfig(Compile) resolves to a versioned subdirectory (target/out/jvm/scala-3.8.1/<project>/) instead of target/ as on sbt 1. This makes the output path of the plugin inconsistent. Changed paths to preserve the sbt 1 behavior throughout ParadoxPlugin.scala.

The current setup should produce consistent paths during cross-build.

eed3si9n

I have a minor question about target directory, but overall lgtm

anatoliykmetyuk · 2026-02-27T16:16:00Z

The formatting failure seems to be due to the new using syntax in the Scala 3 specific sources that scalafmt recognized as invalid. I've set the dialect to scala3 with the latest commit which should solve it.

anatoliykmetyuk added 27 commits February 25, 2026 15:06

Core compiles to Scala 3

391d40f

Plugin works under Scala 3

365611c

WIP make plugin comple under sbt 2

b153a31

Cross-build plugin to sbt 2

5bd90b0

Cross-build plugin to sbt 2

c409393

Disable parallel testing as it causes flaky behavior in some tests

bc65e5c

Fix CI to be aware of sbt 2

42d89c6

Enable uncached in custom-directive scripted test

fa87758

Simplified Compat layer

899b6a9

Inlined shared sourcesFor method

f635300

Simplified webJarsClassLoader resolution

62df1cd

Simplify the uncached ++= pattern

79b90c9

Fix docker tests

a3d2169

Rename variable to minimize diff

0c3814b

Adjust Compat layer to the sbt2-compat pattern

480f132

Adjust apiURI parameter type and naming

6054b45

Revert unnecessary docsOverlayParadox test task

9c6ef1d

Restore libraryDependencies test to what it was

7630ef7

Exclude libraryDependencies test on sbt 2 as the material plugin is n…

82e0665

…ot ported to sbt 2 yet

Run tests in CI

786d784

Fix implicits usage in validation scripted test

ca4be1b

Rename compat layer dirs in accordance with the pattern

11ed9d5

Simplify path reference in MarkdownTestkit

827eb10

Remove unused import

4f86512

Fix ParadoxThemePlugin to use sbt2-compat

120f917

anatoliykmetyuk marked this pull request as ready for review February 26, 2026 09:08

anatoliykmetyuk added 2 commits February 26, 2026 18:16

Fix types in compat layer

10764e3

Include sbt 2 crossbuild into publishing in CI

7a52054

CI publication flow corrected

cfd0193

johanandren reviewed Feb 27, 2026

View reviewed changes

Fix formatting with scalafmt

6b9e64b

eed3si9n reviewed Feb 27, 2026

View reviewed changes

eed3si9n approved these changes Feb 27, 2026

View reviewed changes

Set scalafmt dialect to Scala 3

a11bfe8

anatoliykmetyuk force-pushed the sbt2-port branch from e3befcb to a11bfe8 Compare February 27, 2026 16:08

johanandren approved these changes Mar 2, 2026

View reviewed changes

johanandren merged commit cd57327 into lightbend:main Mar 2, 2026
6 checks passed

anatoliykmetyuk deleted the sbt2-port branch March 2, 2026 13:27

This was referenced Mar 3, 2026

Patch sbt-web call to SbtWeb.deduplicateMappings() #659

Open

Do something regarding paradox calling deduplicateMappings sbt/sbt-web#285

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cross-build to sbt 2 and Scala 3.#674

Cross-build to sbt 2 and Scala 3.#674
johanandren merged 32 commits intolightbend:mainfrom
anatoliykmetyuk:sbt2-port

anatoliykmetyuk commented Feb 26, 2026 •

edited

Loading

Uh oh!

johanandren left a comment

Uh oh!

anatoliykmetyuk commented Feb 27, 2026

Uh oh!

eed3si9n commented Feb 27, 2026

Uh oh!

eed3si9n Feb 27, 2026

Uh oh!

anatoliykmetyuk Feb 27, 2026 •

edited

Loading

Uh oh!

eed3si9n left a comment

Uh oh!

anatoliykmetyuk commented Feb 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

anatoliykmetyuk commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI/Testing

Scala 3 Compatibility

sbt 2 Compatibility

Scripted Tests

Uh oh!

johanandren left a comment

Choose a reason for hiding this comment

Uh oh!

anatoliykmetyuk commented Feb 27, 2026

Uh oh!

eed3si9n commented Feb 27, 2026

Uh oh!

eed3si9n Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

anatoliykmetyuk Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eed3si9n left a comment

Choose a reason for hiding this comment

Uh oh!

anatoliykmetyuk commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anatoliykmetyuk commented Feb 26, 2026 •

edited

Loading

anatoliykmetyuk Feb 27, 2026 •

edited

Loading

anatoliykmetyuk commented Feb 27, 2026 •

edited

Loading