feat(cicd): Configure build, deployment and add documentation (#14)

* build(config): add license, types and files to package.json

* refactor(vite): use ts for index.ts

* fix(releaserc): typo in css

* fix(vite): fix entrypoint

* fix(build): try to fix build by not specifying "module" in package.json

vitejs/vite#12446 (comment)

* fix(build): try to fix build by following wuruoyun/vue-component-lib-starter

* fix(build): fix typos in package.json

* fix(build): switch to vitepress for demo and developement setup

* feat(build) split up deployment and add gh-pages deployment

* fix(build): add npm ci to deploy-npm job

* fix(build): add vitepress build to job

* fix(build): add path to download-artifact step

Author: FabianWilms

.github/workflows/build.yaml

@@ -5,11 +5,38 @@ on: [push]
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read # to be able to publish a GitHub release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci             # install dependencies
+      - run: npm run build      # build library
+      - run: npm run docs:build # build docs
+      - name: upload library artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: library_dist
+          path: ./dist
+      - name: upload vitepress artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: vitepress_dist
+          path: ./docs/.vitepress/dist
+
+  deploy-npm:
+    runs-on: ubuntu-latest
+    needs: build
     permissions:
       contents: write # to be able to publish a GitHub release
       issues: write # to be able to comment on released issues
       pull-requests: write # to be able to comment on released pull requests
       id-token: write # to enable use of OIDC for npm provenance
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/beta'
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -18,10 +45,38 @@ jobs:
           cache: "npm"
           registry-url: "https://registry.npmjs.org"
       - run: npm ci        # install dependencies
-      - run: npm run build # or any other step to build your package
+      - name: Download build-results
+        uses: actions/download-artifact@v4
+        with:
+          name: library_dist
+          path: ./dist
       - name: run semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm run semantic-release
 
+  deploy-gh-pages:
+    runs-on: ubuntu-latest
+    needs: build
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Download build-results
+        uses: actions/download-artifact@v4
+        with:
+          name: vitepress_dist
+          path: ./docs/.vitepress/dist
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        id: deployment
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/.vitepress/dist

.releaserc.json

@@ -22,19 +22,15 @@
       {
         "assets": [
           {
-            "path": "dist/mde5-patternlab-vue.js",
+            "path": "dist/muc-patternlab-vue.es.js",
             "label": "JS distribution"
           },
-          {
-            "path": "dist/mde5-patternlab-vue.umd.cjs",
-            "label": "UMD/CJS distribution"
-          },
           {
             "path": "dist/assets/temporary/muenchende-style.css",
             "label": "CSS distribution"
           },
           {
-            "path": "dist/assets/temporary/muenchende-fontface.css",
+            "path": "dist/assets/temporary/muenchende-fontfaces.css",
             "label": "CSS fontface distribution"
           },
           {

README.md

@@ -20,45 +20,19 @@ See the [open issues](#) for a full list of proposed features (and known issues)
 
 ## Usage
 
-### Installation
-
-```shell
-npm i @muenchen/muc-patternlab-vue
-```
-
-Required Peer Dependencies:
-
-```
-"vue": "^3.4.0"
-```
-
-### Use
-
-e.G. Using the MucBanner-Component:
-
-```vue
-<script setup>
-import { MucBanner } from "@muenchen/muc-patternlab-vue";
-</script>
-
-<template>
-  <muc-banner title="Hello Muc">
-    <div>How are you?</div>
-  </muc-banner>
-</template>
-```
+Please refer to the [documentation](docs/guide/index.md).
 
 ## Develop
 
+### Setup
+
 ```shell
 git clone https://github.com/it-at-m/muc-patternlab-vue.git
 cd muc-patternlab-vue
 npm install
-npm run dev
+npm run docs:dev
 ```
 
-## Documentation
-
 ### Release and Publish
 
 This project uses [semantic-release](https://github.com/semantic-release/semantic-release)!
@@ -76,8 +50,12 @@ It follows [Angulars Commit Message Conventions](https://github.com/angular/angu
 1. Create a new Folder under `./src/components`-Directory
 2. Create Vue-Component (with composition api) and index.ts-File which exports your component
 3. Add your new Component to `./src/components/index.ts`
+4. Create documentation for your component
+   1. Create at least one "Basic" demo at `./docs/components/demo/<your-component>`
+   2. Create a doc-File for your component at `./docs/components/<your-component>.md`
+   3. Add your component doc to the sidebar at `./docs/.vitepress/config.ts`
 
-### Using MDE Patternlab-Icons
+### Using MDE5 Patternlab-Icons
 
 Patternlab-Icons are provided by a svg-Sprite which is automatically injected in this repos App.vue-File for local testing. You can expect the users of this library to do the same thing.
 

docs/.gitkeep

@@ -0,0 +1,16 @@
+<script setup>
+import sprites from "../../../public/assets/temporary/muc-icons.svg?raw"
+</script>
+
+<template>
+  <div>
+    <svg
+        style="display: none;"
+        v-html="sprites">
+    </svg>
+
+    <div class="demo-container">
+      <slot></slot>
+    </div>
+  </div>
+</template>

docs/.vitepress/components/DemoContainer.vue

@@ -0,0 +1,33 @@
+const path = require('path')
+
+module.exports = {
+  title: 'My Lib',
+  description: 'Just playing around.',
+  themeConfig: {
+    repo: 'https://github.com/wuruoyun/vue-component-lib-starter',
+    sidebar: [
+      {
+        text: 'Introduction',
+        children: [
+          { text: 'What is My Lib?', link: '/' },
+          { text: 'Getting Started', link: '/guide/' },
+        ],
+      }, {
+        text: 'Components',
+        children: [
+          { text: 'MucBanner', link: '/components/muc-banner' },
+          { text: 'MucButton', link: '/components/muc-button' },
+          { text: 'MucIntro', link: '/components/muc-intro' },
+        ],
+      }
+    ],
+  },
+  vite: {
+    resolve: {
+      alias: {
+        'muc-patternlab-vue': path.resolve(__dirname, '../../src'),
+      },
+      dedupe: ['vue'], // avoid error when using dependencies that also use Vue
+    }
+  }
+}

docs/.vitepress/config.ts

@@ -0,0 +1,5 @@
+.demo-container {
+  border: 1px solid lightgrey;
+  border-radius: 5px;
+  padding: 10px 20px;
+}

docs/.vitepress/theme/custom.css

@@ -0,0 +1,13 @@
+import DefaultTheme from 'vitepress/theme'
+import DemoContainer from '../components/DemoContainer.vue'
+import MucPatternlabVue from 'muc-patternlab-vue'
+
+import './custom.css'
+
+export default {
+  ...DefaultTheme,
+  enhanceApp({ app }) {
+    app.use(MucPatternlabVue)
+    app.component('DemoContainer', DemoContainer)
+  }
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,20 @@
+<template>
+  <div>
+    <muc-banner type="warning">
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr.
+    </muc-banner>
+
+    <muc-banner type="emergency">
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr.
+    </muc-banner>
+
+    <muc-banner type="info">
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr.
+    </muc-banner>
+  </div>
+</template>
+<style scoped>
+div * {
+  margin-bottom: 16px;
+}
+</style>

docs/components/demo/MucBanner/Basic.vue

@@ -0,0 +1,3 @@
+<template>
+  <muc-button>Click me</muc-button>
+</template>