Merge pull request #15494 from mshima/skip_ci-two_steps_templating

Implement modular templates system.

.github/dependabot.yml

@@ -8,6 +8,11 @@ updates:
     labels:
       - 'theme: jhipster-internals'
       - 'theme: dependencies'
+    ignored_updates:
+      - match:
+          dependency_name: 'p-queue'
+          # ESM only version
+          version_requirement: '>=7'
 
   - package-ecosystem: 'npm'
     directory: '/generators/client/templates/angular/'

generators/bootstrap/index.js

@@ -30,6 +30,7 @@ const {
 const { hasState, setModifiedFileState } = State;
 
 const BaseGenerator = require('../generator-base');
+const { MultiStepTransform } = require('../../utils/multi-step-transform');
 const { defaultConfig } = require('../generator-defaults');
 const { prettierTransform, generatedAnnotationTransform } = require('../generator-transforms');
 const { formatDateForChangelog, prepareFieldForLiquibaseTemplates } = require('../../utils/liquibase');
@@ -158,6 +159,8 @@ module.exports = class extends BaseGenerator {
         }
       });
       const transformStreams = [
+        // multi-step changes the file path, should be executed earlier in the pipeline
+        new MultiStepTransform(),
         createYoResolveTransform(this.env.conflicter),
         createYoRcTransform(),
         createEachFileTransform(file => {

generators/client/files-angular.js

@@ -38,6 +38,7 @@ const files = {
         '.eslintrc.json',
         'angular.json',
         'ngsw-config.json',
+        'README.md.jhi.client.angular',
         'webpack/environment.js',
         'webpack/proxy.conf.js',
         'webpack/webpack.custom.js',

generators/client/files-common.js

@@ -27,7 +27,7 @@ module.exports = {
 const commonFiles = {
   common: [
     {
-      templates: ['.eslintignore', `${CLIENT_MAIN_SRC_DIR}manifest.webapp`],
+      templates: ['.eslintignore', 'README.md.jhi.client', `${CLIENT_MAIN_SRC_DIR}manifest.webapp`],
     },
     {
       path: CLIENT_MAIN_SRC_DIR,

generators/client/templates/angular/README.md.jhi.client.angular.ejs

@@ -0,0 +1,48 @@
+<%#
+ Copyright 2013-2021 the original author or authors from the JHipster project.
+
+ This file is part of the JHipster project, see https://www.jhipster.tech/
+ for more information.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-%>
+<%#
+ This is a fragment file, it will be merged into to root template if available.
+ EJS fragments will process % delimiter tags in template and & delimiter tags in the merge process.
+-%>
+<&_ if (fragment.customCliSection) { -&>
+[Angular CLI][] with 
+<&_ } -&>
+<&_ if (fragment.developmentSection) { -&>
+### Using Angular CLI
+
+You can also use [Angular CLI][] to generate some custom client code.
+
+For example, the following command:
+
+```
+ng generate component my-component
+```
+
+will generate few files:
+
+```
+create <%= CLIENT_MAIN_SRC_DIR %>app/my-component/my-component.component.html
+create <%= CLIENT_MAIN_SRC_DIR %>app/my-component/my-component.component.ts
+update <%= CLIENT_MAIN_SRC_DIR %>app/app.module.ts
+```
+
+<&_ } -&>
+<&_ if (fragment.referenceSection) { _&>
+[Angular CLI]: https://cli.angular.io/
+<&_ } -&>

generators/client/templates/common/README.md.jhi.client.ejs

@@ -0,0 +1,190 @@
+<%#
+ Copyright 2013-2021 the original author or authors from the JHipster project.
+
+ This file is part of the JHipster project, see https://www.jhipster.tech/
+ for more information.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-%>
+<%#
+ This is a fragment file, it will be merged into to root template if available.
+ EJS fragments will process % delimiter tags in template and & delimiter tags in the merge process.
+-%>
+<&_
+ // Register sections and max allowed fragments, 0 for unlimited.
+ fragments.registerSections({
+   customCliSection: 1,
+ });
+_&>
+<%_
+let clientPackageMngrName = 'Npm';
+let clientPackageMngrAddGlobal = 'install -g';
+let clientPackageMngrAdd = 'install --save --save-exact';
+let clientPackageMngrAddDev = 'install --save-dev --save-exact';
+-%>
+<&_ if (fragment.developmentSection) { -&>
+Before you can build this project, you must install and configure the following dependencies on your machine:
+
+1. [Node.js][]: We use Node to run a development web server and build the project.
+   Depending on your system, you can install Node either from source or as a pre-packaged bundle.
+
+After installing Node, you should be able to run the following command to install development tools.
+You will only need to run this command when dependencies change in [package.json](package.json).
+
+```
+<%= clientPackageManager %> install
+```
+
+We use <%= clientPackageManager %> scripts and <&- fragments.customCliSection(' ') &>[Webpack][] as our build system.
+
+  <%_ if (cacheProviderRedis || cacheProviderHazelcast || cacheProviderMemcached) { _%>
+If you are using <%= cacheProvider %> as a cache, you will have to launch a cache server.
+To start your cache server, run:
+
+```
+docker-compose -f src/main/docker/<%= cacheProviderHazelcast?'hazelcast-management-center':cacheProvider %>.yml up -d
+```
+
+    <%_ if (cacheProviderRedis) { _%>
+
+The cache can also be turned off by adding to the application yaml:
+```
+spring:
+    cache:
+        type: none
+```
+See [here](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-caching.html#boot-features-caching-provider-none) for details.
+
+**WARNING**: If you using second level hibernate cache and disabling the spring cache, you have to disable the second level hibernate cache as well since they are using
+the same CacheManager.
+    <%_ } _%>
+  <%_ } _%>
+
+Run the following commands in two separate terminals to create a blissful development experience where your browser
+auto-refreshes when files change on your hard drive.
+
+```
+  <%_ if (buildToolMaven) { _%>
+./mvnw
+  <%_ } _%>
+  <%_ if (buildToolGradle) { _%>
+./gradlew -x webapp
+  <%_ } _%>
+<%= clientPackageManager %> start
+```
+
+<%= clientPackageMngrName %> is also used to manage CSS and JavaScript dependencies used in this application. You can upgrade dependencies by
+specifying a newer version in [package.json](package.json). You can also run `<%= clientPackageManager %> update` and `<%= clientPackageManager %> install` to manage dependencies.
+Add the `help` flag on any command to see how you can use it. For example, `<%= clientPackageManager %> help update`.
+
+The `<%= clientPackageManager %> run` command will list all of the scripts available to run for this project.
+
+### PWA Support
+
+JHipster ships with PWA (Progressive Web App) support, and it's turned off by default. One of the main components of a PWA is a service worker.
+
+  <%_ if (!clientFrameworkAngular) { _%>
+The service worker initialization code is commented out by default. To enable it, uncomment the following code in `<%= CLIENT_MAIN_SRC_DIR %>index.html`:
+
+```html
+<script>
+    if ('serviceWorker' in navigator) {
+        navigator.serviceWorker
+        .register('./service-worker.js')
+        .then(function() { console.log('Service Worker Registered'); });
+    }
+</script>
+```
+
+Note: [Workbox](https://developers.google.com/web/tools/workbox/) powers JHipster's service worker. It dynamically generates the `service-worker.js` file.
+  <%_ } _%>
+  <%_ if (clientFrameworkAngular) { _%>
+The service worker initialization code is disabled by default. To enable it, uncomment the following code in `<%= CLIENT_MAIN_SRC_DIR %>app/app.module.ts`:
+
+```typescript
+ServiceWorkerModule.register('ngsw-worker.js', { enabled: false }),
+```
+<%_ } _%>
+
+### Managing dependencies
+
+For example, to add [Leaflet][] library as a runtime dependency of your application, you would run following command:
+
+```
+<%= clientPackageManager %> <%= clientPackageMngrAdd %> leaflet
+```
+
+To benefit from TypeScript type definitions from [DefinitelyTyped][] repository in development, you would run following command:
+
+```
+<%= clientPackageManager %> <%= clientPackageMngrAddDev %> @types/leaflet
+```
+
+Then you would import the JS and CSS files specified in library's installation instructions so that [Webpack][] knows about them:
+  <%_ if (clientFrameworkAngular) { _%>
+Edit [<%= CLIENT_MAIN_SRC_DIR %>app/app.module.ts](<%= CLIENT_MAIN_SRC_DIR %>app/app.module.ts) file:
+
+```
+import 'leaflet/dist/leaflet.js';
+```
+
+Edit [<%= CLIENT_MAIN_SRC_DIR %>content/scss/vendor.scss](<%= CLIENT_MAIN_SRC_DIR %>content/scss/vendor.scss) file:
+
+```
+@import '~leaflet/dist/leaflet.css';
+```
+
+  <%_ } _%>
+Note: There are still a few other things remaining to do for Leaflet that we won't detail here.
+
+For further instructions on how to develop with JHipster, have a look at [Using JHipster in development][].
+
+<&_ } -&>
+<&_ if (fragment.testingSection) { -&>
+### Client tests
+
+Unit tests are run by [Jest][]. They're located in [<%= CLIENT_TEST_SRC_DIR %>](<%= CLIENT_TEST_SRC_DIR %>) and can be run with:
+
+```
+<%= clientPackageManager %> test
+```
+
+  <%_ if (protractorTests) { _%>
+UI end-to-end tests are powered by [Protractor][], which is built on top of WebDriverJS. They're located in [<%= CLIENT_TEST_SRC_DIR %>e2e](<%= CLIENT_TEST_SRC_DIR %>e2e)
+and can be run by starting Spring Boot in one terminal (`<% if (buildToolMaven) { %>./mvnw spring-boot:run<% } else { %>./gradlew bootRun<% } %>`) and running the tests (`<%= clientPackageManager %> run e2e`) in a second one.
+  <%_ } _%>
+  <%_ if (cypressTests) { _%>
+UI end-to-end tests are powered by [Cypress][]. They're located in [<%= CLIENT_TEST_SRC_DIR %>cypress](<%= CLIENT_TEST_SRC_DIR %>cypress)
+and can be run by starting Spring Boot in one terminal (`<% if (buildToolMaven) { %>./mvnw spring-boot:run<% } else { %>./gradlew bootRun<% } %>`) and running the tests (`<%= clientPackageManager %> run e2e`) in a second one.
+
+#### Lighthouse audits
+
+You can execute automated [lighthouse audits][https://developers.google.com/web/tools/lighthouse/] with [cypress audits][https://github.com/mfrachet/cypress-audit] by running `<%= clientPackageManager %> run e2e:cypress:audits`. 
+You should only run the audits when your application is packaged with the production profile.
+The lighthouse report is created in <% if (buildToolMaven) { %>`target/cypress/lhreport.html`<% } else { %>`build/cypress/lhreport.html`<% } %>
+  <%_ } _%>
+<&_ } -&>
+<&_ if (fragment.referenceSection) { -&>
+[Webpack]: https://webpack.github.io/
+[BrowserSync]: https://www.browsersync.io/
+[Jest]: https://facebook.github.io/jest/
+  <%_ if (protractorTests) { _%>
+[Protractor]: https://angular.github.io/protractor/
+  <%_ } -%>
+  <%_ if (cypressTests) { _%>
+[Cypress]: https://www.cypress.io/
+  <%_ } -%>
+[Leaflet]: https://leafletjs.com/
+[DefinitelyTyped]: https://definitelytyped.org/
+<&_ } -&>
+<&- fragments.render() -&>

generators/common/files.js

@@ -33,7 +33,7 @@ const commonFiles = {
   global: [
     {
       templates: [
-        'README.md',
+        'README.md.jhi',
         {
           file: 'gitignore',
           renameTo: () => '.gitignore',