fix(documentation,internet-header): Clarify and fix internet-header g…

…etting started doc
swisspost · Aug 22, 2023 · c92ff08 · c92ff08
1 parent 7b82a32
commit c92ff08
Show file tree

Hide file tree

Showing 3 changed files with 98 additions and 40 deletions.
diff --git a/.changeset/few-ducks-design.md b/.changeset/few-ducks-design.md
@@ -0,0 +1,6 @@
+---
+'@swisspost/internet-header': patch
+'@swisspost/design-system-documentation': patch
+---
+
+Clarify and fix which internet-header versions are available and how to use them.
diff --git a/packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx b/packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx
@@ -17,7 +17,14 @@ The header for client-facing applications.
 
 ## Installation
 
-### Angular, Vue JS, React (or any other bundler setup)
+### Choosing between lazy-loaded or bare component version
+
+Internet-header package provide two versions:
+
+* Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint.
+* Bare component: if you already manage the lazy-loading or don't need it for any reason, you can use the component without any overhead.
+
+### Angular, Vue.js, React (or any other bundler setup)
 
 All the popular frameworks come with some form of bundler. This makes it easy to use npm packages like the Internet Header as you can import, bundle and deliver the header with your own code.
 
@@ -27,13 +34,6 @@ When working with Angular or any other framework, the easiest installation metho
 npm install @swisspost/internet-header
 ```
 
-```typescript
-// main.ts / index.js / ...
-import { defineCustomElements } from '@swisspost/internet-header';
-
-defineCustomElements();
-```
-
 ```html
 <!-- index.html -->
 <body>
@@ -42,46 +42,63 @@ defineCustomElements();
 </body>
 ```
 
+#### Lazy-loaded
+
+```javascript
+// main.ts / index.js / ...
+import { defineCustomElements } from '@swisspost/internet-header/loader';
+
+defineCustomElements();
+```
+
+#### Bare component
+
+```javascript
+// main.ts / index.js / ...
+import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm';
+```
+
 ### Include from a CDN
 
-If you are not using any loader or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).<br/>
-There are two options available. Make sure to replace `{version}` with the version you want to use.
+If you are not using any bundler or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).<br/>
+Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version.
+
+Available CDNs:
 
-- [jsDelivr](https://www.jsdelivr.com/)
-- [unpkg](https://unpkg.com/)
+* [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header).
+* [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header).
 
-#### jsDelivr
+#### Lazy-loaded
+
+```html
+<!DOCTYPE html>
+<html>
+  <body>
+    <swisspost-internet-header project="your-project-id"></swisspost-internet-header>
+  </body>
+  <script type="module">
+    import { defineCustomElements } from '{cdnUrl}@{version}/loader/index.es2017.js';
+
+    defineCustomElements();
+  </script>
+</html>
+```
+#### Bare component
 
 ```html
 <!-- index.html -->
 <head>
   <script
     async
     type="module"
-    src="https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
+    src="{cdnUrl}@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
   ></script>
 </head>
 <body>
   <swisspost-internet-header project="your-project-id"></swisspost-internet-header>
 </body>
 ```
 
-```javascript
-// main.js | main.ts
-import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js';
-
-defineCustomElements();
-```
-
-#### unpkg
-
-```javascript
-// main.js | main.ts
-import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js';
-
-defineCustomElements();
-```
-
 ## Configuration
 
 The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header.
@@ -103,4 +120,4 @@ For settings on the header itself, see the examples provided in the left menu ba
 
 ## Help
 
-If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System Github Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a).
+If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a).
diff --git a/packages/internet-header/readme.md b/packages/internet-header/readme.md
@@ -14,36 +14,71 @@ The header docs are part of the storybook docs for the Design System.
 
 There are two possibilities to install the header on a page.
 
-### npm installation
+### Npm installation
 
 Use this if your project uses a bundler or a framework like Angular, React or Vue.
 
 ```bash
 npm install @swisspost/internet-header
 ```
 
-`main.ts`
+```html
+<!-- index.html -->
+<body>
+  <swisspost-internet-header project="your-project-id"></swisspost-internet-header>
+  ...
+</body>
+```
+
+#### Lazy-loaded
 
-```ts
-import { defineCustomElements } from '@swisspost/internet-header';
+```javascript
+// main.ts / index.js / ...
+import { defineCustomElements } from '@swisspost/internet-header/loader';
 
 defineCustomElements();
 ```
 
+#### Bare component
+
+```javascript
+// main.ts / index.js / ...
+import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm';
+```
+
 ### Basic installation
 
 Use this if you want to use the CDN version and if you don't use a bundler or a framework.
+Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version.
 
-`index.html`
+#### Lazy-loaded
 
 ```html
-<body>
-  <swisspost-internet-header project="your-project-id"></swisspost-internet-header>
-  ...
+<!DOCTYPE html>
+<html>
+  <body>
+    <swisspost-internet-header project="your-project-id"></swisspost-internet-header>
+  </body>
+  <script type="module">
+    import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.es2017.js';
+
+    defineCustomElements();
+  </script>
+</html>
+```
+#### Bare component
+
+```html
+<!-- index.html -->
+<head>
   <script
+    async
     type="module"
-    src="https://unpkg.com/@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
+    src="https://unpkg.com/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
   ></script>
+</head>
+<body>
+  <swisspost-internet-header project="your-project-id"></swisspost-internet-header>
 </body>
 ```