docs(devs-infra): update documentation about Angular 13 libraries (#1151

)

CHANGELOG.md

@@ -27,29 +27,8 @@
 ## BREAKING CHANGES
 
 * **NodeJs** range version support now is `^12.20.0 || ^14.15.0 || >=16.10.0`
-* Due to the introduction of **ESM package format** for Angular packages, several things are added to the **default preset** to handle `.mjs` files from **Angular ESM packages**:
-
-  + `ng-jest-resolver` is introduced as a custom Jest resolver to resolve `.mjs` files. This custom Jest resolver will affect
-
-  how Jest loads modules. If this resolver doesn't fit the needs, users are encouraged to extend [this
-  resolver](https://github.com/thymikee/jest-preset-angular/blob/main/src/resolvers/ng-jest-resolver.ts) from the preset to suit own needs.
-
-  + `transformIgnorePatterns` is added to inform Jest to transform `.mjs` files.
-
-  + `transform` is updated to include `.mjs` extension to transform to `CommonJS` codes.
-
-If one has custom Jest config, please make sure to adjust Jest config for CJS mode as following:
-```
-// jest.config.js
-module.exports = {
-  // other config
-  resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
-  transformIgnorePatterns: ['node_modules/(?!@angular)'],
-  transform: {
-    '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular',
-  },
-}
-```
+* Due to the introduction of **ESM package format** for Angular packages, several things are added to the **default preset** 
+to handle `.mjs` files from **Angular ESM packages**. Please check our migration documentation at https://thymikee.github.io/jest-preset-angular/docs/next/guides/angular-13+
 
 
 ### Special Thanks

website/docs/getting-started/options.md

@@ -36,12 +36,14 @@ module.exports = {
       stringifyContentPathRegex: '\\.(html|svg)$',
     },
   },
+  moduleFileExtensions: ['ts', 'html', 'js', 'json'],
+  resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
+  snapshotSerializers,
   testEnvironment: 'jsdom',
+  transformIgnorePatterns: ['node_modules/(?!@angular)'],
   transform: {
-    '^.+\\.(ts|js|html|svg)$': 'jest-preset-angular',
+    '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular',
   },
-  moduleFileExtensions: ['ts', 'html', 'js', 'json'],
-  snapshotSerializers,
 };
 ```
 
@@ -55,11 +57,13 @@ Jest runs with `jest-preset-angular` neither in browser nor through dev server.
 ### Brief explanation of config
 
 - we're using some `"globals"` to pass information about where our tsconfig.json file is that we'd like to be able to transform HTML files through `ts-jest`.
-- `"transform"` – run every TS, JS, or HTML file through so called _Jest transformer_; this lets Jest understand non-JS syntax.
-- `"testEnvironment"` – the test environment to run on.
 - `"moduleFileExtensions"` – our modules are TypeScript and JavaScript files.
-- `"moduleNameMapper"` – if you're using absolute imports here's how to tell Jest where to look for them; uses regex.
+- `"moduleNameMapper"` – if you're using absolute imports here's how to tell Jest where to look for them; uses `RegExp`.
+- `"resolver"` - instruct Jest how to resolve entry file based on `package.json` definitions.
 - `"snapshotSerializers"` - array of serializers which will be applied to snapshot the code. Note: by default angular adds
   some angular-specific attributes to the code (like `ng-reflect-*`, `ng-version="*"`, `_ngcontent-c*` etc).
   This package provides serializer to remove such attributes. This makes snapshots cleaner and more human-readable.
   To remove such specific attributes use `no-ng-attributes` serializer. You need to add `no-ng-attributes` serializer manually.
+- `"testEnvironment"` – the test environment to run on.
+- `"transformIgnorePatterns"`: instruct Jest to transform certain packages which don't contain in `CommonJS` codes.
+- `"transform"` – run every `TS`, `JS`, `MJS`, or `HTML` file through so called _Jest transformer_; this lets Jest understand non-JS syntax.

website/docs/guides/angular-13+.md

@@ -30,16 +30,29 @@ module.exports = {
 
 there are no migration steps required
 
-- If one is using custom Jest config options for `transformIgnorePatterns`, `transform` and not using `preset: 'jest-preset-angular'`,
-  there are a few changes needed to be added to the Jest config:
+- If one is not having `preset: 'jest-preset-angular'` in Jest config, the config needs to be updated with new values for
+  `resolver`, `transformIgnorePatterns` and `transform`:
 
 ```js
 // jest.config.js
 module.exports = {
+  // ...other options
   resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
   transformIgnorePatterns: ['node_modules/(?!@angular)'],
   transform: {
     '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular',
   },
 };
 ```
+
+:::important
+Angular 13 libraries are also built automatically into ESM package format. Therefore, the Angular libraries should also
+be added to `transformIgnorePatterns` to avoid Jest error `SyntaxError: Cannot use import statement outside a module`,
+
+Example config:
+
+```js
+transformIgnorePatterns: ['node_modules/(?!@angular|my-ng-library-a|my-ng-library-b)'];
+```
+
+:::