@forsakringskassan/vue-lib-template 1.5.2 → 1.6.0

package/files/README.md

@@ -2,12 +2,14 @@
 
 En mall för hur ett komponentbibliotek fungerar.
 
+Läs mer i [guide för att skapa komponenter](./project-guide/index.md).
+
 ## Dokumentation
 
 Bygg och starta dokumentationen med:
 
 ```bash
-npm run build:docs
+npm run build
 npm run start:docs
 ```
 
@@ -42,48 +44,3 @@ vue:${component}
 ```
 
 Dokumentationen genereras med [`@forsakringskassan/docs-generator`](https://forsakringskassan.github.io/docs-generator/latest/).
-
-## Att dokumentera
-
-- [ ] ingress
-- [ ] quick start: de vanliga kommandon man behöver
-- [ ] lintning och statisk kodanalys
-    - vilka verktyg körs och varför
-    - förklara html-validate och no-unknown-elements
-- [ ] förklara varför vi använder api-extractor/värde | public internal | dts-fil
-- [ ] förstå vad paketet levererar
-- [ ] så här kör du cypress
-- [ ] bundling och inte bundling, hur gör jag
-- [ ] hur dokumenterar man komponenter?
-- [x] hur bygger man dokumentationen?
-- [x] hur startar man dokumentationen?
-- [ ] checklista över vad som ska fungera
-    - importera static assets
-    - vscode: ska inte visa squiggly lines vid import av static assets
-    - vscode: ska inte visa squiggly lines vid cy.mount i komponenttest
-
-## Att göra
-
-- [x] börja med att kopiera alla rotfiler och cypresskatalog etc från designsystem (det vi inte fick med som körs från roten t ex lint osv)
-- [x] docs
-- [x] sandbox eller inte
-- [ ] stylelint, även på sfc
-- [x] levera css
-- [ ] postcss med autoprefixer ska köras
-- [x] trimma allowScripts (jättelåg prio)
-- [x] semantic release för vanligt repo
-- [ ] uppdatera .gitignore med app.vue
-- [ ] pretest: att vara eller att inte vara, det är frågan
-- [x] npm start
-- [x] npm start AwesomeComponent
-- [x] npm test
-- [x] npm run build
-- [x] npm run build:docs
-- [x] npm run start:docs
-- [x] apimock
-- [x] bättre exempelkomponent
-- [x] bättre enhetstest
-- [x] bättre komponenttest
-- [x] live exempel
-- [ ] skill för att skapa live exempel
-- [ ] skript för att rensa demo-filer

package/files/_env

@@ -0,0 +1 @@
+VITE_CAT_API_URL=/api/cat

package/files/_gitignore

@@ -1,11 +1,17 @@
-# This file is managed by @forsakringskassan/vue-lib-template.
-# Changes will be overwritten!
+# This file is partially managed by @forsakringskassan/vue-lib-template.
+#
+# Place your own rules below the "Add local changes below" comment.
+# Rules above that line may be overwritten.
 
 # vite dev
 # /src/vite-dev/app.vue
 *.tgz
 node_modules/
 
+# Environment files
+.env
+.env.*
+
 # Build artifacts
 .eslintcache
 coverage/
@@ -25,3 +31,5 @@ test-results/
 *.njsproj
 *.sln
 *.sw?
+
+# --- Add local changes below ---

package/files/_htmlvalidateignore

@@ -1,8 +1,12 @@
-# This file is managed by @forsakringskassan/vue-lib-template.
-# Changes will be overwritten!
+# This file is partially managed by @forsakringskassan/vue-lib-template.
+#
+# Place your own rules below the "Add local changes below" comment.
+# Rules above that line may be overwritten.
 
 # generated files
 dist/
 docs/public/
 docs/node_modules/
 docs/temp/
+
+# --- Add local changes below ---

package/files/_prettierignore

@@ -1,5 +1,7 @@
-# This file is managed by @forsakringskassan/vue-lib-template.
-# Changes will be overwritten!
+# This file is partially managed by @forsakringskassan/vue-lib-template.
+#
+# Place your own rules below the "Add local changes below" comment.
+# Rules above that line may be overwritten.
 
 # owned by tooling
 package-lock.json
@@ -30,3 +32,5 @@ yarn-error.log*
 *.njsproj
 *.sln
 *.sw?
+
+# --- Add local changes below ---

package/files/docs/build.mts

@@ -66,7 +66,13 @@ docs.compileScript("#apimock", "./src/bundle-mocks.ts", {
 });
 
 const mswUrl = new URL(import.meta.resolve("msw/mockServiceWorker.js"));
-docs.compileWorker("#mock-service-worker", mswUrl);
+docs.compileWorker("#mock-service-worker", mswUrl, {
+    /* this format must match `docs/src/bunde-mocks.ts`, we use iife over esm
+     * until we can properly deploy everywhere (when deployed internally the
+     * service worker refused to load due to a redirect 302), if this is changed
+     * make sure it runs when deployed internally */
+    format: "iife",
+});
 
 await docs.build([
     {

package/files/docs/package.json

@@ -13,7 +13,7 @@
     "@fkui/icon-lib-default": "6.59.0",
     "@fkui/vue": "6.59.0",
     "@forsakringskassan/apimock-express": "4.2.1",
-    "@forsakringskassan/docs-generator": "3.12.1",
+    "@forsakringskassan/docs-generator": "3.14.0",
     "@tsconfig/node24": "24.0.5",
     "@tsconfig/recommended": "1.0.13",
     "http-server": "14.1.1",

package/files/docs/src/bundle-mocks.ts

@@ -6,5 +6,6 @@ import mocks from "../../src/mocks/index.mjs";
 const workerUrl = import.meta.resolve("#mock-service-worker");
 
 export const apimockReady = setupWorker(workerUrl, mocks, {
-    type: "module",
+    /* this format must match `docs/build.mts` */
+    type: "classic",
 });

package/files/package.json

@@ -45,8 +45,8 @@
   ],
   "scripts": {
     "build": "run-s build:lib build:dts build:api",
+    "postbuild": "npm run -w docs build",
     "build:api": "fk-api-extractor api-extractor.*.json",
-    "build:docs": "npm run -w docs build",
     "build:dts": "vue-tsc -b",
     "build:lib": "fk-build-vue-lib --clean --selectors",
     "clean": "rimraf -g dist temp",
@@ -66,7 +66,6 @@
     "start:docs": "npm start -w docs",
     "stylelint": "stylelint \"src/**/*.{css,scss,vue}\"",
     "stylelint:fix": "npm run stylelint -- --fix",
-    "pretest": "npm run lint",
     "test": "vitest run",
     "unit": "vitest run --no-coverage"
   },
@@ -98,7 +97,7 @@
     "@forsakringskassan/commitlint-config": "4.2.8",
     "@forsakringskassan/cypress-config": "1.10.0",
     "@forsakringskassan/cypress-visual-regression": "5.2.0",
-    "@forsakringskassan/docs-generator": "3.12.1",
+    "@forsakringskassan/docs-generator": "3.14.0",
     "@forsakringskassan/docs-live-example": "3.0.2",
     "@forsakringskassan/eslint-config": "15.11.4",
     "@forsakringskassan/eslint-config-cli": "15.11.0",
@@ -112,9 +111,9 @@
     "@forsakringskassan/stylelint-config": "3.5.0",
     "@forsakringskassan/vite-lib-config": "5.12.5",
     "@forsakringskassan/vitest-config-jsdom": "5.0.0",
-    "@forsakringskassan/vue-lib-template": "1.5.2",
+    "@forsakringskassan/vue-lib-template": "1.6.0",
     "@html-validate/release-scripts": "7.6.12",
-    "@types/node": "24.13.6",
+    "@types/node": "24.19.0",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vue/server-renderer": "3.5.43",
     "@vue/test-utils": "2.5.1",
@@ -130,7 +129,7 @@
     "rimraf": "6.1.3",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vite": "8.3.1",
-    "vitest": "5.0.1",
+    "vitest": "5.0.2",
     "vue": "3.5.43",
     "vue-tsc": "3.3.11"
   },

package/files/project-guide/development.md

@@ -55,25 +55,24 @@ Refer to [FcCatInfoComponent.vue](https://github.com/Forsakringskassan/vue-lib-t
 
 Use the repository scripts from the root of the project unless stated otherwise. The most important commands for daily development are marked in **bold**.
 
-| Command                  | Use it for                                                                      |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| **`npm start`**          | Start the Vite development server using `src/vite-dev/app.vue`.                 |
-| **`npm run build`**      | Build the library, declaration files, API reports, and the Cloneman template.   |
-| `npm run build:lib`      | Build the distributable JavaScript and CSS library bundle.                      |
-| `npm run build:dts`      | Check and emit TypeScript declaration files.                                    |
-| `npm run build:api`      | Update API Extractor reports for the public package surface.                    |
-| **`npm run build:docs`** | Build the documentation site into `docs/public/`.                               |
-| **`npm run start:docs`** | Serve the generated documentation site locally at `http://localhost:8080`.      |
-| **`npm test`**           | Run the full test command, including the configured pre-test checks.            |
-| **`npm run unit`**       | Run Vitest without coverage. Useful for a quick unit-test loop.                 |
-| **`npm run lint`**       | Run Prettier, ESLint, Stylelint, and HTML validation checks.                    |
-| **`npm run lint:fix`**   | Apply available automatic formatting and lint fixes. Review the resulting diff. |
-| `npm run prettier:check` | Check formatting without changing files.                                        |
-| `npm run prettier:write` | Format supported files.                                                         |
-| `npm run eslint`         | Run ESLint with its cache.                                                      |
-| `npm run stylelint`      | Check styles in `src/**/*.css` and `src/**/*.scss`.                             |
-| `npm run html-validate`  | Validate HTML, Vue files, and Markdown examples.                                |
-| `npm run clean`          | Remove generated `dist/` and `temp/` files.                                     |
+| Command                  | Use it for                                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| **`npm start`**          | Start the Vite development server using `src/vite-dev/app.vue`.                             |
+| **`npm run build`**      | Build the library, declaration files, API reports, documentation and the Cloneman template. |
+| `npm run build:lib`      | Build the distributable JavaScript and CSS library bundle.                                  |
+| `npm run build:dts`      | Check and emit TypeScript declaration files.                                                |
+| `npm run build:api`      | Update API Extractor reports for the public package surface.                                |
+| **`npm run start:docs`** | Serve the generated documentation site locally at `http://localhost:8080`.                  |
+| **`npm test`**           | Run Vitest                                                                                  |
+| **`npm run unit`**       | Run Vitest without coverage. Useful for a quick unit-test loop.                             |
+| **`npm run lint`**       | Run Prettier, ESLint, Stylelint, and HTML validation checks.                                |
+| **`npm run lint:fix`**   | Apply available automatic formatting and lint fixes. Review the resulting diff.             |
+| `npm run prettier:check` | Check formatting without changing files.                                                    |
+| `npm run prettier:write` | Format supported files.                                                                     |
+| `npm run eslint`         | Run ESLint with its cache.                                                                  |
+| `npm run stylelint`      | Check styles in `src/**/*.css` and `src/**/*.scss`.                                         |
+| `npm run html-validate`  | Validate HTML, Vue files, and Markdown examples.                                            |
+| `npm run clean`          | Remove generated `dist/` and `temp/` files.                                                 |
 
 ## Running examples
 
@@ -85,12 +84,25 @@ npm start catinfo
 
 This uses fuzzy search to find and start the best matching file in `src/examples/` (e.g., `CatInfoExample.vue`).
 
+## API URL configuration
+
+The cat example reads its endpoint from the Vite environment variable `VITE_CAT_API_URL` in `.env`.
+The repository's `.env` sets the local mock endpoint:
+
+```bash
+VITE_CAT_API_URL=/api/cat
+```
+
+If you need to vary variables between different environments, create additional `.env` files for each mode, for example `.env.development` and `.env.production`. See the [Vite documentation](https://vite.dev/guide/env-and-mode#env-variables).
+
+Restart the development server after changing the value in an env file.
+
 ## Documentation commands
 
 Documentation is maintained in `docs/` and generated with [`@forsakringskassan/docs-generator`](https://forsakringskassan.github.io/docs-generator/latest/). A typical local workflow is:
 
 ```bash
-npm run build:docs
+npm run build
 npm run start:docs
 ```
 

package/files/project-guide/documentation.md

@@ -47,7 +47,8 @@ The reference implementation shows this pattern in [FcCatInfoComponentLiveExampl
 
 See the [docs-live-example README](https://github.com/Forsakringskassan/docs-live-example/blob/main/README.md) for the implementation details behind interactive examples.
 
-A runnable example is part of the documentation contract, not optional decoration. Add at least one for every component and verify it through `npm run build:docs` and the local documentation server.
+A runnable example is part of the documentation contract, not optional decoration.
+Add at least one for every component and verify it through `npm run build` and the local documentation server.
 
 ## Explain usage and constraints
 

package/files/src/components/guide/FcCatInfo/cat-api.spec.ts

@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { catGetById } from "./cat-api";
 
 describe("catGetById", () => {
+    vi.stubEnv("VITE_CAT_API_URL", "/api/cat");
+
     beforeEach(() => {
         vi.stubGlobal("fetch", vi.fn());
     });

package/files/src/components/guide/FcCatInfo/cat-api.ts

@@ -1,10 +1,13 @@
 import type { Cat } from "./cat-types";
 
+const apiUrl = import.meta.env.VITE_CAT_API_URL;
+
 /**
  * @internal
  */
 export async function catGetById(id: string): Promise<Cat> {
-    const response = await fetch(`/api/cat?id=${id}`);
+    const query = new URLSearchParams({ id }).toString();
+    const response = await fetch(`${apiUrl}?${query}`);
 
     if (!response.ok) {
         const errorData = (await response.json()) as { error?: string };

package/files/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+    readonly VITE_CAT_API_URL: string;
+}
+
+interface ImportMeta {
+    readonly env: ImportMetaEnv;
+}

package/hooks/install.mjs

@@ -1,5 +1,18 @@
 
 
+async function updatePackagejson(context                )                {
+    const { getParameter, updateJsonFile } = context;
+
+    /* write repository url to "package.json" */
+    const repoUrl = getParameter("code-repo-url");
+    await updateJsonFile("package.json", {
+        repository: {
+            type: "git",
+            url: `git+${repoUrl}`,
+        },
+    });
+}
+
 async function enableDeployDocs(context                )                {
     const { getParameter, replaceInFile } = context;
     const url = getParameter("docs-repo-url");
@@ -14,6 +27,8 @@ export async function install(context                )                {
     const { getApplicationName, replaceInFile } = context;
     const scopedName = getApplicationName();
 
+    await updatePackagejson(context);
+
     /* update placeholder names with the real application name (from package.json) */
     const placeholder = /"@forsakringskassan\/vue-lib-template(\/[^"]+)?"/g;
     const quotedName = (_        , subpath                    )         => {

package/index.js

@@ -7,7 +7,7 @@
 
         const options = {
             ...packageJson.cloneman,
-            fileHash: "d52f8481fc95881263df7af7368e65c192df06f584027f33c50abe8be2f6dbaa",
+            fileHash: "2040dc28f6d366d8e92dd5c1c12f9505f76448c8ad88483604b79c89c2c5376a",
             filesDir: path.join(import.meta.dirname, "files"),
             hooksDir: path.join(import.meta.dirname, "hooks"),
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forsakringskassan/vue-lib-template",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Vue library template based on Cloneman",
   "keywords": [
     "template",
@@ -27,6 +27,7 @@
       ".agents/skills/documentation/SKILL.md",
       ".agents/skills/documentation/template.md",
       ".editorconfig",
+      ".env",
       ".gitignore",
       ".htmlvalidate.json",
       ".htmlvalidateignore",
@@ -101,6 +102,7 @@
       "src/style.scss",
       "src/theme.scss",
       "src/vite-dev/app.vue",
+      "src/vite-env.d.ts",
       "tsconfig.cypress.json",
       "tsconfig.json",
       "tsconfig.lib.json",
@@ -111,10 +113,7 @@
       ".agents/skills/documentation/SKILL.md",
       ".agents/skills/documentation/template.md",
       ".editorconfig",
-      ".gitignore",
       ".htmlvalidate.json",
-      ".htmlvalidateignore",
-      ".prettierignore",
       ".vscode/extensions.json",
       ".vscode/settings.json",
       "api-extractor.lib.json",
@@ -148,6 +147,24 @@
       "vite.config.mts"
     ],
     "partiallyManagedFiles": [
+      {
+        "filename": ".gitignore",
+        "include": {
+          "above": "--- Add local changes below ---"
+        }
+      },
+      {
+        "filename": ".htmlvalidateignore",
+        "include": {
+          "above": "--- Add local changes below ---"
+        }
+      },
+      {
+        "filename": ".prettierignore",
+        "include": {
+          "above": "--- Add local changes below ---"
+        }
+      },
       {
         "filename": "src/theme.scss",
         "include": {
@@ -188,10 +205,17 @@
       "fk-icons"
     ],
     "parameters": [
+      {
+        "key": "code-repo-url",
+        "description": "URL to code repository",
+        "help": "Format: https://example.net/project/repo.git",
+        "required": true,
+        "pattern": "https://.*.git"
+      },
       {
         "key": "docs-repo-url",
         "description": "URL to repository to deploy documentation to",
-        "help": "Format: ssh://user@host/project/repo.git",
+        "help": "Format: ssh://user@example.net:project/repo.git",
         "required": false,
         "defaultValue": "",
         "pattern": "ssh://.*.git"