Merge pull request mvnpm#5133 from ia3andy/fixes

Improve user xp (nav, doc, readme, ...)
phillip-kruger · Mar 6, 2024 · d7fbfef · d7fbfef
2 parents ba5ff9b + 006cf77
commit d7fbfef
Show file tree

Hide file tree

Showing 12 changed files with 390 additions and 213 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -20,4 +20,6 @@ jobs:
         distribution: 'temurin'
         cache: maven
     - name: Build with Maven
-      run: mvn -B  formatter:validate impsort:check package --file pom.xml
+      run: mvn -B  formatter:validate impsort:check package -Dno-format --file pom.xml
+    - name: Build with Maven (Native)
+      run: mvn -B install -Dnative -Dquarkus.native.container-build -Dnative.surefire.skip -Dquarkus.profile=test
diff --git a/.gitignore b/.gitignore
@@ -42,3 +42,6 @@ nbactions.xml
 .env
 /dev.sh
 /local.sh
+
+# Quarkus
+.quarkus
diff --git a/.locker/pom.xml b/.locker/pom.xml
@@ -29,6 +29,7 @@
         <groupId>org.mvnpm.at.mvnpm</groupId>
         <artifactId>codeblock</artifactId>
         <version>1.0.6</version>
+        <scope>provided</scope>
       </dependency>
       <dependency>
         <groupId>org.mvnpm.at.mvnpm</groupId>
@@ -48,12 +49,36 @@
         <version>3.5.1</version>
         <scope>runtime</scope>
       </dependency>
+      <dependency>
+        <groupId>org.mvnpm.at.quarkus-webcomponents</groupId>
+        <artifactId>badge</artifactId>
+        <version>1.0.0</version>
+        <scope>provided</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.mvnpm.at.quarkus-webcomponents</groupId>
+        <artifactId>card</artifactId>
+        <version>1.0.0</version>
+        <scope>provided</scope>
+      </dependency>
       <dependency>
         <groupId>org.mvnpm.at.types</groupId>
         <artifactId>trusted-types</artifactId>
         <version>2.0.7</version>
         <scope>runtime</scope>
       </dependency>
+      <dependency>
+        <groupId>org.mvnpm.at.vaadin</groupId>
+        <artifactId>component-base</artifactId>
+        <version>24.3.7</version>
+        <scope>provided</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.mvnpm.at.vaadin</groupId>
+        <artifactId>icon</artifactId>
+        <version>24.3.7</version>
+        <scope>provided</scope>
+      </dependency>
       <dependency>
         <groupId>org.mvnpm.at.vaadin</groupId>
         <artifactId>router</artifactId>
@@ -66,6 +91,18 @@
         <version>2.0.6</version>
         <scope>runtime</scope>
       </dependency>
+      <dependency>
+        <groupId>org.mvnpm.at.vaadin</groupId>
+        <artifactId>vaadin-lumo-styles</artifactId>
+        <version>24.3.7</version>
+        <scope>provided</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.mvnpm.at.vaadin</groupId>
+        <artifactId>vaadin-themable-mixin</artifactId>
+        <version>24.3.7</version>
+        <scope>provided</scope>
+      </dependency>
       <dependency>
         <groupId>org.mvnpm.at.vaadin</groupId>
         <artifactId>vaadin-usage-statistics</artifactId>
@@ -78,6 +115,12 @@
         <version>1.11.2</version>
         <scope>runtime</scope>
       </dependency>
+      <dependency>
+        <groupId>org.mvnpm</groupId>
+        <artifactId>compare-versions</artifactId>
+        <version>6.1.0</version>
+        <scope>provided</scope>
+      </dependency>
       <dependency>
         <groupId>org.mvnpm</groupId>
         <artifactId>lit-element</artifactId>
@@ -96,6 +139,12 @@
         <version>3.1.2</version>
         <scope>runtime</scope>
       </dependency>
+      <dependency>
+        <groupId>org.mvnpm</groupId>
+        <artifactId>marked</artifactId>
+        <version>12.0.0</version>
+        <scope>provided</scope>
+      </dependency>
       <dependency>
         <groupId>org.mvnpm</groupId>
         <artifactId>path-to-regexp</artifactId>

diff --git a/README.md b/README.md
@@ -1,24 +1,44 @@
-![Logo](brand/fulllogo_transparent_nobuffer.png)
+![Logo](brand/fulllogo.png)
 
-Consume the NPM packages directly from Maven and Gradle projects.
+### Use npm like any other Maven dependency...
 
-A lot of packages are already synced on Central, you may check this from [mvnpm.org](mvnpm.org): <img height="25" alt="image" src="https://github.com/mvnpm/mvnpm/assets/2223984/60aa898d-73e2-4a5e-83ec-fb7e0a7d22c3">
+**mvnpm** (Maven NPM) allows to consume the [NPM Registry](https://www.npmjs.com/) packages as dependencies directly from a Maven or Gradle project:
 
+```xml
+    <dependency>
+        <groupId>org.mvnpm</groupId>
+        <artifactId>{package-name}</artifactId>
+        <version>{package-version}</version>
+        <scope>{runtime/provided}</scope>
+    </dependency>
+```
+
+_Use `org.mvnpm.at.{namespace}` as groupId for a particular namespace (i.e. `@hotwired/stimulus` becomes `org.mvnpm.at.hotwired:stimulus`)._
 
-If it's not:
-- Configure your project to use the MVNPM Maven Repository as a fallback. When a package is missing, it will fetch it from the fallback repository and automatically trigger a sync with Maven Central.
-- Click to trigger a sync with Maven Central: <img height="25" alt="image" src="https://github.com/mvnpm/mvnpm/assets/2223984/923f09ff-9631-4c11-aa61-8f6a9ded73d8">
+### How to consume?
 
+*   Packaged and served with the [Quarkus Web Bundler extension](https://docs.quarkiverse.io/quarkus-web-bundler/dev/index.html) using scope "provided".
+*   Directly Served by Quarkus with scope "runtime"
+*   In any Java application with [importmaps](https://github.com/mvnpm/importmap) or [esbuild-java](https://github.com/mvnpm/esbuild-java)
+*   In any Java application like you would have done with [webjars](https://www.webjars.org/)
 
+### How to sync a missing package?
 
+A lot of packages are already synced on Central, which mean they can directly be used from you pom.xml or build.gradle. You may check if a package version is available by looking at the "Maven central" badge on the [Browse page](/).  
+**If it's not:**
 
-## Configure the MVNPM Maven Repository as a fallback
+*   Click on the "Maven Central" badge to trigger a sync with Maven Central
+*   Configure your local Maven settings to use the [MVNPM Maven Repository as a fallback](#configure-fallback-repo). When a package is missing, it will fetch it from the fallback repository and automatically trigger a sync with Maven Central.
 
+**You should use the Maven Central repository for production builds.**
 
-In your settings.xml:
+### How to configure the fallback repository?
+
+The **mvnpm** Maven repository is a facade on top of the [NPM Registry](https://www.npmjs.com/), it is handy when starting (or updating versions) on a project with many non synchronised packages (which will become more and more unlikely in the future).  
+to use it in your local Maven settings add the following to your settings.xml (typically /home/your-username/.m2/settings.xml)
 
 ```xml
-<settings>
+    <settings>
     <profiles>
         <profile>
             <id>mvnpm-repo</id>
@@ -32,7 +52,7 @@ In your settings.xml:
                     <snapshots>
                         <enabled>false</enabled>
                     </snapshots>
-                    <id>mvnpm.org</id> 
+                    <id>mvnpm.org</id>
                     <name>mvnpm</name>
                     <url>https://repo.mvnpm.org/maven2</url>
                 </repository>
@@ -47,68 +67,44 @@ In your settings.xml:
 </settings>
 ```
 
-see https://maven.apache.org/guides/mini/guide-multiple-repositories.html for more details on multiple repositories
+### How does the mvnpm Maven repository work ?
 
-In your project pom.xml:
-```xml
-<profiles>
-        <profile>
-            <id>mvnpm-repo</id>
-            <repositories>
-                <repository>
-                    <id>central</id>
-                    <name>central</name>
-                    <url>https://repo.maven.apache.org/maven2</url>
-                </repository>
-                <repository>
-                    <snapshots>
-                        <enabled>false</enabled>
-                    </snapshots>
-                    <id>mvnpm.org</id> 
-                    <name>mvnpm</name>
-                    <url>https://repo.mvnpm.org/maven2</url>
-                </repository>
-            </repositories>
-        </profile>
-    </profiles>
-</profiles
-```
+![Schema](src/main/resources/web/static/mvnpm.png)
 
-## Include dependencies
+*   Developer's Maven build requests an npm package from Maven Central.
+*   Maven Central returns a 404 if the package does not exist.
+*   The developer's Maven build continues to the next repository (as configured above) and requests the npm package from mvnpm.
+*   mvnpm requests the NPM Registry for the package (tgz) and converts it to a JAR. It also generates and includes an import map and pom for this package.
+*   mvnpm returns this JAR to the developer, and the developer can continue with the build.
+*   In the background, mvnpm kicks off a process to create all the files needed to release this package to Maven Central. This includes:  
+    \- source  
+    \- javadoc  
+    \- signatures for all of the files (sha1, md5, asc)  
+    \- bundling all the above to upload to Central.
+*   Once the bundle exists, it gets uploaded and released to Maven Central.
+*   This means that by the time the CI/CD pipeline of the developer runs, the package is available in Maven Central.
 
-```
-    <dependency>
-        <groupId>org.mvnpm[.at.namespace]</groupId>
-        <artifactId>{ANY NPM PACKAGE NAME}</artifactId>
-        <version>{ANY NPM PACKAGE VERSION}</version>
-        <scope>runtime</scope>
-    </dependency>
-```
+### How to update versions?
 
-The scope depends on the usage of the dependencies, for example with the [Quarkus Web Bundler](https://docs.quarkiverse.io/quarkus-web-bundler/dev/advanced-guides.html#mvnpm), use `provided` scope instead.
+**mvnpm** continuously monitor the NPM Registry for any previously synchronized packages. When it detects a new version, a synchronization process will be initiated. So tools like dependabot will be able to propose the new version in your pull requests.
 
-**Examples:**
+### How to lock dependencies?
 
-Lit
-```
-    <dependency>
-        <groupId>org.mvnpm</groupId>
-        <artifactId>lit</artifactId>
-        <version>2.4.0</version>
-        <scope>runtime</scope>
-    </dependency>
-```
+**Locking with Maven**
 
-@hotwired/stimulus
-```
-    <dependency>
-        <groupId>org.mvnpm.at.hotwired</groupId>
-        <artifactId>stimulus</artifactId>
-        <version>3.2.2</version>
-        <scope>runtime</scope>
-    </dependency>
-```
+The [mvnpm locker Maven Plugin](https://github.com/mvnpm/locker) will create a version locker profile for your org.mvnpm and org.webjars dependencies. Allowing you to mimick the package-lock.json and yarn.lock files in a Maven world.
 
-For dependency locking (similar to package-lock.json in the npm world), have a look to the https://github.com/mvnpm/locker.
+It is essential as NPM dependencies are typically deployed using version ranges, without locking your builds will use different versions of dependencies between builds if any of your transitive NPM based dependencies are updated.
 
+In addition when using the locker, the number of files Maven need to download is considerably reduced as it no longer need to check all possible version ranges (better for reproducibility, contributors and CI).
 
+**Locking with Gradle**
+Gradle provides a native version locking system, to install it, add this:
+
+build.gradle
+```groovy
+dependencyLocking {
+lockAllConfigurations()
+}
+```
+Then run `gradle dependencies --write-locks` to generate the lockfile.
diff --git a/pom.xml b/pom.xml
@@ -183,27 +183,35 @@
         <groupId>org.mvnpm.at.mvnpm</groupId>
         <artifactId>codeblock</artifactId>
         <version>1.0.6</version>
+        <scope>provided</scope>
+    </dependency>
+    <!-- To compare versions -->
+    <dependency>
+      <groupId>org.mvnpm</groupId>
+      <artifactId>compare-versions</artifactId>
+      <version>6.1.0</version>
+      <scope>provided</scope>
     </dependency>
     <!-- To render Markdown -->
     <dependency>
 	<groupId>org.mvnpm</groupId>
 	<artifactId>marked</artifactId>
 	<version>12.0.0</version>
-	<scope>runtime</scope>
+	<scope>provided</scope>
     </dependency>
     <!-- Cards for display -->
     <dependency>
 	<groupId>org.mvnpm.at.quarkus-webcomponents</groupId>
 	<artifactId>card</artifactId>
 	<version>1.0.0</version>
-	<scope>runtime</scope>
+	<scope>provided</scope>
     </dependency>
     <!-- Badges for display -->
     <dependency>
 	<groupId>org.mvnpm.at.quarkus-webcomponents</groupId>
 	<artifactId>badge</artifactId>
 	<version>1.0.0</version>
-	<scope>runtime</scope>
+	<scope>provided</scope>
     </dependency>
     <!-- Testing -->
     <dependency>

diff --git a/src/main/resources/META-INF/resources/dummy.txt b/src/main/resources/META-INF/resources/dummy.txt
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
@@ -2,7 +2,6 @@ copyright.year=2023
 quarkus.banner.path=asciiart.txt
 
 quarkus.web-bundler.dependencies.node-modules=node_modules
-quarkus.web-bundler.dependencies.compile-only=false
 
 quarkus.rest-client.npm-registry.url=https://registry.npmjs.org
 quarkus.rest-client.npm-registry.verify-host=false