From 3831eb2d1cecd19d6da289b1500e755a75c1c1dc Mon Sep 17 00:00:00 2001 From: Admin Date: Sun, 2 Aug 2026 21:26:54 +0000 Subject: [PATCH 1/4] Update package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 2c18ace..986e79b 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@intecion/ipal-kit", "version": "1.0.0", - "description": "Intecion Payload Advanced Library — plugin dla Payload CMS 3: i18n, SEO, formularze, consent, analytics, blog/archiwa.", + "description": "Intecion Payload Advanced Library — plugin for Payload CMS 3: i18n, SEO, forms, consent, analytics, blogs/archives.", "license": "MIT", "type": "module", "exports": { From 2f52349d63b6ccbc6e2714ccd65fe877fe9953ad Mon Sep 17 00:00:00 2001 From: Admin Date: Sun, 2 Aug 2026 21:34:02 +0000 Subject: [PATCH 2/4] Update package.json for pnpm --- package.json | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index 986e79b..a5606c2 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,12 @@ { "name": "@intecion/ipal-kit", "version": "1.0.0", - "description": "Intecion Payload Advanced Library — plugin for Payload CMS 3: i18n, SEO, forms, consent, analytics, blogs/archives.", + "description": "Intecion Payload Advanced Library — a Payload CMS 3 plugin: i18n, SEO, forms, consent, analytics, blog/archives.", "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://git.intecion.net/IntecionSoftware/ipal-kit.git" + }, "type": "module", "exports": { ".": { @@ -109,7 +113,7 @@ "pnpm": "^9 || ^10 || ^11" }, "publishConfig": { - "registry": "https://npm.pkg.github.com" + "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/" }, "pnpm": { "onlyBuiltDependencies": [ @@ -118,4 +122,4 @@ "unrs-resolver" ] } -} +} \ No newline at end of file From af8cc91a6bb86b0101d27315454886fb684fac62 Mon Sep 17 00:00:00 2001 From: Admin Date: Sun, 2 Aug 2026 21:34:35 +0000 Subject: [PATCH 3/4] Update README.md --- README.md | 302 ++++++++++++++++++++++-------------------------------- 1 file changed, 122 insertions(+), 180 deletions(-) diff --git a/README.md b/README.md index 602ffd1..f85d4d3 100644 --- a/README.md +++ b/README.md @@ -1,218 +1,160 @@ -# Payload Plugin Template +# @intecion/ipal-kit -A template repo to create a [Payload CMS](https://payloadcms.com) plugin. +Intecion Payload Advanced Library — plugin do Payload CMS 3. Dostarcza i18n +(routing per-locale, hreflang, przełącznik języka), SEO (metadane, canonical, +sitemapa, robots), formularze (Turnstile, rate limit, walidacja), consent mode, +analytics (GA4/GTM), oraz system bloga/archiwów (kolekcje pod stroną-archiwum, +listing, paginacja). -Payload is built with a robust infrastructure intended to support Plugins with ease. This provides a simple, modular, and reusable way for developers to extend the core capabilities of Payload. +Repozytorium: https://git.intecion.net/IntecionSoftware/ipal-kit +(dostęp tylko dla zalogowanych pracowników Intecion). -To build your own Payload plugin, all you need is: +--- -- An understanding of the basic Payload concepts -- And some JavaScript/Typescript experience +## Instalacja -## Background +> **Serwer jest prywatny.** Zarówno kod, jak i pakiet w Gitea są widoczne tylko +> po zalogowaniu. Każdy sposób instalacji wymaga tokenu dostępu (PAT) z konta +> pracownika. Bez niego instalacja zwróci 404 albo błąd autoryzacji. -Here is a short recap on how to integrate plugins with Payload, to learn more visit the [plugin overview page](https://payloadcms.com/docs/plugins/overview). +### Krok 1 — token dostępu (raz na osobę) -### How to install a plugin +W Gitea: **Ustawienia → Aplikacje → Wygeneruj token dostępu**. Nadaj zakresy: +- `read:package` — do instalacji (wystarczy pracownikowi) +- `write:package` — dodatkowo, jeśli będziesz publikować wydania -To install any plugin, simply add it to your payload.config() in the Plugin array. +Skopiuj token (pokazuje się raz). -```ts -import myPlugin from 'my-plugin' +### Krok 2 — wybierz drogę instalacji -export const config = buildConfig({ - plugins: [ - // You can pass options to the plugin - myPlugin({ - enabled: true, - }), - ], -}) +Dwie drogi. **A (rejestr Gitea)** jest zalecana dla zespołu — daje wersjonowanie +i szybką instalację gotowego builda. **B (bezpośrednio z git)** nie wymaga +publikowania, ale buduje/pobiera z repo. + +--- + +## Droga A — rejestr npm w Gitea (zalecana) + +Gitea ma wbudowany rejestr npm. Publikujesz zbudowany pakiet, pracownicy pobierają +gotowy `dist` — bez budowania u siebie. + +### Konfiguracja u pracownika (instalacja) + +`.npmrc` w projekcie **albo** globalnie (`~/.npmrc`): + +``` +@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/ +//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} ``` -### Initialization +Token w zmiennej środowiskowej (bezpieczniej niż wpisany wprost — `.npmrc` można +wtedy nawet zacommitować): -The initialization process goes in the following order: - -1. Incoming config is validated -2. **Plugins execute** -3. Default options are integrated -4. Sanitization cleans and validates data -5. Final config gets initialized - -## Building the Plugin - -When you build a plugin, you are purely building a feature for your project and then abstracting it outside of the project. - -### Template Files - -In the Payload [plugin template](https://github.com/payloadcms/payload/tree/3.x/templates/plugin), you will see a common file structure that is used across all plugins: - -1. root folder -2. /src folder -3. /dev folder - -#### Root - -In the root folder, you will see various files that relate to the configuration of the plugin. We set up our environment in a similar manner in Payload core and across other projects, so hopefully these will look familiar: - -- **README**.md\* - This contains instructions on how to use the template. When you are ready, update this to contain instructions on how to use your Plugin. -- **package**.json\* - Contains necessary scripts and dependencies. Overwrite the metadata in this file to describe your Plugin. -- .**eslint**.config.js - Eslint configuration for reporting on problematic patterns. -- .**gitignore** - List specific untracked files to omit from Git. -- .**prettierrc**.json - Configuration for Prettier code formatting. -- **tsconfig**.json - Configures the compiler options for TypeScript -- .**swcrc** - Configuration for SWC, a fast compiler that transpiles and bundles TypeScript. -- **vitest**.config.js - Config file for Vitest, defining how tests are run and how modules are resolved - -**IMPORTANT\***: You will need to modify these files. - -#### Dev - -In the dev folder, you’ll find a basic payload project, created with `npx create-payload-app` and the blank template. - -**IMPORTANT**: Make a copy of the `.env.example` file and rename it to `.env`. Update the `DATABASE_URL` to match the database you are using and your plugin name. Update `PAYLOAD_SECRET` to a unique string. -**You will not be able to run `pnpm/yarn dev` until you have created this `.env` file.** - -`myPlugin` has already been added to the `payload.config()` file in this project. - -```ts -plugins: [ - myPlugin({ - collections: { - posts: true, - }, - }), -] +```bash +# ~/.zshrc +export GITEA_TOKEN=twój_token_z_gitea ``` -Later when you rename the plugin or add additional options, **make sure to update it here**. +Instalacja: -You may wish to add collections or expand the test project depending on the purpose of your plugin. Just make sure to keep this dev environment as simplified as possible - users should be able to install your plugin without additional configuration required. - -When you’re ready to start development, initiate the project with `pnpm/npm/yarn dev` and pull up [http://localhost:3000](http://localhost:3000) in your browser. - -#### Src - -Now that we have our environment setup and we have a dev project ready to - it’s time to build the plugin! - -**index.ts** - -The essence of a Payload plugin is simply to extend the payload config - and that is exactly what we are doing in this file. - -```ts -export const myPlugin = - (pluginOptions: MyPluginConfig) => - (config: Config): Config => { - // do cool stuff with the config here - - return config - } +```bash +pnpm add @intecion/ipal-kit ``` -First, we receive the existing payload config along with any plugin options. +### Publikacja (osoba wydająca) -From here, you can extend the config as you wish. - -Finally, you return the config and that is it! - -##### Spread Syntax - -Spread syntax (or the spread operator) is a feature in JavaScript that uses the dot notation **(...)** to spread elements from arrays, strings, or objects into various contexts. - -We are going to use spread syntax to allow us to add data to existing arrays without losing the existing data. It is crucial to spread the existing data correctly – else this can cause adverse behavior and conflicts with Payload config and other plugins. - -Let’s say you want to build a plugin that adds a new collection: - -```ts -config.collections = [ - ...(config.collections || []), - // Add additional collections here -] -``` - -First we spread the `config.collections` to ensure that we don’t lose the existing collections, then you can add any additional collections just as you would in a regular payload config. - -This same logic is applied to other properties like admin, hooks, globals: - -```ts -config.globals = [ - ...(config.globals || []), - // Add additional globals here -] - -config.hooks = { - ...(incomingConfig.hooks || {}), - // Add additional hooks here +W `package.json` pluginu (jest już ustawione): +```json +"publishConfig": { + "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/" } ``` -Some properties will be slightly different to extend, for instance the onInit property: - -```ts -import { onInitExtension } from './onInitExtension' // example file - -config.onInit = async (payload) => { - if (incomingConfig.onInit) await incomingConfig.onInit(payload) - // Add additional onInit code by defining an onInitExtension function - onInitExtension(pluginOptions, payload) -} +`~/.npmrc` z tokenem `write:package`: +``` +//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} ``` -If you wish to add to the onInit, you must include the **async/await**. We don’t use spread syntax in this case, instead you must await the existing `onInit` before running additional functionality. - -In the template, we have stubbed out some addition `onInit` actions that seeds in a document to the `plugin-collection`, you can use this as a base point to add more actions - and if not needed, feel free to delete it. - -##### Types.ts - -If your plugin has options, you should define and provide types for these options. - -```ts -export type MyPluginConfig = { - /** - * List of collections to add a custom field - */ - collections?: Partial> - /** - * Disable the plugin - */ - disabled?: boolean -} +Wydanie: +```bash +pnpm clean && pnpm build +npm version patch # 1.0.0 → 1.0.1 +npm publish ``` -If possible, include JSDoc comments to describe the options and their types. This allows a developer to see details about the options in their editor. +Zaleta rejestru: semver — pnpm zawsze widzi nową wersję, koniec z ręcznym +czyszczeniem cache. `publishConfig` działa poprawnie (exports z dist), nie musisz +ruszać głównego `exports`. -##### Testing +--- -Having a test suite for your plugin is essential to ensure quality and stability. **Vitest** is a fast, modern testing framework that works seamlessly with Vite and supports TypeScript out of the box. +## Droga B — bezpośrednio z repozytorium git -Vitest organizes tests into test suites and cases, similar to other testing frameworks. We recommend creating individual tests based on the expected behavior of your plugin from start to finish. +Bez publikowania. pnpm klonuje repo i bierze zacommitowany `dist`. -Writing tests with Vitest is very straightforward, and you can learn more about how it works in the [Vitest documentation.](https://vitest.dev/) +### Uwierzytelnienie -For this template, we stubbed out `int.spec.ts` in the `dev` folder where you can write your tests. +Serwer prywatny, więc git musi mieć dostęp. Dwie opcje: -```ts -describe('Plugin tests', () => { - // Create tests to ensure expected behavior from the plugin - it('some condition that must be met', () => { - // Write your test logic here - expect(...) - }) -}) +**SSH** (jeśli masz klucz w Gitea): +```bash +pnpm add git+ssh://git@git.intecion.net:IntecionSoftware/ipal-kit.git ``` -## Best practices +**HTTPS z tokenem**: +```bash +pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git +``` -With this tutorial and the plugin template, you should have everything you need to start building your own plugin. -In addition to the setup, here are other best practices aim we follow: +Konkretny tag (stabilniej niż główny branch): +```bash +pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0 +``` -- **Providing an enable / disable option:** For a better user experience, provide a way to disable the plugin without uninstalling it. This is especially important if your plugin adds additional webpack aliases, this will allow you to still let the webpack run to prevent errors. -- **Include tests in your GitHub CI workflow**: If you’ve configured tests for your package, integrate them into your workflow to run the tests each time you commit to the plugin repository. Learn more about [how to configure tests into your GitHub CI workflow.](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs) -- **Publish your finished plugin to NPM**: The best way to share and allow others to use your plugin once it is complete is to publish an NPM package. This process is straightforward and well documented, find out more [creating and publishing a NPM package here.](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/). -- **Add payload-plugin topic tag**: Apply the tag **payload-plugin **to your GitHub repository. This will boost the visibility of your plugin and ensure it gets listed with [existing payload plugins](https://github.com/topics/payload-plugin). -- **Use [Semantic Versioning](https://semver.org/) (SemVar)** - With the SemVar system you release version numbers that reflect the nature of changes (major, minor, patch). Ensure all major versions reference their Payload compatibility. +> Nie ma skrótu `gitea:` (jak `github:`). Zawsze pełny URL `git+https://` lub +> `git+ssh://`. -# Questions +### Wymagania po stronie repo (dla wydającego) -Please contact [Payload](mailto:dev@payloadcms.com) with any questions about using this plugin template. +Instalacja z git NIE buduje pakietu, więc: +- **`dist/` musi być zacommitowany** — zbuduj i zacommituj przed każdym wydaniem +- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować + i żąda `onlyBuiltDependencies` +- **główny `exports` wskazuje `dist`** (nie `src`) — instalacja z git czyta + główny exports, `publishConfig` jest ignorowane przy git + +--- + +## Po instalacji (obie drogi) + +Dodaj peer-zależności — plugin ich nie zaciąga: + +```bash +pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \ + nodemailer lucide-react slugify server-only +``` + +Konfiguracja pluginu, krok po kroku: [docs/getting-started.md](./docs/getting-started.md). + +--- + +## Dokumentacja + +Pełna dokumentacja w [docs/](./docs). Start: +- [docs/getting-started.md](./docs/getting-started.md) — od zera do działającego projektu +- [docs/install.md](./docs/install.md) — szczegóły instalacji i diagnostyka +- [docs/README.md](./docs/README.md) — spis modułów + +--- + +## Diagnostyka instalacji + +| Objaw | Przyczyna | +|---|---| +| `404` / `Unauthorized` przy `pnpm add @intecion/...` | brak/zły token w `.npmrc`, albo brak dostępu do organizacji w Gitea | +| `404` na `git.intecion.net/.../ipal-kit.git` | nie zalogowany / brak tokenu w URL / brak uprawnień do repo | +| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (Droga B) — usuń, `dist` jest w repo | +| `Cannot find module .../src/...ts` | główny `exports` wskazuje src zamiast dist | +| stary kod mimo reinstall | cache; `pnpm store prune && rm -rf .next node_modules/@intecion` | + +Więcej: [docs/install.md](./docs/install.md). \ No newline at end of file From fd1ab5e17e479cc600e4838f7ed97f283ed1d2d9 Mon Sep 17 00:00:00 2001 From: Admin Date: Sun, 2 Aug 2026 21:41:24 +0000 Subject: [PATCH 4/4] Update README.md --- README.md | 193 +++++++++++++++++++++++++++--------------------------- 1 file changed, 96 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index f85d4d3..93973c3 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,159 @@ # @intecion/ipal-kit -Intecion Payload Advanced Library — plugin do Payload CMS 3. Dostarcza i18n -(routing per-locale, hreflang, przełącznik języka), SEO (metadane, canonical, -sitemapa, robots), formularze (Turnstile, rate limit, walidacja), consent mode, -analytics (GA4/GTM), oraz system bloga/archiwów (kolekcje pod stroną-archiwum, -listing, paginacja). +Intecion Payload Advanced Library — a plugin for Payload CMS 3. -Repozytorium: https://git.intecion.net/IntecionSoftware/ipal-kit -(dostęp tylko dla zalogowanych pracowników Intecion). +Provides internationalization (per-locale routing, hreflang, language switcher), +SEO (metadata, canonical, sitemap, robots), forms (Turnstile, rate limiting, +validation), consent management (consent mode), analytics (GA4/GTM), and a +blog/archive system (collections under an archive page, listing, pagination). + +**Repository:** https://git.intecion.net/IntecionSoftware/ipal-kit --- -## Instalacja +## Before you start -> **Serwer jest prywatny.** Zarówno kod, jak i pakiet w Gitea są widoczne tylko -> po zalogowaniu. Każdy sposób instalacji wymaga tokenu dostępu (PAT) z konta -> pracownika. Bez niego instalacja zwróci 404 albo błąd autoryzacji. +The `git.intecion.net` server is internal — you'll only see the code and the +package once you're signed in to your Intecion account. Every installation method +needs your personal access token. Without it you'll get a 404 or an +"Unauthorized" error. -### Krok 1 — token dostępu (raz na osobę) +You generate the token once. It's tied to your account — don't ask anyone for +theirs, and don't put it in any file that ends up in a repository. -W Gitea: **Ustawienia → Aplikacje → Wygeneruj token dostępu**. Nadaj zakresy: -- `read:package` — do instalacji (wystarczy pracownikowi) -- `write:package` — dodatkowo, jeśli będziesz publikować wydania +### Generate a token -Skopiuj token (pokazuje się raz). +1. Sign in to Gitea → click your avatar → **Settings**. +2. **Applications → Generate New Token**. +3. Name it (e.g. `ipal-kit-install`) and select the scope: + - `read:package` — if you only install the plugin in projects, + - `write:package` — additionally, if you'll publish new versions. +4. Click **Generate**. Copy the token now — Gitea shows it only once. -### Krok 2 — wybierz drogę instalacji +### Store the token in your environment -Dwie drogi. **A (rejestr Gitea)** jest zalecana dla zespołu — daje wersjonowanie -i szybką instalację gotowego builda. **B (bezpośrednio z git)** nie wymaga -publikowania, ale buduje/pobiera z repo. +Don't paste the token straight into project files. Keep it in an environment +variable, so your install config carries no secret. + +```bash +# add to ~/.zshrc (or ~/.bashrc) +export GITEA_TOKEN=paste_your_token_here +``` + +Reload your shell (`source ~/.zshrc`) or open a new terminal window. --- -## Droga A — rejestr npm w Gitea (zalecana) +## Installation -Gitea ma wbudowany rejestr npm. Publikujesz zbudowany pakiet, pracownicy pobierają -gotowy `dist` — bez budowania u siebie. +There are two routes. Pick **Route A** if you just want to use the plugin in a +project — it's faster and versioned. Choose **Route B** only when you need a +specific, unreleased commit straight from the repository. -### Konfiguracja u pracownika (instalacja) +### Route A — from the registry (recommended) -`.npmrc` w projekcie **albo** globalnie (`~/.npmrc`): +The plugin is published to the package registry in Gitea. You pull a ready-built +package and build nothing locally. + +**1. Configure the registry.** Create an `.npmrc` file in your project directory +(or add these two lines to `~/.npmrc` to make it work globally): ``` @intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/ //git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} ``` -Token w zmiennej środowiskowej (bezpieczniej niż wpisany wprost — `.npmrc` można -wtedy nawet zacommitować): +Because the token lives in the `${GITEA_TOKEN}` variable, this file holds no +secret — you can safely commit it. -```bash -# ~/.zshrc -export GITEA_TOKEN=twój_token_z_gitea -``` - -Instalacja: +**2. Install:** ```bash pnpm add @intecion/ipal-kit ``` -### Publikacja (osoba wydająca) +### Route B — straight from the repository -W `package.json` pluginu (jest już ustawione): -```json -"publishConfig": { - "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/" -} -``` +pnpm clones the repository and uses the pre-built output. There's no `gitea:` +shorthand — give the full address. -`~/.npmrc` z tokenem `write:package`: -``` -//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} -``` +Over HTTPS with your token: -Wydanie: ```bash -pnpm clean && pnpm build -npm version patch # 1.0.0 → 1.0.1 -npm publish +pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git ``` -Zaleta rejestru: semver — pnpm zawsze widzi nową wersję, koniec z ręcznym -czyszczeniem cache. `publishConfig` działa poprawnie (exports z dist), nie musisz -ruszać głównego `exports`. +Or over SSH, if you have a key added in Gitea: ---- - -## Droga B — bezpośrednio z repozytorium git - -Bez publikowania. pnpm klonuje repo i bierze zacommitowany `dist`. - -### Uwierzytelnienie - -Serwer prywatny, więc git musi mieć dostęp. Dwie opcje: - -**SSH** (jeśli masz klucz w Gitea): ```bash pnpm add git+ssh://git@git.intecion.net:IntecionSoftware/ipal-kit.git ``` -**HTTPS z tokenem**: +Append a specific version after `#` to pin to a release: + ```bash -pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git +pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0 ``` -Konkretny tag (stabilniej niż główny branch): -```bash -pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0 -``` - -> Nie ma skrótu `gitea:` (jak `github:`). Zawsze pełny URL `git+https://` lub -> `git+ssh://`. - -### Wymagania po stronie repo (dla wydającego) - -Instalacja z git NIE buduje pakietu, więc: -- **`dist/` musi być zacommitowany** — zbuduj i zacommituj przed każdym wydaniem -- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować - i żąda `onlyBuiltDependencies` -- **główny `exports` wskazuje `dist`** (nie `src`) — instalacja z git czyta - główny exports, `publishConfig` jest ignorowane przy git - --- -## Po instalacji (obie drogi) +## Finish setting up your project -Dodaj peer-zależności — plugin ich nie zaciąga: +The plugin doesn't pull in the dependencies it shares with Payload — add them +yourself, in a version matching your Payload: ```bash pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \ nodemailer lucide-react slugify server-only ``` -Konfiguracja pluginu, krok po kroku: [docs/getting-started.md](./docs/getting-started.md). +From here, the guide takes over: **[docs/getting-started.md](./docs/getting-started.md)** — +from an empty project to a working site. --- -## Dokumentacja +## Publishing a new version -Pełna dokumentacja w [docs/](./docs). Start: -- [docs/getting-started.md](./docs/getting-started.md) — od zera do działającego projektu -- [docs/install.md](./docs/install.md) — szczegóły instalacji i diagnostyka -- [docs/README.md](./docs/README.md) — spis modułów +This section only applies if you develop the plugin itself and publish new +versions. You'll need a token with the `write:package` scope. + +In `~/.npmrc`: + +``` +//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} +``` + +Build, bump the version number, publish: + +```bash +pnpm clean && pnpm build +npm version patch # 1.0.0 → 1.0.1 +npm publish +``` + +Bump the version on every release — that way pnpm always sees the new package and +nobody gets stuck on a stale one from the cache. --- -## Diagnostyka instalacji +## Documentation -| Objaw | Przyczyna | +Everything lives in the **[docs/](./docs)** directory. To get started: + +- **[getting-started.md](./docs/getting-started.md)** — project setup, step by step +- **[install.md](./docs/install.md)** — more on installation and troubleshooting +- **[README.md](./docs/README.md)** — index of the plugin's modules + +--- + +## Something not working? + +| What you see | What's wrong | |---|---| -| `404` / `Unauthorized` przy `pnpm add @intecion/...` | brak/zły token w `.npmrc`, albo brak dostępu do organizacji w Gitea | -| `404` na `git.intecion.net/.../ipal-kit.git` | nie zalogowany / brak tokenu w URL / brak uprawnień do repo | -| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (Droga B) — usuń, `dist` jest w repo | -| `Cannot find module .../src/...ts` | główny `exports` wskazuje src zamiast dist | -| stary kod mimo reinstall | cache; `pnpm store prune && rm -rf .next node_modules/@intecion` | +| `404` or `Unauthorized` on `pnpm add @intecion/...` | no token in `.npmrc`, a wrong token, or you don't have access to the organization in Gitea | +| `404` when installing from the `.git` address | you're not signed in, the token is missing from the address, or you lack access to the repository | +| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | an attempt to build on install from git — report it to whoever publishes the plugin | +| old code after reinstalling | cache: run `pnpm store prune`, then remove `.next` and `node_modules/@intecion` | -Więcej: [docs/install.md](./docs/install.md). \ No newline at end of file +If you get stuck, check **[docs/install.md](./docs/install.md)** or message the +team that maintains the plugin. \ No newline at end of file